Re: [PATCH v4] delete_module.2: Update man to current syscall behaviour

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 6622 bytes --]

Hi Alexander,

On Tue, Mar 05, 2024 at 10:39:57AM +0300, Alexander Ofitserov wrote:
> Parameter O_NONBLOCK described in man doesn't exist anymore
> in kernel versions 3.13+ (particularly in commit
> 3f2b9c9cdf389e303b2273679af08aab5f153517 aka v3.13-rc1~83^2~5),
> which is quite old, only O_TRUNC parameter present for current kernel version,
> O_NONBLOCK does nothing.
> 
> O_NONBLOCK used in "try_stop_module" function, which is invoked by syscall
> delete_module, here is the code of this function for kernel version 3.12.74:
> https://elixir.bootlin.com/linux/v3.12.74/source/kernel/module.c#L775
> 
> However, in later kernels, this parameter disappeared.
> Also, here is the code for 3.13:
> https://elixir.bootlin.com/linux/v3.13/source/kernel/module.c#L767
> 
> In recent kernels, 6.7.5 for example, this parameter also absent:
> https://elixir.bootlin.com/linux/v6.7.5/source/kernel/module/main.c#L637
> 
> v3 -> v4:
> added more information with links to code to commit message
> 
> v2 -> v3:
> subsection Linux 3.12 and earlier renamed to O_NONBLOCK
> removed info about arguments for kernels 3.12 and earlier
> added semantic newlines
> 
> v1 -> v2:
> added behaviour of syscall for kernel 3.12 and earlier
> in history section
> added commit hash to commit message
> changed word 'actual' to 'current' due to ambigious
> meaning
> 
> Signed-off-by: Alexander Ofitserov <oficerovas@altlinux.org>
> ---
>  man2/delete_module.2 | 92 +++++++++++++++++++++++++-------------------
>  1 file changed, 52 insertions(+), 40 deletions(-)
> 
> diff --git a/man2/delete_module.2 b/man2/delete_module.2
> index e9c432e84..e4b107702 100644
> --- a/man2/delete_module.2
> +++ b/man2/delete_module.2
> @@ -50,42 +50,20 @@ is zero, then the module is immediately unloaded.
>  If a module has a nonzero reference count,
>  then the behavior depends on the bits set in
>  .IR flags .
> -In normal usage (see NOTES), the
> -.B O_NONBLOCK
> -flag is always specified, and the
> +The
>  .B O_TRUNC
>  flag may additionally be specified.
>  .\"  	O_TRUNC == KMOD_REMOVE_FORCE in kmod library
> -.\"  	O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library
>  .IP
>  The various combinations for

"various combinations" is rather confusing, now that there's only one
flag bit, right?

>  .I flags
>  have the following effect:
>  .RS
>  .TP
> -.B flags == O_NONBLOCK
> -The call returns immediately, with an error.
> -.TP
> -.B flags == (O_NONBLOCK | O_TRUNC)
> +.B flags == O_TRUNC
>  The module is unloaded immediately,
>  regardless of whether it has a nonzero reference count.
> -.TP
> -.B (flags & O_NONBLOCK) == 0

Is flags == 0 a possibility?  The rest of the page seems to say so, but
this list of "various combinations" doesn't include it.

> -If
> -.I flags
> -does not specify
> -.BR O_NONBLOCK ,
> -the following steps occur:
>  .RS
> -.IP \[bu] 3
> -The module is marked so that no new references are permitted.
> -.IP \[bu]
> -If the module's reference count is nonzero,
> -the caller is placed in an uninterruptible sleep state
> -.RB ( TASK_UNINTERRUPTIBLE )
> -until the reference count is zero, at which point the call unblocks.
> -.IP \[bu]
> -The module is unloaded in the usual way.
>  .RE
>  .RE
>  .P
> @@ -151,11 +129,7 @@ in
>  .TP
>  .B EWOULDBLOCK
>  Other modules depend on this module;
> -or,

Please keep 'or,' in a separate line.  It reduces the diff, and it
doesn't hurt much.

> -.B O_NONBLOCK
> -was specified in
> -.IR flags ,
> -but the reference count of this module is nonzero and
> +or, the reference count of this module is nonzero and
>  .B O_TRUNC
>  was not specified in
>  .IR flags .
> @@ -172,6 +146,54 @@ it is (before glibc 2.23) sufficient to
>  manually declare the interface in your code;
>  alternatively, you can invoke the system call using
>  .BR syscall (2).
> +.SS O_NONBLOCK
> +In Linux 3.12 and earlier, parameter:

I would  s/ parameter://

> +.I flags
> +also can contain 

There's trailing white-space in some lines.  Don't worry too much about
it; I can remove it while applying.  Just wanted to let you know it's
there.

> +.B O_NONBLOCK
> +flag in addition to 
> +.B O_TRUNC
> +flag.
> +Behavior depends on the bits set in
> +.IR flags .
> +In normal usage (see NOTES), the

You removed NOTES in this commit.  :)

> +.B O_NONBLOCK
> +flag is always specified, and the
> +.B O_TRUNC
> +flag may additionally be specified.
> +.\"  	O_TRUNC == KMOD_REMOVE_FORCE in kmod library
> +.\"  	O_NONBLOCK == KMOD_REMOVE_NOWAIT in kmod library
> +.IP

This should be .P not .IP

It was IP where it was before, because it was a continuation of the
'(3)' bulletted (_i_ndented) paragraph.

> +The various combinations for
> +.I flags
> +have the following effect:
> +.RS

And this .RS/.RE pair should also go away.

Have a lovely day!
Alex

> +.TP
> +.B flags == O_NONBLOCK
> +The call returns immediately, with an error.
> +.TP
> +.B flags == (O_NONBLOCK | O_TRUNC)
> +The module is unloaded immediately,
> +regardless of whether it has a nonzero reference count.
> +.TP
> +.B (flags & O_NONBLOCK) == 0
> +If
> +.I flags
> +does not specify
> +.BR O_NONBLOCK ,
> +the following steps occur:
> +.RS
> +.IP \[bu] 3
> +The module is marked so that no new references are permitted.
> +.IP \[bu]
> +If the module's reference count is nonzero,
> +the caller is placed in an uninterruptible sleep state
> +.RB ( TASK_UNINTERRUPTIBLE )
> +until the reference count is zero, at which point the call unblocks.
> +.IP \[bu]
> +The module is unloaded in the usual way.
> +.RE
> +.RE
>  .SS Linux 2.4 and earlier
>  In Linux 2.4 and earlier, the system call took only one argument:
>  .P
> @@ -183,19 +205,9 @@ is NULL, all unused modules marked auto-clean are removed.
>  .P
>  Some further details of differences in the behavior of
>  .BR delete_module ()
> -in Linux 2.4 and earlier are
> +in Linux 3.12 and earlier are
>  .I not
>  currently explained in this manual page.
> -.SH NOTES
> -The uninterruptible sleep that may occur if
> -.B O_NONBLOCK
> -is omitted from
> -.I flags
> -is considered undesirable, because the sleeping process is left
> -in an unkillable state.
> -As at Linux 3.7, specifying
> -.B O_NONBLOCK
> -is optional, but in future kernels it is likely to become mandatory.
>  .SH SEE ALSO
>  .BR create_module (2),
>  .BR init_module (2),
> -- 
> 2.33.8
> 

-- 
<https://www.alejandro-colomar.es/>
Looking for a remote C programming job at the moment.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]