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

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

[Alexander Ofitserov]

Parameter O_NONBLOCK described in man doesn't exist anymore
in kernel versions 3.13+, which is quite old,
only O_TRUNC parameter present for actual kernel version,
O_NONBLOCK does nothing.

Signed-off-by: Alexander Ofitserov <oficerovas@altlinux.org>
---
 man2/delete_module.2 | 57 +++++++++++++-------------------------------
 1 file changed, 17 insertions(+), 40 deletions(-)

diff --git a/man2/delete_module.2 b/man2/delete_module.2
index e9c432e84..bc07d0ce3 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,19 @@ 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 Linux 3.12 and earlier
+In Linux 3.12 and earlier, the system call took two arguments:
+.P
+.BI "   int delete_module(const char *" name ", unsigned int " flags );
+.P
+Parameter
+.I flags
+also can contain 
+.B O_NONBLOCK
+flag in addition to 
+.B O_TRUNC
+flag.
+
 .SS Linux 2.4 and earlier
 In Linux 2.4 and earlier, the system call took only one argument:
 .P
@@ -183,19 +170,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] delete_module.2: Update man to actual syscall behaviour

[G. Branden Robinson]

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

At 2024-02-20T12:21:44+0300, Alexander Ofitserov wrote:
> Parameter O_NONBLOCK described in man doesn't exist anymore in kernel
> versions 3.13+, which is quite old, only O_TRUNC parameter present for
> actual kernel version, O_NONBLOCK does nothing.

Please be aware that "actual" and "aktuell" are false friends in German
and English.  I suspect that you mean "current" here.

https://speakspokehavespoken.com/2020/04/16/15-english-german-false-friends/

Some English speakers will be aware of this usage error, others won't,
and "es kann mach dem irritieren".[1]  ;-)

It can be especially confusing in contexts where something "actual" has
a "virtual" counterpart.

Regards,
Branden

[1] This is bad German.  Do not imitate except for humorous purposes. :P

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

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

[Alejandro Colomar]

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

[Off-topic; just language curiosity; feel free to ignore]

Hi Branden,

On Tue, Feb 20, 2024 at 07:20:15AM -0600, G. Branden Robinson wrote:
> At 2024-02-20T12:21:44+0300, Alexander Ofitserov wrote:
> > Parameter O_NONBLOCK described in man doesn't exist anymore in kernel
> > versions 3.13+, which is quite old, only O_TRUNC parameter present for
> > actual kernel version, O_NONBLOCK does nothing.
> 
> Please be aware that "actual" and "aktuell" are false friends in German
> and English.  I suspect that you mean "current" here.
> 
> https://speakspokehavespoken.com/2020/04/16/15-english-german-false-friends/

That's also taught in Spanish high school.  The Spanish word is "actual"
too, which means current.

However, I found in dictionaries some time ago that English "actual" can
mean Spanish "actual" (i.e., "current", "present").

See some `dict actual` entries:

	From The Collaborative International Dictionary of English v.0.48 [gcide]:

	  Actual \Ac"tu*al\ (#; 135), a. [OE. actuel, F. actuel, L.
	     actualis, fr. agere to do, act.]
	...
	  
	     3. In action at the time being; now exiting; present; as the
		actual situation of the country.
		[1913 Webster]

and

	From WordNet (r) 3.0 (2006) [wn]:

	  actual
	      adj
	...
	      5: being or existing at the present moment; "the ship's actual
		 position is 22 miles due south of Key West"

Some other dictionaries don't acknowledge this meaning, and claim it's
a mistake.  Do you know who is right about it?  I fear some dictionaries
might be ahistorically removing that meaning.  Even if that meaning
wasn't the main one, it probably was correct some time in the future.
I'd like to see some investigation showing history of that meaning
before claiming it's wrong.  I rather call out the Cambridge dictionary
and others as being wrong.

Have a lovely day!
Alex

> 
> Some English speakers will be aware of this usage error, others won't,
> and "es kann mach dem irritieren".[1]  ;-)
> 
> It can be especially confusing in contexts where something "actual" has
> a "virtual" counterpart.
> 
> Regards,
> Branden
> 
> [1] This is bad German.  Do not imitate except for humorous purposes. :P

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

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

[G. Branden Robinson]

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

Hi Alex,

At 2024-02-20T16:24:01+0100, Alejandro Colomar wrote:
> [Off-topic; just language curiosity; feel free to ignore]

[no worries]

> That's also taught in Spanish high school.  The Spanish word is
> "actual" too, which means current.

Oy vey.  I've got more training in Spanish than any other non-English
language, and never hit that one.

I raised this point because it was (mis-)used repeatedly in groff
documentation and I had to clean it up.  It was then that I learned that
this specific solecism is frequent in technical writing where there is
multinational collaboration.

> See some `dict actual` entries:
> 
> 	From The Collaborative International Dictionary of English v.0.48 [gcide]:
> 
> 	  Actual \Ac"tu*al\ (#; 135), a. [OE. actuel, F. actuel, L.
> 	     actualis, fr. agere to do, act.]
> 	...
> 	  
> 	     3. In action at the time being; now exiting; present; as the
> 		actual situation of the country.
> 		[1913 Webster]
> 
> and
> 
> 	From WordNet (r) 3.0 (2006) [wn]:
> 
> 	  actual
> 	      adj
> 	...
> 	      5: being or existing at the present moment; "the ship's actual
> 		 position is 22 miles due south of Key West"
> 
> Some other dictionaries don't acknowledge this meaning, and claim it's
> a mistake.  Do you know who is right about it?  I fear some dictionaries
> might be ahistorically removing that meaning.  Even if that meaning
> wasn't the main one, it probably was correct some time in the future.
> I'd like to see some investigation showing history of that meaning
> before claiming it's wrong.  I rather call out the Cambridge dictionary
> and others as being wrong.

I'm not sufficiently credentialed to argue with published dictionaries,
but I will offer that the use of "present" in these definitions has to
be understood in context, and note should be take of the one we're using
here.  When discussing software, implementations sometimes don't match
specifications--documented behavior may not be reflected in code.

So when we encounter the phrase "in the actual version", one can infer
that a description is being offered in contrast to some non-actual
version; perhaps some change of intention occurred in the passage from
design document or bug report to the code as written.

But, in my experience, most of the time when we see "in the actual
version", all the (typically non-native) speaker is trying to impart is
a temporal statement about the present (or near-present) situation, not
drawing a contrast between intentions elsewhere document and actuality.

Returning to your examples:

> 	     3. In action at the time being; now exiting; present; as the
> 		actual situation of the country.

Contrast:

"The Central Committee of the Communist Party reported that per capita
intake of nutritional calories in Ukraine in 1933 was 13% higher than in
England."

If a historian were to offer some perspective on that claim, their use
of the word "actual" would be contrasting reality with assertion more
strongly than it would be nailing down a temporal datum.

Similarly:

> 	      5: being or existing at the present moment; "the ship's actual
> 		 position is 22 miles due south of Key West"

"The ship's reported position was 5 miles southwest of Bahía de los
Cochinos."

The contrast between "reported" and "actual" here is a more
significant factor than "at the present moment".  Given enough time, a
ship could move from one location to the other, just as an API can
change over time; but when we use "actual", our emphasis is not on
temporal matters even though we often need some temporal information to
decide the truth of a claim.

Does this clarify?

For more along these lines, I highly recommend Jeremy Gardner's document
"Misused English words and expressions in EU Publications".

https://www.eca.europa.eu/other%20publications/en_terminology_publication/en_terminology_publication.pdf

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi Branden,

On Tue, Feb 20, 2024 at 10:36:11AM -0600, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2024-02-20T16:24:01+0100, Alejandro Colomar wrote:
> > [Off-topic; just language curiosity; feel free to ignore]
> 
> [no worries]

I was preventing other innocent readers, who might not be aware of how
much we enjoy such converations.  :)

> > That's also taught in Spanish high school.  The Spanish word is
> > "actual" too, which means current.
> 
> Oy vey.  I've got more training in Spanish than any other non-English
> language, and never hit that one.
> 
> I raised this point because it was (mis-)used repeatedly in groff
> documentation and I had to clean it up.  It was then that I learned that
> this specific solecism is frequent in technical writing where there is
> multinational collaboration.

And you're probably right.

[...]

> > Some other dictionaries don't acknowledge this meaning, and claim it's
> > a mistake.  Do you know who is right about it?  I fear some dictionaries
> > might be ahistorically removing that meaning.  Even if that meaning
> > wasn't the main one, it probably was correct some time in the future.

Huh!  I meant s/future/past/

> > I'd like to see some investigation showing history of that meaning
> > before claiming it's wrong.  I rather call out the Cambridge dictionary
> > and others as being wrong.
> 
> I'm not sufficiently credentialed to argue with published dictionaries,
> but I will offer that the use of "present" in these definitions has to
> be understood in context, and note should be take of the one we're using
> here.  When discussing software, implementations sometimes don't match
> specifications--documented behavior may not be reflected in code.
> 
> So when we encounter the phrase "in the actual version", one can infer
> that a description is being offered in contrast to some non-actual
> version; perhaps some change of intention occurred in the passage from
> design document or bug report to the code as written.
> 
> But, in my experience, most of the time when we see "in the actual
> version", all the (typically non-native) speaker is trying to impart is
> a temporal statement about the present (or near-present) situation, not
> drawing a contrast between intentions elsewhere document and actuality.

Agree.  For documentation, we better write unambiguous English, and not
just correct English.

> 
> Returning to your examples:
> 
> > 	     3. In action at the time being; now exiting; present; as the
> > 		actual situation of the country.
> 
> Contrast:
> 
> "The Central Committee of the Communist Party reported that per capita
> intake of nutritional calories in Ukraine in 1933 was 13% higher than in
> England."
> 
> If a historian were to offer some perspective on that claim, their use
> of the word "actual" would be contrasting reality with assertion more
> strongly than it would be nailing down a temporal datum.
> 
> Similarly:
> 
> > 	      5: being or existing at the present moment; "the ship's actual
> > 		 position is 22 miles due south of Key West"
> 
> "The ship's reported position was 5 miles southwest of Bahía de los
> Cochinos."
> 
> The contrast between "reported" and "actual" here is a more
> significant factor than "at the present moment".  Given enough time, a
> ship could move from one location to the other, just as an API can
> change over time; but when we use "actual", our emphasis is not on
> temporal matters even though we often need some temporal information to
> decide the truth of a claim.
> 
> Does this clarify?

Yup.  "actual" may be actually correct as a synonymous of "current", but
it's more ambiguous actually than it might have been a long time ago, so
we better avoid it in documentation.  :)

Have a lovely day!
Alex

> For more along these lines, I highly recommend Jeremy Gardner's document
> "Misused English words and expressions in EU Publications".
> 
> https://www.eca.europa.eu/other%20publications/en_terminology_publication/en_terminology_publication.pdf
> 
> Regards,
> Branden



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

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

[Dmitry V. Levin]

On Tue, Feb 20, 2024 at 12:21:44PM +0300, Alexander Ofitserov wrote:
> Parameter O_NONBLOCK described in man doesn't exist anymore
> in kernel versions 3.13+, which is quite old,

I suggest mentioning the Linux kernel commit id that removed O_NONBLOCK
support, which seems to be 3f2b9c9cdf389e303b2273679af08aab5f153517
aka v3.13-rc1~83^2~5.

> only O_TRUNC parameter present for actual kernel version,
> O_NONBLOCK does nothing.

While it's vital to document the current kernel behavior,
I wish a description of the historical behavior is also retained.


-- 
ldv

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

[Alejandro Colomar]

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

Hi Dmitry, Alexander,

On Tue, Feb 20, 2024 at 08:18:30PM +0200, Dmitry V. Levin wrote:
> On Tue, Feb 20, 2024 at 12:21:44PM +0300, Alexander Ofitserov wrote:
> > Parameter O_NONBLOCK described in man doesn't exist anymore
> > in kernel versions 3.13+, which is quite old,
> 
> I suggest mentioning the Linux kernel commit id that removed O_NONBLOCK
> support, which seems to be 3f2b9c9cdf389e303b2273679af08aab5f153517
> aka v3.13-rc1~83^2~5.
> 
> > only O_TRUNC parameter present for actual kernel version,
> > O_NONBLOCK does nothing.
> 
> While it's vital to document the current kernel behavior,
> I wish a description of the historical behavior is also retained.

Thanks!  You could describe the old behavior in the HISTORY section.

Have a lovely day!
Alex

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