.\" 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 2016-10-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
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
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 ,
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
with
.I errno
indicating the error.
-
+.PP
Otherwise, the system call returns a nonnegative value depending on
.I cmd
as follows:
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
.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
.SH CONFORMING TO
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
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
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
Maximum value for
.BR semval :
implementation dependent (32767).
-.LP
+.PP
For greater portability, it is best to always call
.BR semctl ()
with four arguments.
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
.B SEM_UNDO
flag (see
.BR semop (2)).
-
+.PP
Linux also updates
.I sempid
for