|
Packit |
7cfc04 |
.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
|
|
Packit |
7cfc04 |
.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com>
|
|
Packit |
7cfc04 |
.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl>
|
|
Packit |
7cfc04 |
.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
|
|
Packit |
7cfc04 |
.\" Modified 20 Dec 2001, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Modified 21 Dec 2001, aeb
|
|
Packit |
7cfc04 |
.\" Modified 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Added notes on CAP_IPC_OWNER requirement
|
|
Packit |
7cfc04 |
.\" Modified 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
|
|
Packit |
7cfc04 |
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Language and formatting clean-ups
|
|
Packit |
7cfc04 |
.\" Rewrote semun text
|
|
Packit |
7cfc04 |
.\" Added semid_ds and ipc_perm structure definitions
|
|
Packit |
7cfc04 |
.\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH SEMCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
semctl \- System V semaphore control operations
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <sys/types.h>
|
|
Packit |
7cfc04 |
.B #include <sys/ipc.h>
|
|
Packit |
7cfc04 |
.B #include <sys/sem.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);"
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
.BR semctl ()
|
|
Packit |
7cfc04 |
performs the control operation specified by
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
on the System\ V semaphore set identified by
|
|
Packit |
7cfc04 |
.IR semid ,
|
|
Packit |
7cfc04 |
or on the
|
|
Packit |
7cfc04 |
.IR semnum -th
|
|
Packit |
7cfc04 |
semaphore of that set.
|
|
Packit |
7cfc04 |
(The semaphores in a set are numbered starting at 0.)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
This function has three or four arguments, depending on
|
|
Packit |
7cfc04 |
.IR cmd .
|
|
Packit |
7cfc04 |
When there are four, the fourth has the type
|
|
Packit |
7cfc04 |
.IR "union semun" .
|
|
Packit |
7cfc04 |
The \fIcalling program\fP must define this union as follows:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
union semun {
|
|
Packit |
7cfc04 |
int val; /* Value for SETVAL */
|
|
Packit |
7cfc04 |
struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */
|
|
Packit |
7cfc04 |
unsigned short *array; /* Array for GETALL, SETALL */
|
|
Packit |
7cfc04 |
struct seminfo *__buf; /* Buffer for IPC_INFO
|
|
Packit |
7cfc04 |
(Linux-specific) */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I semid_ds
|
|
Packit |
7cfc04 |
data structure is defined in \fI<sys/sem.h>\fP as follows:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct semid_ds {
|
|
Packit |
7cfc04 |
struct ipc_perm sem_perm; /* Ownership and permissions */
|
|
Packit |
7cfc04 |
time_t sem_otime; /* Last semop time */
|
|
Packit |
7cfc04 |
time_t sem_ctime; /* Last change time */
|
|
Packit |
7cfc04 |
unsigned long sem_nsems; /* No. of semaphores in set */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I ipc_perm
|
|
Packit |
7cfc04 |
structure is defined as follows
|
|
Packit |
7cfc04 |
(the highlighted fields are settable using
|
|
Packit |
7cfc04 |
.BR IPC_SET ):
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct ipc_perm {
|
|
Packit |
7cfc04 |
key_t __key; /* Key supplied to semget(2) */
|
|
Packit |
7cfc04 |
uid_t \fBuid\fP; /* Effective UID of owner */
|
|
Packit |
7cfc04 |
gid_t \fBgid\fP; /* Effective GID of owner */
|
|
Packit |
7cfc04 |
uid_t cuid; /* Effective UID of creator */
|
|
Packit |
7cfc04 |
gid_t cgid; /* Effective GID of creator */
|
|
Packit |
7cfc04 |
unsigned short \fBmode\fP; /* Permissions */
|
|
Packit |
7cfc04 |
unsigned short __seq; /* Sequence number */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Valid values for
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
are:
|
|
Packit |
7cfc04 |
.TP 10
|
|
Packit |
7cfc04 |
.B IPC_STAT
|
|
Packit |
7cfc04 |
Copy information from the kernel data structure associated with
|
|
Packit |
7cfc04 |
.I semid
|
|
Packit |
7cfc04 |
into the
|
|
Packit |
7cfc04 |
.I semid_ds
|
|
Packit |
7cfc04 |
structure pointed to by
|
|
Packit |
7cfc04 |
.IR arg.buf .
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I semnum
|
|
Packit |
7cfc04 |
is ignored.
|
|
Packit |
7cfc04 |
The calling process must have read permission on the semaphore set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B IPC_SET
|
|
Packit |
7cfc04 |
Write the values of some members of the
|
|
Packit |
7cfc04 |
.I semid_ds
|
|
Packit |
7cfc04 |
structure pointed to by
|
|
Packit |
7cfc04 |
.I arg.buf
|
|
Packit |
7cfc04 |
to the kernel data structure associated with this semaphore set,
|
|
Packit |
7cfc04 |
updating also its
|
|
Packit |
7cfc04 |
.I sem_ctime
|
|
Packit |
7cfc04 |
member.
|
|
Packit |
7cfc04 |
The following members of the structure are updated:
|
|
Packit |
7cfc04 |
.IR sem_perm.uid ,
|
|
Packit |
7cfc04 |
.IR sem_perm.gid ,
|
|
Packit |
7cfc04 |
and (the least significant 9 bits of)
|
|
Packit |
7cfc04 |
.IR sem_perm.mode .
|
|
Packit |
7cfc04 |
The effective UID of the calling process must match the owner
|
|
Packit |
7cfc04 |
.RI ( sem_perm.uid )
|
|
Packit |
7cfc04 |
or creator
|
|
Packit |
7cfc04 |
.RI ( sem_perm.cuid )
|
|
Packit |
7cfc04 |
of the semaphore set, or the caller must be privileged.
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I semnum
|
|
Packit |
7cfc04 |
is ignored.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B IPC_RMID
|
|
Packit |
7cfc04 |
Immediately remove the semaphore set,
|
|
Packit |
7cfc04 |
awakening all processes blocked in
|
|
Packit |
7cfc04 |
.BR semop (2)
|
|
Packit |
7cfc04 |
calls on the set (with an error return and
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
set to
|
|
Packit |
7cfc04 |
.BR EIDRM ).
|
|
Packit |
7cfc04 |
The effective user ID of the calling process must
|
|
Packit |
7cfc04 |
match the creator or owner of the semaphore set,
|
|
Packit |
7cfc04 |
or the caller must be privileged.
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I semnum
|
|
Packit |
7cfc04 |
is ignored.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR IPC_INFO " (Linux-specific)"
|
|
Packit |
7cfc04 |
Return information about system-wide semaphore limits and
|
|
Packit |
7cfc04 |
parameters in the structure pointed to by
|
|
Packit |
7cfc04 |
.IR arg.__buf .
|
|
Packit |
7cfc04 |
This structure is of type
|
|
Packit |
7cfc04 |
.IR seminfo ,
|
|
Packit |
7cfc04 |
defined in
|
|
Packit |
7cfc04 |
.I <sys/sem.h>
|
|
Packit |
7cfc04 |
if the
|
|
Packit |
7cfc04 |
.B _GNU_SOURCE
|
|
Packit |
7cfc04 |
feature test macro is defined:
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct seminfo {
|
|
Packit |
7cfc04 |
int semmap; /* Number of entries in semaphore
|
|
Packit |
7cfc04 |
map; unused within kernel */
|
|
Packit |
7cfc04 |
int semmni; /* Maximum number of semaphore sets */
|
|
Packit |
7cfc04 |
int semmns; /* Maximum number of semaphores in all
|
|
Packit |
7cfc04 |
semaphore sets */
|
|
Packit |
7cfc04 |
int semmnu; /* System-wide maximum number of undo
|
|
Packit |
7cfc04 |
structures; unused within kernel */
|
|
Packit |
7cfc04 |
int semmsl; /* Maximum number of semaphores in a
|
|
Packit |
7cfc04 |
set */
|
|
Packit |
7cfc04 |
int semopm; /* Maximum number of operations for
|
|
Packit |
7cfc04 |
semop(2) */
|
|
Packit |
7cfc04 |
int semume; /* Maximum number of undo entries per
|
|
Packit |
7cfc04 |
process; unused within kernel */
|
|
Packit |
7cfc04 |
int semusz; /* Size of struct sem_undo */
|
|
Packit |
7cfc04 |
int semvmx; /* Maximum semaphore value */
|
|
Packit |
7cfc04 |
int semaem; /* Max. value that can be recorded for
|
|
Packit |
7cfc04 |
semaphore adjustment (SEM_UNDO) */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR semmsl ,
|
|
Packit |
7cfc04 |
.IR semmns ,
|
|
Packit |
7cfc04 |
.IR semopm ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I semmni
|
|
Packit |
7cfc04 |
settings can be changed via
|
|
Packit |
7cfc04 |
.IR /proc/sys/kernel/sem ;
|
|
Packit |
7cfc04 |
see
|
|
Packit |
7cfc04 |
.BR proc (5)
|
|
Packit |
7cfc04 |
for details.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR SEM_INFO " (Linux-specific)"
|
|
Packit |
7cfc04 |
Return a
|
|
Packit |
7cfc04 |
.I seminfo
|
|
Packit |
7cfc04 |
structure containing the same information as for
|
|
Packit |
7cfc04 |
.BR IPC_INFO ,
|
|
Packit |
7cfc04 |
except that the following fields are returned with information
|
|
Packit |
7cfc04 |
about system resources consumed by semaphores: the
|
|
Packit |
7cfc04 |
.I semusz
|
|
Packit |
7cfc04 |
field returns the number of semaphore sets that currently exist
|
|
Packit |
7cfc04 |
on the system; and the
|
|
Packit |
7cfc04 |
.I semaem
|
|
Packit |
7cfc04 |
field returns the total number of semaphores in all semaphore sets
|
|
Packit |
7cfc04 |
on the system.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR SEM_STAT " (Linux-specific)"
|
|
Packit |
7cfc04 |
Return a
|
|
Packit |
7cfc04 |
.I semid_ds
|
|
Packit |
7cfc04 |
structure as for
|
|
Packit |
7cfc04 |
.BR IPC_STAT .
|
|
Packit |
7cfc04 |
However, the
|
|
Packit |
7cfc04 |
.I semid
|
|
Packit |
7cfc04 |
argument is not a semaphore identifier, but instead an index into
|
|
Packit |
7cfc04 |
the kernel's internal array that maintains information about
|
|
Packit |
7cfc04 |
all semaphore sets on the system.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETALL
|
|
Packit |
7cfc04 |
Return
|
|
Packit |
7cfc04 |
.B semval
|
|
Packit |
7cfc04 |
(i.e., the current value)
|
|
Packit |
7cfc04 |
for all semaphores of the set into
|
|
Packit |
7cfc04 |
.IR arg.array .
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I semnum
|
|
Packit |
7cfc04 |
is ignored.
|
|
Packit |
7cfc04 |
The calling process must have read permission on the semaphore set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETNCNT
|
|
Packit |
7cfc04 |
Return the value of
|
|
Packit |
7cfc04 |
.B semncnt
|
|
Packit |
7cfc04 |
for the
|
|
Packit |
7cfc04 |
.IR semnum \-th
|
|
Packit |
7cfc04 |
semaphore of the set
|
|
Packit |
7cfc04 |
(i.e., the number of processes waiting for an increase of
|
|
Packit |
7cfc04 |
.B semval
|
|
Packit |
7cfc04 |
for the
|
|
Packit |
7cfc04 |
.IR semnum \-th
|
|
Packit |
7cfc04 |
semaphore of the set).
|
|
Packit |
7cfc04 |
The calling process must have read permission on the semaphore set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETPID
|
|
Packit |
7cfc04 |
Return the value of
|
|
Packit |
7cfc04 |
.B sempid
|
|
Packit |
7cfc04 |
for the
|
|
Packit |
7cfc04 |
.IR semnum \-th
|
|
Packit |
7cfc04 |
semaphore of the set.
|
|
Packit |
7cfc04 |
This is the PID of the process that last performed an operation on
|
|
Packit |
7cfc04 |
that semaphore (but see NOTES).
|
|
Packit |
7cfc04 |
The calling process must have read permission on the semaphore set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETVAL
|
|
Packit |
7cfc04 |
Return the value of
|
|
Packit |
7cfc04 |
.B semval
|
|
Packit |
7cfc04 |
for the
|
|
Packit |
7cfc04 |
.IR semnum \-th
|
|
Packit |
7cfc04 |
semaphore of the set.
|
|
Packit |
7cfc04 |
The calling process must have read permission on the semaphore set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETZCNT
|
|
Packit |
7cfc04 |
Return the value of
|
|
Packit |
7cfc04 |
.B semzcnt
|
|
Packit |
7cfc04 |
for the
|
|
Packit |
7cfc04 |
.IR semnum \-th
|
|
Packit |
7cfc04 |
semaphore of the set
|
|
Packit |
7cfc04 |
(i.e., the number of processes waiting for
|
|
Packit |
7cfc04 |
.B semval
|
|
Packit |
7cfc04 |
of the
|
|
Packit |
7cfc04 |
.IR semnum \-th
|
|
Packit |
7cfc04 |
semaphore of the set to become 0).
|
|
Packit |
7cfc04 |
The calling process must have read permission on the semaphore set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B SETALL
|
|
Packit |
7cfc04 |
Set
|
|
Packit |
7cfc04 |
.B semval
|
|
Packit |
7cfc04 |
for all semaphores of the set using
|
|
Packit |
7cfc04 |
.IR arg.array ,
|
|
Packit |
7cfc04 |
updating also the
|
|
Packit |
7cfc04 |
.I sem_ctime
|
|
Packit |
7cfc04 |
member of the
|
|
Packit |
7cfc04 |
.I semid_ds
|
|
Packit |
7cfc04 |
structure associated with the set.
|
|
Packit |
7cfc04 |
Undo entries (see
|
|
Packit |
7cfc04 |
.BR semop (2))
|
|
Packit |
7cfc04 |
are cleared for altered semaphores in all processes.
|
|
Packit |
7cfc04 |
If the changes to semaphore values would permit blocked
|
|
Packit |
7cfc04 |
.BR semop (2)
|
|
Packit |
7cfc04 |
calls in other processes to proceed, then those processes are woken up.
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I semnum
|
|
Packit |
7cfc04 |
is ignored.
|
|
Packit |
7cfc04 |
The calling process must have alter (write) permission on
|
|
Packit |
7cfc04 |
the semaphore set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B SETVAL
|
|
Packit |
7cfc04 |
Set the value of
|
|
Packit |
7cfc04 |
.B semval
|
|
Packit |
7cfc04 |
to
|
|
Packit |
7cfc04 |
.I arg.val
|
|
Packit |
7cfc04 |
for the
|
|
Packit |
7cfc04 |
.IR semnum \-th
|
|
Packit |
7cfc04 |
semaphore of the set, updating also the
|
|
Packit |
7cfc04 |
.I sem_ctime
|
|
Packit |
7cfc04 |
member of the
|
|
Packit |
7cfc04 |
.I semid_ds
|
|
Packit |
7cfc04 |
structure associated with the set.
|
|
Packit |
7cfc04 |
Undo entries are cleared for altered semaphores in all processes.
|
|
Packit |
7cfc04 |
If the changes to semaphore values would permit blocked
|
|
Packit |
7cfc04 |
.BR semop (2)
|
|
Packit |
7cfc04 |
calls in other processes to proceed, then those processes are woken up.
|
|
Packit |
7cfc04 |
The calling process must have alter permission on the semaphore set.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
On failure,
|
|
Packit |
7cfc04 |
.BR semctl ()
|
|
Packit |
7cfc04 |
returns \-1
|
|
Packit |
7cfc04 |
with
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
indicating the error.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Otherwise, the system call returns a nonnegative value depending on
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
as follows:
|
|
Packit |
7cfc04 |
.TP 10
|
|
Packit |
7cfc04 |
.B GETNCNT
|
|
Packit |
7cfc04 |
the value of
|
|
Packit |
7cfc04 |
.BR semncnt .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETPID
|
|
Packit |
7cfc04 |
the value of
|
|
Packit |
7cfc04 |
.BR sempid .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETVAL
|
|
Packit |
7cfc04 |
the value of
|
|
Packit |
7cfc04 |
.BR semval .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B GETZCNT
|
|
Packit |
7cfc04 |
the value of
|
|
Packit |
7cfc04 |
.BR semzcnt .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B IPC_INFO
|
|
Packit |
7cfc04 |
the index of the highest used entry in the
|
|
Packit |
7cfc04 |
kernel's internal array recording information about all
|
|
Packit |
7cfc04 |
semaphore sets.
|
|
Packit |
7cfc04 |
(This information can be used with repeated
|
|
Packit |
7cfc04 |
.B SEM_STAT
|
|
Packit |
7cfc04 |
operations to obtain information about all semaphore sets on the system.)
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B SEM_INFO
|
|
Packit |
7cfc04 |
as for
|
|
Packit |
7cfc04 |
.BR IPC_INFO .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B SEM_STAT
|
|
Packit |
7cfc04 |
the identifier of the semaphore set whose index was given in
|
|
Packit |
7cfc04 |
.IR semid .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
All other
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
values return 0 on success.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
On failure,
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
will be set to one of the following:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EACCES
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
has one of the values
|
|
Packit |
7cfc04 |
.BR GETALL ,
|
|
Packit |
7cfc04 |
.BR GETPID ,
|
|
Packit |
7cfc04 |
.BR GETVAL ,
|
|
Packit |
7cfc04 |
.BR GETNCNT ,
|
|
Packit |
7cfc04 |
.BR GETZCNT ,
|
|
Packit |
7cfc04 |
.BR IPC_STAT ,
|
|
Packit |
7cfc04 |
.BR SEM_STAT ,
|
|
Packit |
7cfc04 |
.BR SETALL ,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.B SETVAL
|
|
Packit |
7cfc04 |
and the calling process does not have the required
|
|
Packit |
7cfc04 |
permissions on the semaphore set and does not have the
|
|
Packit |
7cfc04 |
.B CAP_IPC_OWNER
|
|
Packit |
7cfc04 |
capability in the user namespace that governs its IPC namespace.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EFAULT
|
|
Packit |
7cfc04 |
The address pointed to by
|
|
Packit |
7cfc04 |
.I arg.buf
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.I arg.array
|
|
Packit |
7cfc04 |
isn't accessible.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EIDRM
|
|
Packit |
7cfc04 |
The semaphore set was removed.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
Invalid value for
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.IR semid .
|
|
Packit |
7cfc04 |
Or: for a
|
|
Packit |
7cfc04 |
.B SEM_STAT
|
|
Packit |
7cfc04 |
operation, the index value specified in
|
|
Packit |
7cfc04 |
.I semid
|
|
Packit |
7cfc04 |
referred to an array slot that is currently unused.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPERM
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
has the value
|
|
Packit |
7cfc04 |
.B IPC_SET
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.B IPC_RMID
|
|
Packit |
7cfc04 |
but the effective user ID of the calling process is not the creator
|
|
Packit |
7cfc04 |
(as found in
|
|
Packit |
7cfc04 |
.IR sem_perm.cuid )
|
|
Packit |
7cfc04 |
or the owner
|
|
Packit |
7cfc04 |
(as found in
|
|
Packit |
7cfc04 |
.IR sem_perm.uid )
|
|
Packit |
7cfc04 |
of the semaphore set,
|
|
Packit |
7cfc04 |
and the process does not have the
|
|
Packit |
7cfc04 |
.B CAP_SYS_ADMIN
|
|
Packit |
7cfc04 |
capability.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ERANGE
|
|
Packit |
7cfc04 |
The argument
|
|
Packit |
7cfc04 |
.I cmd
|
|
Packit |
7cfc04 |
has the value
|
|
Packit |
7cfc04 |
.B SETALL
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.B SETVAL
|
|
Packit |
7cfc04 |
and the value to which
|
|
Packit |
7cfc04 |
.B semval
|
|
Packit |
7cfc04 |
is to be set (for some semaphore of the set) is less than 0
|
|
Packit |
7cfc04 |
or greater than the implementation limit
|
|
Packit |
7cfc04 |
.BR SEMVMX .
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
POSIX.1-2001, POSIX.1-2008, SVr4.
|
|
Packit |
7cfc04 |
.\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
POSIX.1 specifies the
|
|
Packit |
7cfc04 |
.\" POSIX.1-2001, POSIX.1-2008
|
|
Packit |
7cfc04 |
.I sem_nsems
|
|
Packit |
7cfc04 |
field of the
|
|
Packit |
7cfc04 |
.I semid_ds
|
|
Packit |
7cfc04 |
structure as having the type
|
|
Packit |
7cfc04 |
.IR "unsigned\ short" ,
|
|
Packit |
7cfc04 |
and the field is so defined on most other systems.
|
|
Packit |
7cfc04 |
It was also so defined on Linux 2.2 and earlier,
|
|
Packit |
7cfc04 |
but, since Linux 2.4, the field has the type
|
|
Packit |
7cfc04 |
.IR "unsigned\ long" .
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
The inclusion of
|
|
Packit |
7cfc04 |
.I <sys/types.h>
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I <sys/ipc.h>
|
|
Packit |
7cfc04 |
isn't required on Linux or by any version of POSIX.
|
|
Packit |
7cfc04 |
However,
|
|
Packit |
7cfc04 |
some old implementations required the inclusion of these header files,
|
|
Packit |
7cfc04 |
and the SVID also documented their inclusion.
|
|
Packit |
7cfc04 |
Applications intended to be portable to such old systems may need
|
|
Packit |
7cfc04 |
to include these header files.
|
|
Packit |
7cfc04 |
.\" Like Linux, the FreeBSD man pages still document
|
|
Packit |
7cfc04 |
.\" the inclusion of these header files.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR IPC_INFO ,
|
|
Packit |
7cfc04 |
.B SEM_STAT
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B SEM_INFO
|
|
Packit |
7cfc04 |
operations are used by the
|
|
Packit |
7cfc04 |
.BR ipcs (1)
|
|
Packit |
7cfc04 |
program to provide information on allocated resources.
|
|
Packit |
7cfc04 |
In the future these may modified or moved to a
|
|
Packit |
7cfc04 |
.I /proc
|
|
Packit |
7cfc04 |
filesystem interface.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Various fields in a \fIstruct semid_ds\fP were typed as
|
|
Packit |
7cfc04 |
.I short
|
|
Packit |
7cfc04 |
under Linux 2.2
|
|
Packit |
7cfc04 |
and have become
|
|
Packit |
7cfc04 |
.I long
|
|
Packit |
7cfc04 |
under Linux 2.4.
|
|
Packit |
7cfc04 |
To take advantage of this,
|
|
Packit |
7cfc04 |
a recompilation under glibc-2.1.91 or later should suffice.
|
|
Packit |
7cfc04 |
(The kernel distinguishes old and new calls by an
|
|
Packit |
7cfc04 |
.B IPC_64
|
|
Packit |
7cfc04 |
flag in
|
|
Packit |
7cfc04 |
.IR cmd .)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
In some earlier versions of glibc, the
|
|
Packit |
7cfc04 |
.I semun
|
|
Packit |
7cfc04 |
union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires
|
|
Packit |
7cfc04 |
.\" POSIX.1-2001, POSIX.1-2008
|
|
Packit |
7cfc04 |
that the caller define this union.
|
|
Packit |
7cfc04 |
On versions of glibc where this union is \fInot\fP defined,
|
|
Packit |
7cfc04 |
the macro
|
|
Packit |
7cfc04 |
.B _SEM_SEMUN_UNDEFINED
|
|
Packit |
7cfc04 |
is defined in \fI<sys/sem.h>\fP.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The following system limit on semaphore sets affects a
|
|
Packit |
7cfc04 |
.BR semctl ()
|
|
Packit |
7cfc04 |
call:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B SEMVMX
|
|
Packit |
7cfc04 |
Maximum value for
|
|
Packit |
7cfc04 |
.BR semval :
|
|
Packit |
7cfc04 |
implementation dependent (32767).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
For greater portability, it is best to always call
|
|
Packit |
7cfc04 |
.BR semctl ()
|
|
Packit |
7cfc04 |
with four arguments.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.SS The sempid value
|
|
Packit |
7cfc04 |
POSIX.1 defines
|
|
Packit |
7cfc04 |
.I sempid
|
|
Packit |
7cfc04 |
as the "process ID of [the] last operation" on a semaphore,
|
|
Packit |
7cfc04 |
and explicitly notes that this value is set by a successful
|
|
Packit |
7cfc04 |
.BR semop (2)
|
|
Packit |
7cfc04 |
call, with the implication that no other interface affects the
|
|
Packit |
7cfc04 |
.I sempid
|
|
Packit |
7cfc04 |
value.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
While some implementations conform to the behavior specified in POSIX.1,
|
|
Packit |
7cfc04 |
others do not.
|
|
Packit |
7cfc04 |
(The fault here probably lies with POSIX.1 inasmuch as it likely failed
|
|
Packit |
7cfc04 |
to capture the full range of existing implementation behaviors.)
|
|
Packit |
7cfc04 |
Various other implementations
|
|
Packit |
7cfc04 |
.\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin
|
|
Packit |
7cfc04 |
also update
|
|
Packit |
7cfc04 |
.I sempid
|
|
Packit |
7cfc04 |
for the other operations that update the value of a semaphore: the
|
|
Packit |
7cfc04 |
.B SETVAL
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B SETALL
|
|
Packit |
7cfc04 |
operations, as well as the semaphore adjustments performed
|
|
Packit |
7cfc04 |
on process termination as a consequence of the use of the
|
|
Packit |
7cfc04 |
.B SEM_UNDO
|
|
Packit |
7cfc04 |
flag (see
|
|
Packit |
7cfc04 |
.BR semop (2)).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Linux also updates
|
|
Packit |
7cfc04 |
.I sempid
|
|
Packit |
7cfc04 |
for
|
|
Packit |
7cfc04 |
.BR SETVAL
|
|
Packit |
7cfc04 |
operations and semaphore adjustments.
|
|
Packit |
7cfc04 |
However, somewhat inconsistently, up to and including 4.5,
|
|
Packit |
7cfc04 |
Linux did not update
|
|
Packit |
7cfc04 |
.I sempid
|
|
Packit |
7cfc04 |
for
|
|
Packit |
7cfc04 |
.BR SETALL
|
|
Packit |
7cfc04 |
operations.
|
|
Packit |
7cfc04 |
This was rectified
|
|
Packit |
7cfc04 |
.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
|
|
Packit |
7cfc04 |
in Linux 4.6.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR ipc (2),
|
|
Packit |
7cfc04 |
.BR semget (2),
|
|
Packit |
7cfc04 |
.BR semop (2),
|
|
Packit |
7cfc04 |
.BR capabilities (7),
|
|
Packit |
7cfc04 |
.BR sem_overview (7),
|
|
Packit |
7cfc04 |
.BR svipc (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|