| .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
| .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| semctl \- System V semaphore control operations |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/ipc.h> |
| .B #include <sys/sem.h> |
| .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 |
| .IR semid , |
| or on the |
| .IR semnum -th |
| semaphore of that set. |
| (The semaphores in a set are numbered starting at 0.) |
| .PP |
| This function has three or four arguments, depending on |
| .IR cmd . |
| When there are four, the fourth has the type |
| .IR "union semun" . |
| The \fIcalling program\fP must define this union as follows: |
| .PP |
| .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 |
| .PP |
| The |
| .I semid_ds |
| data structure is defined in \fI<sys/sem.h>\fP as follows: |
| .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; /* Creation time/time of last |
| modification via semctl() */ |
| unsigned long sem_nsems; /* No. of semaphores in set */ |
| }; |
| .EE |
| .in |
| .PP |
| 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 |
| .BR 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 . |
| .PP |
| The |
| .I ipc_perm |
| structure is defined as follows |
| (the highlighted fields are settable using |
| .BR IPC_SET ): |
| .PP |
| .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 |
| .PP |
| 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 |
| .PP |
| In effect, "write" means "alter" for a semaphore set. |
| Bits 0100, 0010, and 0001 (the execute bits) are unused by the system. |
| .PP |
| Valid values for |
| .I cmd |
| 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 |
| .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 |
| (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 |
| .BR ( 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 cmd |
| 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 . |
| .PP |
| All other |
| .I cmd |
| values return 0 on success. |
| .PP |
| On failure, |
| .BR semctl () |
| returns \-1 and sets |
| .I errno |
| to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| The argument |
| .I cmd |
| 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 cmd |
| 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 cmd |
| 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 cmd |
| 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 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 |
| 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" . |
| .SH NOTES |
| The inclusion of |
| .I <sys/ipc.h> |
| isn't required on Linux or by any version of POSIX. |
| However, |
| some old implementations required the inclusion of this header file, |
| and the SVID also documented its inclusion. |
| Applications intended to be portable to such old systems may need |
| to include this header file. |
| .\" Like Linux, the FreeBSD man pages still document |
| .\" the inclusion of these header files. |
| .PP |
| 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. |
| .PP |
| 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 cmd .) |
| .PP |
| 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. |
| .PP |
| The following system limit on semaphore sets affects a |
| .BR semctl () |
| call: |
| .TP |
| .B SEMVMX |
| Maximum value for |
| .BR semval : |
| implementation dependent (32767). |
| .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 Linux 4.5, |
| the kernel did not update |
| .I sempid |
| for |
| .BR SETALL |
| operations. |
| This was rectified |
| .\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f |
| in Linux 4.6. |
| .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) |