Re: [PATCH] prctl.2: Fix typo

[Bruno Haible <bruno@clisp.org>]

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

Alejandro Colomar wrote:
> Yes, I don't think it means optional, but rather a choice from all the
> available operations.

IMO, a choice is an "option" only if it is possible to choose none of
the available choices.

> Would you mind checking the
> entire page for those other replacements?

Done: Find attached 0001, which replaces "option" with "operation" in those
places where it denotes the first argument.

Also 0002: a paragraph break was missing in the list of reasons for EINVAL.

I also updated the prototype of this function in IRIX. The IRIX 6.5 header
file in fact does not give a name to the first argument: it declares

  ptrdiff_t prctl(unsigned, ...);

Bruno


[-- Attachment #2: 0001-prctl.2-Use-better-term.patch --]
[-- Type: text/x-patch, Size: 7824 bytes --]

From 8823af7522ea7e9e2e89774e3ce7b33724ba50bf Mon Sep 17 00:00:00 2001
From: Bruno Haible <bruno@clisp.org>
Date: Sun, 29 Oct 2023 21:46:49 +0100
Subject: [PATCH 1/2] prctl.2: Use better term

The first argument of prctl() was denoted as "option" here. This makes
no sense, because
  - The first argument is not optional; it is mandatory.
    A choice is an "option" only if it is possible to choose none of
    the available choices.
  - The title of the page is "operations on a process or thread".

A better term is "operation".
---
 man2/prctl.2 | 88 ++++++++++++++++++++++++++--------------------------
 1 file changed, 44 insertions(+), 44 deletions(-)

diff --git a/man2/prctl.2 b/man2/prctl.2
index f72aeb700..bcda079bb 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -46,7 +46,7 @@ Standard C library
 .nf
 .B #include <sys/prctl.h>
 .PP
-.BI "int prctl(int " option ", ..."
+.BI "int prctl(int " operation ", ..."
 .BI "          \fR/*\fP unsigned long " arg2 ", unsigned long " arg3 ,
 .BI "          unsigned long " arg4 ", unsigned long " arg5 " \fR*/\fP );"
 .fi
@@ -414,7 +414,7 @@ so FPU emulation is not required and the FPU always operates in
 .B FR=1
 mode.
 .IP
-This option is mainly intended for use by the dynamic linker
+This operation is mainly intended for use by the dynamic linker
 .RB ( ld.so (8)).
 .IP
 The arguments
@@ -2096,7 +2096,7 @@ and (if it returns)
 .B PR_GET_SECCOMP
 return the nonnegative values described above.
 All other
-.I option
+.I operation
 values return 0 on success.
 On error, \-1 is returned, and
 .I errno
@@ -2104,7 +2104,7 @@ is set to indicate the error.
 .SH ERRORS
 .TP
 .B EACCES
-.I option
+.I operation
 is
 .B PR_SET_SECCOMP
 and
@@ -2120,7 +2120,7 @@ attribute (see the discussion of
 above).
 .TP
 .B EACCES
-.I option
+.I operation
 is
 .BR PR_SET_MM ,
 and
@@ -2130,7 +2130,7 @@ is
 the file is not executable.
 .TP
 .B EBADF
-.I option
+.I operation
 is
 .BR PR_SET_MM ,
 .I arg3
@@ -2141,7 +2141,7 @@ and the file descriptor passed in
 is not valid.
 .TP
 .B EBUSY
-.I option
+.I operation
 is
 .BR PR_SET_MM ,
 .I arg3
@@ -2156,7 +2156,7 @@ symbolic link, which is prohibited.
 is an invalid address.
 .TP
 .B EFAULT
-.I option
+.I operation
 is
 .BR PR_SET_SECCOMP ,
 .I arg2
@@ -2169,7 +2169,7 @@ and
 is an invalid address.
 .TP
 .B EFAULT
-.I option
+.I operation
 is
 .B PR_SET_SYSCALL_USER_DISPATCH
 and
@@ -2178,12 +2178,12 @@ has an invalid address.
 .TP
 .B EINVAL
 The value of
-.I option
+.I operation
 is not recognized,
 or not supported on this system.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_MCE_KILL
 or
@@ -2197,10 +2197,10 @@ arguments were not specified as zero.
 .B EINVAL
 .I arg2
 is not valid value for this
-.IR option .
+.IR operation .
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_SECCOMP
 or
@@ -2209,7 +2209,7 @@ and the kernel was not configured with
 .BR CONFIG_SECCOMP .
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .BR PR_SET_SECCOMP ,
 .I arg2
@@ -2219,7 +2219,7 @@ and the kernel was not configured with
 .BR CONFIG_SECCOMP_FILTER .
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .BR PR_SET_MM ,
 and one of the following is true
@@ -2259,7 +2259,7 @@ resource limit to be exceeded.
 .RE
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_PTRACER
 and
@@ -2269,7 +2269,7 @@ is not 0,
 or the PID of an existing process.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_PDEATHSIG
 and
@@ -2277,7 +2277,7 @@ and
 is not a valid signal number.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_DUMPABLE
 and
@@ -2288,7 +2288,7 @@ nor
 .BR SUID_DUMP_USER .
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_TIMING
 and
@@ -2297,7 +2297,7 @@ is not
 .BR PR_TIMING_STATISTICAL .
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_NO_NEW_PRIVS
 and
@@ -2311,7 +2311,7 @@ or
 is nonzero.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_GET_NO_NEW_PRIVS
 and
@@ -2323,7 +2323,7 @@ or
 is nonzero.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_THP_DISABLE
 and
@@ -2334,7 +2334,7 @@ or
 is nonzero.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_GET_THP_DISABLE
 and
@@ -2346,7 +2346,7 @@ or
 is nonzero.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_CAP_AMBIENT
 and an unused argument
@@ -2371,7 +2371,7 @@ and
 does not specify a valid capability.
 .TP
 .B EINVAL
-.I option
+.I operation
 was
 .B PR_GET_SPECULATION_CTRL
 or
@@ -2380,7 +2380,7 @@ and unused arguments to
 .BR prctl ()
 are not 0.
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_PAC_RESET_KEYS
 and the arguments are invalid or unsupported.
@@ -2389,7 +2389,7 @@ See the description of
 above for details.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SVE_SET_VL
 and the arguments are invalid or unsupported,
@@ -2399,13 +2399,13 @@ See the description of
 above for details.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SVE_GET_VL
 and SVE is not available on this platform.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_SYSCALL_USER_DISPATCH
 and one of the following is true:
@@ -2427,7 +2427,7 @@ is invalid.
 .RE
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_SET_TAGGED_ADDR_CTRL
 and the arguments are invalid or unsupported.
@@ -2436,7 +2436,7 @@ See the description of
 above for details.
 .TP
 .B EINVAL
-.I option
+.I operation
 is
 .B PR_GET_TAGGED_ADDR_CTRL
 and the arguments are invalid or unsupported.
@@ -2445,13 +2445,13 @@ See the description of
 above for details.
 .TP
 .B ENODEV
-.I option
+.I operation
 was
 .B PR_SET_SPECULATION_CTRL
 the kernel or CPU does not support the requested speculation misfeature.
 .TP
 .B ENXIO
-.I option
+.I operation
 was
 .B PR_MPX_ENABLE_MANAGEMENT
 or
@@ -2460,7 +2460,7 @@ and the kernel or the CPU does not support MPX management.
 Check that the kernel and processor have MPX support.
 .TP
 .B ENXIO
-.I option
+.I operation
 was
 .B PR_SET_SPECULATION_CTRL
 implies that the control of the selected speculation misfeature is not possible.
@@ -2469,7 +2469,7 @@ See
 for the bit fields to determine which option is available.
 .TP
 .B EOPNOTSUPP
-.I option
+.I operation
 is
 .B PR_SET_FP_MODE
 and
@@ -2477,7 +2477,7 @@ and
 has an invalid or unsupported value.
 .TP
 .B EPERM
-.I option
+.I operation
 is
 .BR PR_SET_SECUREBITS ,
 and the caller does not have the
@@ -2489,7 +2489,7 @@ or tried to set a flag whose corresponding locked flag was set
 .BR capabilities (7)).
 .TP
 .B EPERM
-.I option
+.I operation
 is
 .B PR_SET_SPECULATION_CTRL
 wherein the speculation was disabled with
@@ -2497,7 +2497,7 @@ wherein the speculation was disabled with
 and caller tried to enable it again.
 .TP
 .B EPERM
-.I option
+.I operation
 is
 .BR PR_SET_KEEPCAPS ,
 and the caller's
@@ -2507,7 +2507,7 @@ flag is set
 .BR capabilities (7)).
 .TP
 .B EPERM
-.I option
+.I operation
 is
 .BR PR_CAPBSET_DROP ,
 and the caller does not have the
@@ -2515,7 +2515,7 @@ and the caller does not have the
 capability.
 .TP
 .B EPERM
-.I option
+.I operation
 is
 .BR PR_SET_MM ,
 and the caller does not have the
@@ -2523,7 +2523,7 @@ and the caller does not have the
 capability.
 .TP
 .B EPERM
-.I option
+.I operation
 is
 .B PR_CAP_AMBIENT
 and
@@ -2538,7 +2538,7 @@ or the
 securebit has been set.
 .TP
 .B ERANGE
-.I option
+.I operation
 was
 .B PR_SET_SPECULATION_CTRL
 and
@@ -2558,11 +2558,11 @@ with prototype
 .PP
 .in +4n
 .EX
-.BI "ptrdiff_t prctl(int " option ", int " arg2 ", int " arg3 );
+.BI "ptrdiff_t prctl(int " operation ", int " arg2 ", int " arg3 );
 .EE
 .in
 .PP
-and options to get the maximum number of processes per user,
+and operations to get the maximum number of processes per user,
 get the maximum number of processors the calling process can use,
 find out whether a specified process is currently blocked,
 get or set the maximum stack size, and so on.
-- 
2.34.1


[-- Attachment #3: 0002-prctl.2-Add-a-missing-paragraph-break.patch --]
[-- Type: text/x-patch, Size: 581 bytes --]

From d1ae2b0b32e837476467397ce1f9d81e347621da Mon Sep 17 00:00:00 2001
From: Bruno Haible <bruno@clisp.org>
Date: Tue, 31 Oct 2023 18:02:43 +0100
Subject: [PATCH 2/2] prctl.2: Add a missing paragraph break.

A paragraph break was missing in the enumeration of possible reasons for EINVAL.
---
 man2/prctl.2 | 1 +
 1 file changed, 1 insertion(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index bcda079bb..b97f3fb53 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -2379,6 +2379,7 @@ or
 and unused arguments to
 .BR prctl ()
 are not 0.
+.TP
 .B EINVAL
 .I operation
 is
-- 
2.34.1