1SEMCTL(2) Linux Programmer's Manual SEMCTL(2)
2
6 semctl - System V semaphore control operations
7
9 #include <sys/sem.h>
10 int semctl(int semid, int semnum, int cmd, ...);
12
14 semctl() performs the control operation specified by cmd on the Sys‐
15 tem V semaphore set identified by semid, or on the semnum-th semaphore
16 of that set. (The semaphores in a set are numbered starting at 0.)
17 This function has three or four arguments, depending on cmd. When
19 there are four, the fourth has the type union semun. The calling pro‐
20 gram must define this union as follows:
21 union semun {
23 int val; /* Value for SETVAL */
24 struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */
25 unsigned short *array; /* Array for GETALL, SETALL */
26 struct seminfo *__buf; /* Buffer for IPC_INFO
27 (Linux-specific) */
28 };
29 The semid_ds data structure is defined in <sys/sem.h> as follows:
31 struct semid_ds {
33 struct ipc_perm sem_perm; /* Ownership and permissions */
34 time_t sem_otime; /* Last semop time */
35 time_t sem_ctime; /* Creation time/time of last
36 modification via semctl() */
37 unsigned long sem_nsems; /* No. of semaphores in set */
38 };
39 The fields of the semid_ds structure are as follows:
41 sem_perm This is an ipc_perm structure (see below) that specifies the
43 access permissions on the semaphore set.
44 sem_otime Time of last semop(2) system call.
46 sem_ctime Time of creation of semaphore set or time of last semctl()
48 IPCSET, SETVAL, or SETALL operation.
49 sem_nsems Number of semaphores in the set. Each semaphore of the set
51 is referenced by a nonnegative integer ranging from 0 to
52 sem_nsems-1.
53 The ipc_perm structure is defined as follows (the highlighted fields
55 are settable using IPC_SET):
56 struct ipc_perm {
58 key_t __key; /* Key supplied to semget(2) */
59 uid_t uid; /* Effective UID of owner */
60 gid_t gid; /* Effective GID of owner */
61 uid_t cuid; /* Effective UID of creator */
62 gid_t cgid; /* Effective GID of creator */
63 unsigned short mode; /* Permissions */
64 unsigned short __seq; /* Sequence number */
65 };
66 The least significant 9 bits of the mode field of the ipc_perm struc‐
68 ture define the access permissions for the shared memory segment. The
69 permission bits are as follows:
70 0400 Read by user
72 0200 Write by user
73 0040 Read by group
74 0020 Write by group
75 0004 Read by others
76 0002 Write by others
77 In effect, "write" means "alter" for a semaphore set. Bits 0100, 0010,
79 and 0001 (the execute bits) are unused by the system.
80 Valid values for cmd are:
82 IPC_STAT
84 Copy information from the kernel data structure associated with
85 semid into the semid_ds structure pointed to by arg.buf. The
86 argument semnum is ignored. The calling process must have read
87 permission on the semaphore set.
88 IPC_SET
90 Write the values of some members of the semid_ds structure
91 pointed to by arg.buf to the kernel data structure associated
92 with this semaphore set, updating also its sem_ctime member.
93 The following members of the structure are updated:
95 sem_perm.uid, sem_perm.gid, and (the least significant 9 bits
96 of) sem_perm.mode.
97 The effective UID of the calling process must match the owner
99 (sem_perm.uid) or creator (sem_perm.cuid) of the semaphore set,
100 or the caller must be privileged. The argument semnum is ig‐
101 nored.
102 IPC_RMID
104 Immediately remove the semaphore set, awakening all processes
105 blocked in semop(2) calls on the set (with an error return and
106 errno set to EIDRM). The effective user ID of the calling
107 process must match the creator or owner of the semaphore set, or
108 the caller must be privileged. The argument semnum is ignored.
109 IPC_INFO (Linux-specific)
111 Return information about system-wide semaphore limits and param‐
112 eters in the structure pointed to by arg.__buf. This structure
113 is of type seminfo, defined in <sys/sem.h> if the _GNU_SOURCE
114 feature test macro is defined:
115 struct seminfo {
117 int semmap; /* Number of entries in semaphore
118 map; unused within kernel */
119 int semmni; /* Maximum number of semaphore sets */
120 int semmns; /* Maximum number of semaphores in all
121 semaphore sets */
122 int semmnu; /* System-wide maximum number of undo
123 structures; unused within kernel */
124 int semmsl; /* Maximum number of semaphores in a
125 set */
126 int semopm; /* Maximum number of operations for
127 semop(2) */
128 int semume; /* Maximum number of undo entries per
129 process; unused within kernel */
130 int semusz; /* Size of struct sem_undo */
131 int semvmx; /* Maximum semaphore value */
132 int semaem; /* Max. value that can be recorded for
133 semaphore adjustment (SEM_UNDO) */
134 };
135 The semmsl, semmns, semopm, and semmni settings can be changed
137 via /proc/sys/kernel/sem; see proc(5) for details.
138 SEM_INFO (Linux-specific)
140 Return a seminfo structure containing the same information as
141 for IPC_INFO, except that the following fields are returned with
142 information about system resources consumed by semaphores: the
143 semusz field returns the number of semaphore sets that currently
144 exist on the system; and the semaem field returns the total num‐
145 ber of semaphores in all semaphore sets on the system.
146 SEM_STAT (Linux-specific)
148 Return a semid_ds structure as for IPC_STAT. However, the semid
149 argument is not a semaphore identifier, but instead an index
150 into the kernel's internal array that maintains information
151 about all semaphore sets on the system.
152 SEM_STAT_ANY (Linux-specific, since Linux 4.17)
154 Return a semid_ds structure as for SEM_STAT. However,
155 sem_perm.mode is not checked for read access for semid meaning
156 that any user can employ this operation (just as any user may
157 read /proc/sysvipc/sem to obtain the same information).
158 GETALL Return semval (i.e., the current value) for all semaphores of
160 the set into arg.array. The argument semnum is ignored. The
161 calling process must have read permission on the semaphore set.
162 GETNCNT
164 Return the semncnt value for the semnum-th semaphore of the set
165 (i.e., the number of processes waiting for the semaphore's value
166 to increase). The calling process must have read permission on
167 the semaphore set.
168 GETPID Return the sempid value for the semnum-th semaphore of the set.
170 This is the PID of the process that last performed an operation
171 on that semaphore (but see NOTES). The calling process must
172 have read permission on the semaphore set.
173 GETVAL Return semval (i.e., the semaphore value) for the semnum-th sem‐
175 aphore of the set. The calling process must have read permis‐
176 sion on the semaphore set.
177 GETZCNT
179 Return the semzcnt value for the semnum-th semaphore of the set
180 (i.e., the number of processes waiting for the semaphore value
181 to become 0). The calling process must have read permission on
182 the semaphore set.
183 SETALL Set the semval values for all semaphores of the set using
185 arg.array, updating also the sem_ctime member of the semid_ds
186 structure associated with the set. Undo entries (see semop(2))
187 are cleared for altered semaphores in all processes. If the
188 changes to semaphore values would permit blocked semop(2) calls
189 in other processes to proceed, then those processes are woken
190 up. The argument semnum is ignored. The calling process must
191 have alter (write) permission on the semaphore set.
192 SETVAL Set the semaphore value (semval) to arg.val for the semnum-th
194 semaphore of the set, updating also the sem_ctime member of the
195 semid_ds structure associated with the set. Undo entries are
196 cleared for altered semaphores in all processes. If the changes
197 to semaphore values would permit blocked semop(2) calls in other
198 processes to proceed, then those processes are woken up. The
199 calling process must have alter permission on the semaphore set.
200
202 On success, semctl() returns a nonnegative value depending on cmd as
203 follows:
204 GETNCNT
206 the value of semncnt.
207 GETPID the value of sempid.
209 GETVAL the value of semval.
211 GETZCNT
213 the value of semzcnt.
214 IPC_INFO
216 the index of the highest used entry in the kernel's internal ar‐
217 ray recording information about all semaphore sets. (This in‐
218 formation can be used with repeated SEM_STAT or SEM_STAT_ANY op‐
219 erations to obtain information about all semaphore sets on the
220 system.)
221 SEM_INFO
223 as for IPC_INFO.
224 SEM_STAT
226 the identifier of the semaphore set whose index was given in
227 semid.
228 SEM_STAT_ANY
230 as for SEM_STAT.
231 All other cmd values return 0 on success.
233 On failure, semctl() returns -1 and sets errno to indicate the error.
235
237 EACCES The argument cmd has one of the values GETALL, GETPID, GETVAL,
238 GETNCNT, GETZCNT, IPC_STAT, SEM_STAT, SEM_STAT_ANY, SETALL, or
239 SETVAL and the calling process does not have the required per‐
240 missions on the semaphore set and does not have the
241 CAP_IPC_OWNER capability in the user namespace that governs its
242 IPC namespace.
243 EFAULT The address pointed to by arg.buf or arg.array isn't accessible.
245 EIDRM The semaphore set was removed.
247 EINVAL Invalid value for cmd or semid. Or: for a SEM_STAT operation,
249 the index value specified in semid referred to an array slot
250 that is currently unused.
251 EPERM The argument cmd has the value IPC_SET or IPC_RMID but the ef‐
253 fective user ID of the calling process is not the creator (as
254 found in sem_perm.cuid) or the owner (as found in sem_perm.uid)
255 of the semaphore set, and the process does not have the
256 CAP_SYS_ADMIN capability.
257 ERANGE The argument cmd has the value SETALL or SETVAL and the value to
259 which semval is to be set (for some semaphore of the set) is
260 less than 0 or greater than the implementation limit SEMVMX.
261
263 POSIX.1-2001, POSIX.1-2008, SVr4.
264 POSIX.1 specifies the sem_nsems field of the semid_ds structure as hav‐
266 ing the type unsigned short, and the field is so defined on most other
267 systems. It was also so defined on Linux 2.2 and earlier, but, since
268 Linux 2.4, the field has the type unsigned long.
269
271 The IPC_INFO, SEM_STAT, and SEM_INFO operations are used by the ipcs(1)
272 program to provide information on allocated resources. In the future
273 these may modified or moved to a /proc filesystem interface.
274 Various fields in a struct semid_ds were typed as short under Linux 2.2
276 and have become long under Linux 2.4. To take advantage of this, a re‐
277 compilation under glibc-2.1.91 or later should suffice. (The kernel
278 distinguishes old and new calls by an IPC_64 flag in cmd.)
279 In some earlier versions of glibc, the semun union was defined in
281 <sys/sem.h>, but POSIX.1 requires that the caller define this union.
282 On versions of glibc where this union is not defined, the macro
283 _SEM_SEMUN_UNDEFINED is defined in <sys/sem.h>.
284 The following system limit on semaphore sets affects a semctl() call:
286 SEMVMX Maximum value for semval: implementation dependent (32767).
288 For greater portability, it is best to always call semctl() with four
290 arguments.
291 The sempid value
293 POSIX.1 defines sempid as the "process ID of [the] last operation" on a
294 semaphore, and explicitly notes that this value is set by a successful
295 semop(2) call, with the implication that no other interface affects the
296 sempid value.
297 While some implementations conform to the behavior specified in
299 POSIX.1, others do not. (The fault here probably lies with POSIX.1
300 inasmuch as it likely failed to capture the full range of existing im‐
301 plementation behaviors.) Various other implementations also update
302 sempid for the other operations that update the value of a semaphore:
303 the SETVAL and SETALL operations, as well as the semaphore adjustments
304 performed on process termination as a consequence of the use of the
305 SEM_UNDO flag (see semop(2)).
306 Linux also updates sempid for SETVAL operations and semaphore adjust‐
308 ments. However, somewhat inconsistently, up to and including Linux
309 4.5, the kernel did not update sempid for SETALL operations. This was
310 rectified in Linux 4.6.
311
313 See shmop(2).
314
316 ipc(2), semget(2), semop(2), capabilities(7), sem_overview(7),
317 sysvipc(7)
318
320 This page is part of release 5.13 of the Linux man-pages project. A
321 description of the project, information about reporting bugs, and the
322 latest version of this page, can be found at
323 https://www.kernel.org/doc/man-pages/.
324Linux 2021-03-22 SEMCTL(2)