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

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

[Alexander Ofitserov]

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
 .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
-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,
-.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 flags
+also can contain 
+.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
+.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
+The various combinations for
+.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)
+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

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

[Alejandro Colomar]

[-- 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 --]