.\" 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 2013-06-03 "Linux" "Linux Programmer's Manual"
+.TH SEMCTL 2 2019-08-02 "Linux" "Linux Programmer's Manual"
.SH NAME
semctl \- System V semaphore control operations
.SH SYNOPSIS
.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
.BR semctl ()
performs the control operation specified by
.I cmd
-on the System V semaphore set identified by
+on the System\ V semaphore set identified by
.IR semid ,
or on the
.IR semnum -th
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 */
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
(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 */
unsigned short \fBmode\fP; /* Permissions */
unsigned short __seq; /* Sequence number */
};
+.EE
.in
-.fi
.PP
Valid values for
.I cmd
is ignored.
.TP
.BR IPC_INFO " (Linux-specific)"
-Returns information about system-wide semaphore limits and
+Return information about system-wide semaphore limits and
parameters in the structure pointed to by
.IR arg.__buf .
This structure is of type
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 */
int semaem; /* Max. value that can be recorded for
semaphore adjustment (SEM_UNDO) */
};
-
+.EE
.in
-.fi
+.IP
The
.IR semmsl ,
.IR semmns ,
for details.
.TP
.BR SEM_INFO " (Linux-specific)"
-Returns a
+Return a
.I seminfo
structure containing the same information as for
.BR IPC_INFO ,
on the system.
.TP
.BR SEM_STAT " (Linux-specific)"
-Returns a
+Return a
.I semid_ds
structure as for
.BR IPC_STAT .
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
The calling process must have read permission on the semaphore set.
.TP
.B GETNCNT
-The system call returns the value of
+Return the value of
.B semncnt
for the
.IR semnum \-th
The calling process must have read permission on the semaphore set.
.TP
.B GETPID
-The system call returns the value of
+Return the value of
.B sempid
for the
.IR semnum \-th
-semaphore of the set
-(i.e., the PID of the process that executed the last
-.BR semop (2)
-call for the
-.IR semnum \-th
-semaphore of the set).
+semaphore of the set.
+This is the PID of the process that last performed an operation on
+that semaphore (but see NOTES).
The calling process must have read permission on the semaphore set.
.TP
.B GETVAL
-The system call returns the value of
+Return the value of
.B semval
for the
.IR semnum \-th
The calling process must have read permission on the semaphore set.
.TP
.B GETZCNT
-The system call returns the value of
+Return the value of
.B semzcnt
for the
.IR semnum \-th
calls in other processes to proceed, then those processes are woken up.
The calling process must have alter permission on the semaphore set.
.SH RETURN VALUE
-On failure
+On failure,
.BR semctl ()
returns \-1
with
.I errno
indicating the error.
-
-Otherwise the system call returns a nonnegative value depending on
+.PP
+Otherwise, the system call returns a nonnegative value depending on
.I cmd
as follows:
-.TP 12
+.TP 10
.B GETNCNT
the value of
.BR semncnt .
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
-As for
+as for
.BR IPC_INFO .
.TP
.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.
.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
or greater than the implementation limit
.BR SEMVMX .
.SH CONFORMING TO
-SVr4, POSIX.1-2001.
+POSIX.1-2001, POSIX.1-2008, SVr4.
.\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
-
-POSIX.1-2001 specifies the
+.PP
+POSIX.1 specifies the
+.\" POSIX.1-2001, POSIX.1-2008
.I sem_nsems
field of the
.I semid_ds
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
operations are used by the
.BR ipcs (1)
program to provide information on allocated resources.
-In the future these may modified or moved to a /proc filesystem
-interface.
-.LP
+In the future these may modified or moved to a
+.I /proc
+filesystem interface.
+.PP
Various fields in a \fIstruct semid_ds\fP were typed as
.I short
under Linux 2.2
.PP
In some earlier versions of glibc, the
.I semun
-union was defined in \fI<sys/sem.h>\fP, but POSIX.1-2001 requires
+union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires
+.\" POSIX.1-2001, POSIX.1-2008
that the caller define this union.
On versions of glibc where this union is \fInot\fP defined,
the macro
Maximum value for
.BR semval :
implementation dependent (32767).
-.LP
-For greater portability it is best to always call
+.PP
+For greater portability, it is best to always call
.BR semctl ()
with four arguments.
+.\"
+.SS The sempid value
+POSIX.1 defines
+.I sempid
+as the "process ID of [the] last operation" on a semaphore,
+and explicitly notes that this value is set by a successful
+.BR semop (2)
+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
+to capture the full range of existing implementation behaviors.)
+Various other implementations
+.\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin
+also update
+.I sempid
+for the other operations that update the value of a semaphore: the
+.B SETVAL
+and
+.B SETALL
+operations, as well as the semaphore adjustments performed
+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, up to and including 4.5,
+Linux did not update
+.I sempid
+for
+.BR SETALL
+operations.
+This was rectified
+.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
+in Linux 4.6.
.SH SEE ALSO
.BR ipc (2),
.BR semget (2),
.BR semop (2),
.BR capabilities (7),
.BR sem_overview (7),
-.BR svipc (7)
+.BR sysvipc (7)
projects / thirdparty / man-pages.git / blobdiff