Re: [Request for review] Revised delete_module(2) manual page

[Rusty Russell <rusty@rustcorp.com.au>]

"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:

> Hello Kees, Rusty,
>
> The current delete_module(2) page is severely out of date (basically,
> its content corresponds to 2.4 days, and was even pretty thin in
> covering that). So, I took a shot at revising the page to Linux 2.6+
> reality. Would it be possible that you could review it?

OK.  Main suggestion is that I discussed with Lucas removing the
!O_NONBLOCK case.  It's not supported by modprobe -r, and almost
unheard-of for rmmod (it's --wait).

In practice, people want the unload-or-fail semantics, or the
force-unload semantics.

> Otherwise, by default,
> .BR delete_module ()
> marks a module so that no new references are permitted.
> If the module's reference count
> (i.e., the number of processes currently using the module) is nonzero,
> it then places the caller in an uninterruptible sleep
> state until all reference count is zero,
> at which point the call unblocks.
> When the reference count reaches zero, the module is unloaded.

So this should be inverted:

        Otherwise (assuming O_NONBLOCK, see flags below), if the
        module's reference count (i.e., the number of processes
        currently using the module) is nonzero, the call fails.

> The
> .IR flags
> argument can be used to modify the behavior of the system call.

It is usually set to O_NONBLOCK, which may be required in future kernel
versions (see NOTES).

> The following values can be ORed in this argument:
> .TP
> .B O_TRUNC
> .\"  	KMOD_REMOVE_FORCE in kmod library
> Force unloading of the module, even if the following conditions are true:
> .RS
> .IP * 3
> The module has no
> .I exit
> function.
> By default, attempting to unload a module that has no
> .I exit
> function fails.
> .IP *
> The reference count for (i.e., the number of processes currently using)
> this module is nonzero.
...
> .IP
> Using this flag taints the kernel (TAINT_FORCED_RMMOD).
> .IP
> .IR "Using this flag is dangerous!"
> If the kernel was not built with
> .BR CONFIG_MODULE_FORCE_UNLOAD ,
> this flag is silently ignored.

NOTES:

If O_NONBLOCK is not set, then the kernel may enter uninterruptible
sleep until the module reference count reaches zero.  This is not
generally desirable, so this flag may be compulsory in future kernel
configurations.

Cheers,
Rusty.