summaryrefslogtreecommitdiffstats
path: root/man2/semctl.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/semctl.2')
-rw-r--r--man2/semctl.2623
1 files changed, 0 insertions, 623 deletions
diff --git a/man2/semctl.2 b/man2/semctl.2
deleted file mode 100644
index c3724e4..0000000
--- a/man2/semctl.2
+++ /dev/null
@@ -1,623 +0,0 @@
-'\" t
-.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
-.\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com>
-.\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl>
-.\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
-.\" Modified 20 Dec 2001, Michael Kerrisk <mtk.manpages@gmail.com>
-.\" Modified 21 Dec 2001, aeb
-.\" Modified 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
-.\" Added notes on CAP_IPC_OWNER requirement
-.\" Modified 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
-.\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
-.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
-.\" Language and formatting clean-ups
-.\" 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 2024-03-03 "Linux man-pages 6.7"
-.SH NAME
-semctl \- System V semaphore control operations
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <sys/sem.h>
-.P
-.BI "int semctl(int " semid ", int " semnum ", int " op ", ...);"
-.fi
-.SH DESCRIPTION
-.BR semctl ()
-performs the control operation specified by
-.I op
-on the System\ V semaphore set identified by
-.IR semid ,
-or on the
-.IR semnum -th
-semaphore of that set.
-(The semaphores in a set are numbered starting at 0.)
-.P
-This function has three or four arguments, depending on
-.IR op .
-When there are four, the fourth has the type
-.IR "union semun" .
-The \fIcalling program\fP must define this union as follows:
-.P
-.in +4n
-.EX
-union semun {
- int val; /* Value for SETVAL */
- struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */
- unsigned short *array; /* Array for GETALL, SETALL */
- struct seminfo *__buf; /* Buffer for IPC_INFO
- (Linux\-specific) */
-};
-.EE
-.in
-.P
-The
-.I semid_ds
-data structure is defined in \fI<sys/sem.h>\fP as follows:
-.P
-.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; /* Creation time/time of last
- modification via semctl() */
- unsigned long sem_nsems; /* No. of semaphores in set */
-};
-.EE
-.in
-.P
-The fields of the
-.I semid_ds
-structure are as follows:
-.TP 11
-.I sem_perm
-This is an
-.I ipc_perm
-structure (see below) that specifies the access permissions on the semaphore
-set.
-.TP
-.I sem_otime
-Time of last
-.BR semop (2)
-system call.
-.TP
-.I sem_ctime
-Time of creation of semaphore set or time of last
-.BR semctl ()
-.BR IPCSET ,
-.BR SETVAL ,
-or
-.B SETALL
-operation.
-.TP
-.I sem_nsems
-Number of semaphores in the set.
-Each semaphore of the set is referenced by a nonnegative integer
-ranging from
-.B 0
-to
-.IR sem_nsems\-1 .
-.P
-The
-.I ipc_perm
-structure is defined as follows
-(the highlighted fields are settable using
-.BR IPC_SET ):
-.P
-.in +4n
-.EX
-struct ipc_perm {
- key_t __key; /* Key supplied to semget(2) */
- uid_t \fBuid\fP; /* Effective UID of owner */
- gid_t \fBgid\fP; /* Effective GID of owner */
- uid_t cuid; /* Effective UID of creator */
- gid_t cgid; /* Effective GID of creator */
- unsigned short \fBmode\fP; /* Permissions */
- unsigned short __seq; /* Sequence number */
-};
-.EE
-.in
-.P
-The least significant 9 bits of the
-.I mode
-field of the
-.I ipc_perm
-structure define the access permissions for the shared memory segment.
-The permission bits are as follows:
-.TS
-l l.
-0400 Read by user
-0200 Write by user
-0040 Read by group
-0020 Write by group
-0004 Read by others
-0002 Write by others
-.TE
-.P
-In effect, "write" means "alter" for a semaphore set.
-Bits 0100, 0010, and 0001 (the execute bits) are unused by the system.
-.P
-Valid values for
-.I op
-are:
-.TP
-.B IPC_STAT
-Copy information from the kernel data structure associated with
-.I semid
-into the
-.I semid_ds
-structure pointed to by
-.IR arg.buf .
-The argument
-.I semnum
-is ignored.
-The calling process must have read permission on the semaphore set.
-.TP
-.B IPC_SET
-Write the values of some members of the
-.I semid_ds
-structure pointed to by
-.I arg.buf
-to the kernel data structure associated with this semaphore set,
-updating also its
-.I sem_ctime
-member.
-.IP
-The following members of the structure are updated:
-.IR sem_perm.uid ,
-.IR sem_perm.gid ,
-and (the least significant 9 bits of)
-.IR sem_perm.mode .
-.IP
-The effective UID of the calling process must match the owner
-.RI ( sem_perm.uid )
-or creator
-.RI ( sem_perm.cuid )
-of the semaphore set, or the caller must be privileged.
-The argument
-.I semnum
-is ignored.
-.TP
-.B IPC_RMID
-Immediately remove the semaphore set,
-awakening all processes blocked in
-.BR semop (2)
-calls on the set (with an error return and
-.I errno
-set to
-.BR EIDRM ).
-The effective user ID of the calling process must
-match the creator or owner of the semaphore set,
-or the caller must be privileged.
-The argument
-.I semnum
-is ignored.
-.TP
-.BR IPC_INFO " (Linux\-specific)"
-Return information about system-wide semaphore limits and
-parameters in the structure pointed to by
-.IR arg.__buf .
-This structure is of type
-.IR seminfo ,
-defined in
-.I <sys/sem.h>
-if the
-.B _GNU_SOURCE
-feature test macro is defined:
-.IP
-.in +4n
-.EX
-struct seminfo {
- int semmap; /* Number of entries in semaphore
- map; unused within kernel */
- int semmni; /* Maximum number of semaphore sets */
- int semmns; /* Maximum number of semaphores in all
- semaphore sets */
- int semmnu; /* System\-wide maximum number of undo
- structures; unused within kernel */
- int semmsl; /* Maximum number of semaphores in a
- set */
- int semopm; /* Maximum number of operations for
- semop(2) */
- int semume; /* Maximum number of undo entries per
- process; unused within kernel */
- int semusz; /* Size of struct sem_undo */
- int semvmx; /* Maximum semaphore value */
- int semaem; /* Max. value that can be recorded for
- semaphore adjustment (SEM_UNDO) */
-};
-.EE
-.in
-.IP
-The
-.IR semmsl ,
-.IR semmns ,
-.IR semopm ,
-and
-.I semmni
-settings can be changed via
-.IR /proc/sys/kernel/sem ;
-see
-.BR proc (5)
-for details.
-.TP
-.BR SEM_INFO " (Linux-specific)"
-Return a
-.I seminfo
-structure containing the same information as for
-.BR IPC_INFO ,
-except that the following fields are returned with information
-about system resources consumed by semaphores: the
-.I semusz
-field returns the number of semaphore sets that currently exist
-on the system; and the
-.I semaem
-field returns the total number of semaphores in all semaphore sets
-on the system.
-.TP
-.BR SEM_STAT " (Linux-specific)"
-Return a
-.I semid_ds
-structure as for
-.BR IPC_STAT .
-However, the
-.I semid
-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 semid_ds
-structure as for
-.BR SEM_STAT .
-However,
-.I sem_perm.mode
-is not checked for read access for
-.I semid
-meaning that any user can employ this operation (just as any user may read
-.I /proc/sysvipc/sem
-to obtain the same information).
-.TP
-.B GETALL
-Return
-.B semval
-(i.e., the current value)
-for all semaphores of the set into
-.IR arg.array .
-The argument
-.I semnum
-is ignored.
-The calling process must have read permission on the semaphore set.
-.TP
-.B GETNCNT
-Return the
-.B semncnt
-value for the
-.IR semnum \-th
-semaphore of the set
-(i.e., the number of processes waiting for the semaphore's value to increase).
-The calling process must have read permission on the semaphore set.
-.TP
-.B GETPID
-Return the
-.B sempid
-value for the
-.IR semnum \-th
-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
-Return
-.B semval
-(i.e., the semaphore value) for the
-.IR semnum \-th
-semaphore of the set.
-The calling process must have read permission on the semaphore set.
-.TP
-.B GETZCNT
-Return the
-.B semzcnt
-value for the
-.IR semnum \-th
-semaphore of the set
-(i.e., the number of processes waiting for the semaphore value to become 0).
-The calling process must have read permission on the semaphore set.
-.TP
-.B SETALL
-Set the
-.B semval
-values for all semaphores of the set using
-.IR arg.array ,
-updating also the
-.I sem_ctime
-member of the
-.I semid_ds
-structure associated with the set.
-Undo entries (see
-.BR semop (2))
-are cleared for altered semaphores in all processes.
-If the changes to semaphore values would permit blocked
-.BR semop (2)
-calls in other processes to proceed, then those processes are woken up.
-The argument
-.I semnum
-is ignored.
-The calling process must have alter (write) permission on
-the semaphore set.
-.TP
-.B SETVAL
-Set the semaphore value
-.RB ( semval )
-to
-.I arg.val
-for the
-.IR semnum \-th
-semaphore of the set, updating also the
-.I sem_ctime
-member of the
-.I semid_ds
-structure associated with the set.
-Undo entries are cleared for altered semaphores in all processes.
-If the changes to semaphore values would permit blocked
-.BR semop (2)
-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 success,
-.BR semctl ()
-returns a nonnegative value depending on
-.I op
-as follows:
-.TP
-.B GETNCNT
-the value of
-.BR semncnt .
-.TP
-.B GETPID
-the value of
-.BR sempid .
-.TP
-.B GETVAL
-the value of
-.BR semval .
-.TP
-.B GETZCNT
-the value of
-.BR semzcnt .
-.TP
-.B IPC_INFO
-the index of the highest used entry in the
-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
-as for
-.BR IPC_INFO .
-.TP
-.B SEM_STAT
-the identifier of the semaphore set whose index was given in
-.IR semid .
-.TP
-.B SEM_STAT_ANY
-as for
-.BR SEM_STAT .
-.P
-All other
-.I op
-values return 0 on success.
-.P
-On failure,
-.BR semctl ()
-returns \-1 and sets
-.I errno
-to indicate the error.
-.SH ERRORS
-.TP
-.B EACCES
-The argument
-.I op
-has one of the values
-.BR GETALL ,
-.BR GETPID ,
-.BR GETVAL ,
-.BR GETNCNT ,
-.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 in the user namespace that governs its IPC namespace.
-.TP
-.B EFAULT
-The address pointed to by
-.I arg.buf
-or
-.I arg.array
-isn't accessible.
-.TP
-.B EIDRM
-The semaphore set was removed.
-.TP
-.B EINVAL
-Invalid value for
-.I op
-or
-.IR semid .
-Or: for a
-.B SEM_STAT
-operation, the index value specified in
-.I semid
-referred to an array slot that is currently unused.
-.TP
-.B EPERM
-The argument
-.I op
-has the value
-.B IPC_SET
-or
-.B IPC_RMID
-but the effective user ID of the calling process is not the creator
-(as found in
-.IR sem_perm.cuid )
-or the owner
-(as found in
-.IR sem_perm.uid )
-of the semaphore set,
-and the process does not have the
-.B CAP_SYS_ADMIN
-capability.
-.TP
-.B ERANGE
-The argument
-.I op
-has the value
-.B SETALL
-or
-.B SETVAL
-and the value to which
-.B semval
-is to be set (for some semaphore of the set) is less than 0
-or greater than the implementation limit
-.BR SEMVMX .
-.SH VERSIONS
-POSIX.1 specifies the
-.\" POSIX.1-2001, POSIX.1-2008
-.I sem_nsems
-field of the
-.I semid_ds
-structure as having the type
-.IR "unsigned\ short" ,
-and the field is so defined on most other systems.
-It was also so defined on Linux 2.2 and earlier,
-but, since Linux 2.4, the field has the type
-.IR "unsigned\ long" .
-.\"
-.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.
-.P
-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)).
-.P
-Linux also updates
-.I sempid
-for
-.B SETVAL
-operations and semaphore adjustments.
-However, somewhat inconsistently, up to and including Linux 4.5,
-the kernel did not update
-.I sempid
-for
-.B SETALL
-operations.
-This was rectified
-.\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
-in Linux 4.6.
-.SH STANDARDS
-POSIX.1-2008.
-.SH HISTORY
-POSIX.1-2001, SVr4.
-.\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
-.P
-Various fields in a \fIstruct semid_ds\fP were typed as
-.I short
-under Linux 2.2
-and have become
-.I long
-under Linux 2.4.
-To take advantage of this,
-a recompilation under glibc-2.1.91 or later should suffice.
-(The kernel distinguishes old and new calls by an
-.B IPC_64
-flag in
-.IR op .)
-.P
-In some earlier versions of glibc, the
-.I semun
-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
-.B _SEM_SEMUN_UNDEFINED
-is defined in \fI<sys/sem.h>\fP.
-.SH NOTES
-The
-.BR IPC_INFO ,
-.BR SEM_STAT ,
-and
-.B SEM_INFO
-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
-.I /proc
-filesystem interface.
-.P
-The following system limit on semaphore sets affects a
-.BR semctl ()
-call:
-.TP
-.B SEMVMX
-Maximum value for
-.BR semval :
-implementation dependent (32767).
-.P
-For greater portability, it is best to always call
-.BR semctl ()
-with four arguments.
-.SH EXAMPLES
-See
-.BR shmop (2).
-.SH SEE ALSO
-.BR ipc (2),
-.BR semget (2),
-.BR semop (2),
-.BR capabilities (7),
-.BR sem_overview (7),
-.BR sysvipc (7)