Ready for 5.00

[thirdparty/man-pages.git] / man2 / semctl.2

diff --git a/man2/semctl.2 b/man2/semctl.2
index 6fa976c886603484a4024ef279a6dbf10d1104f5..5d0406c6bc846e2753c80173b8ec26ba37a8717f 100644 (file)
--- a/man2/semctl.2
+++ b/man2/semctl.2
@@ -37,8 +37,9 @@
 .\"    Rewrote semun text
 .\"    Added semid_ds and ipc_perm structure definitions
 .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions.
+.\" 2018-03-20, dbueso: Added SEM_STAT_ANY description.
 .\"
-.TH SEMCTL 2 2015-08-08 "Linux" "Linux Programmer's Manual"
+.TH SEMCTL 2 2019-03-06 "Linux" "Linux Programmer's Manual"
 .SH NAME
 semctl \- System V semaphore control operations
 .SH SYNOPSIS
@@ -46,7 +47,7 @@ semctl \- System V semaphore control operations
 .B #include <sys/types.h>
 .B #include <sys/ipc.h>
 .B #include <sys/sem.h>
-.sp
+.PP
 .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);"
 .fi
 .SH DESCRIPTION
@@ -65,9 +66,9 @@ This function has three or four arguments, depending on
 When there are four, the fourth has the type
 .IR "union semun" .
 The \fIcalling program\fP must define this union as follows:
-
-.nf
+.PP
 .in +4n
+.EX
 union semun {
     int              val;    /* Value for SETVAL */
     struct semid_ds *buf;    /* Buffer for IPC_STAT, IPC_SET */
@@ -75,23 +76,23 @@ union semun {
     struct seminfo  *__buf;  /* Buffer for IPC_INFO
                                 (Linux-specific) */
 };
+.EE
 .in
-.fi
 .PP
 The
 .I semid_ds
 data structure is defined in \fI<sys/sem.h>\fP as follows:
-.nf
+.PP
 .in +4n
-
+.EX
 struct semid_ds {
     struct ipc_perm sem_perm;  /* Ownership and permissions */
     time_t          sem_otime; /* Last semop time */
     time_t          sem_ctime; /* Last change time */
     unsigned long   sem_nsems; /* No. of semaphores in set */
 };
+.EE
 .in
-.fi
 .PP
 The
 .I ipc_perm
@@ -99,8 +100,8 @@ structure is defined as follows
 (the highlighted fields are settable using
 .BR IPC_SET ):
 .PP
-.nf
 .in +4n
+.EX
 struct ipc_perm {
     key_t          __key; /* Key supplied to semget(2) */
     uid_t          \fBuid\fP;   /* Effective UID of owner */
@@ -110,8 +111,8 @@ struct ipc_perm {
     unsigned short \fBmode\fP;  /* Permissions */
     unsigned short __seq; /* Sequence number */
 };
+.EE
 .in
-.fi
 .PP
 Valid values for
 .I cmd
@@ -178,9 +179,9 @@ defined in
 if the
 .B _GNU_SOURCE
 feature test macro is defined:
-.nf
+.IP
 .in +4n
-
+.EX
 struct  seminfo {
     int semmap;  /* Number of entries in semaphore
                     map; unused within kernel */
@@ -200,9 +201,9 @@ struct  seminfo {
     int semaem;  /* Max. value that can be recorded for
                     semaphore adjustment (SEM_UNDO) */
 };
-
+.EE
 .in
-.fi
+.IP
 The
 .IR semmsl ,
 .IR semmns ,
@@ -240,6 +241,19 @@ argument is not a semaphore identifier, but instead an index into
 the kernel's internal array that maintains information about
 all semaphore sets on the system.
 .TP
+.BR SEM_STAT_ANY " (Linux-specific, since Linux 4.17)"
+Return a
+.I seminfo
+structure containing the same information as for
+.BR SEM_STAT .
+However,
+.I sem_perm.mode
+is not checked for read access for
+.IR semid
+meaning that any user can employ this operation (just as any user may read
+.IR /proc/sysvipc/sem
+to obtain the same information).
+.TP
 .B GETALL
 Return
 .B semval
@@ -341,7 +355,7 @@ returns \-1
 with
 .I errno
 indicating the error.
-
+.PP
 Otherwise, the system call returns a nonnegative value depending on
 .I cmd
 as follows:
@@ -368,6 +382,8 @@ kernel's internal array recording information about all
 semaphore sets.
 (This information can be used with repeated
 .B SEM_STAT
+or
+.B SEM_STAT_ANY
 operations to obtain information about all semaphore sets on the system.)
 .TP
 .B SEM_INFO
@@ -377,7 +393,11 @@ as for
 .B SEM_STAT
 the identifier of the semaphore set whose index was given in
 .IR semid .
-.LP
+.TP
+.B SEM_STAT_ANY
+as for
+.BR SEM_STAT .
+.PP
 All other
 .I cmd
 values return 0 on success.
@@ -397,13 +417,14 @@ has one of the values
 .BR GETZCNT ,
 .BR IPC_STAT ,
 .BR SEM_STAT ,
+.BR SEM_STAT_ANY ,
 .BR SETALL ,
 or
 .B SETVAL
 and the calling process does not have the required
 permissions on the semaphore set and does not have the
 .B CAP_IPC_OWNER
-capability.
+capability in the user namespace that governs its IPC namespace.
 .TP
 .B EFAULT
 The address pointed to by
@@ -457,9 +478,9 @@ is to be set (for some semaphore of the set) is less than 0
 or greater than the implementation limit
 .BR SEMVMX .
 .SH CONFORMING TO
-POSIX.1-2001, POSIX.1-2001, SVr4.
+POSIX.1-2001, POSIX.1-2008, SVr4.
 .\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
-
+.PP
 POSIX.1 specifies the
 .\" POSIX.1-2001, POSIX.1-2008
 .I sem_nsems
@@ -484,7 +505,7 @@ Applications intended to be portable to such old systems may need
 to include these header files.
 .\" Like Linux, the FreeBSD man pages still document
 .\" the inclusion of these header files.
-
+.PP
 The
 .BR IPC_INFO ,
 .B SEM_STAT
@@ -496,7 +517,7 @@ program to provide information on allocated resources.
 In the future these may modified or moved to a
 .I /proc
 filesystem interface.
-.LP
+.PP
 Various fields in a \fIstruct semid_ds\fP were typed as
 .I short
 under Linux 2.2
@@ -528,7 +549,7 @@ call:
 Maximum value for
 .BR semval :
 implementation dependent (32767).
-.LP
+.PP
 For greater portability, it is best to always call
 .BR semctl ()
 with four arguments.
@@ -542,7 +563,7 @@ and explicitly notes that this value is set by a successful
 call, with the implication that no other interface affects the
 .I sempid
 value.
-
+.PP
 While some implementations conform to the behavior specified in POSIX.1,
 others do not.
 (The fault here probably lies with POSIX.1 inasmuch as it likely failed
@@ -560,21 +581,21 @@ on process termination as a consequence of the use of the
 .B SEM_UNDO
 flag (see
 .BR semop (2)).
-
+.PP
 Linux also updates
 .I sempid
 for
 .BR SETVAL
 operations and semaphore adjustments.
-However, somewhat inconsistently, it does not update
+However, somewhat inconsistently, up to and including 4.5,
+Linux did not update
 .I sempid
 for
 .BR SETALL
 operations.
-While the
-.B SETALL
-behavior might be viewed as a bug, the behavior is longstanding,
-and is probably unlikely to change.
+This was rectified
+.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
+in Linux 4.6.
 .SH SEE ALSO
 .BR ipc (2),
 .BR semget (2),