diff options
Diffstat (limited to 'man2/semctl.2')
| -rw-r--r-- | man2/semctl.2 | 623 |
1 files changed, 0 insertions, 623 deletions
diff --git a/man2/semctl.2 b/man2/semctl.2 deleted file mode 100644 index 243919c73..000000000 --- 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 (date) "Linux man-pages (unreleased)" -.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) |