]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
11 | .\" | |
12 | .\" Since the Linux kernel and libraries are constantly changing, this | |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
19 | .\" | |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com> | |
24 | .\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl> | |
25 | .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl> | |
305a0578 | 26 | .\" Modified 20 Dec 2001, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 27 | .\" Modified 21 Dec 2001, aeb |
305a0578 | 28 | .\" Modified 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 29 | .\" Added notes on CAP_IPC_OWNER requirement |
305a0578 | 30 | .\" Modified 17 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da | 31 | .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID |
70d0e5ef MK |
32 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
33 | .\" Language and formatting clean-ups | |
34 | .\" Rewrote semun text | |
35 | .\" Added semid_ds and ipc_perm structure definitions | |
fea681da | 36 | .\" |
70d0e5ef | 37 | .TH SEMCTL 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual" |
fea681da MK |
38 | .SH NAME |
39 | semctl \- semaphore control operations | |
40 | .SH SYNOPSIS | |
41 | .nf | |
42 | .B #include <sys/types.h> | |
43 | .B #include <sys/ipc.h> | |
44 | .B #include <sys/sem.h> | |
45 | .sp | |
46 | .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" | |
47 | .fi | |
48 | .SH DESCRIPTION | |
540036b2 | 49 | .BR semctl () |
fea681da MK |
50 | performs the control operation specified by |
51 | .I cmd | |
52 | on the semaphore set identified by | |
53 | .IR semid , | |
54 | or on the | |
55 | .IR semnum -th | |
56 | semaphore of that set. | |
70d0e5ef | 57 | (The semaphores in a set are numbered starting at 0.) |
fea681da | 58 | .PP |
70d0e5ef MK |
59 | This function has three or four arguments, depending on |
60 | .IR cmd . | |
61 | When there are four, the fourth has the type | |
62 | .IR "union semun" . | |
63 | The \fIcalling program\fP must define this union as follows: | |
fea681da MK |
64 | |
65 | .nf | |
70d0e5ef | 66 | .in +4n |
fea681da | 67 | union semun { |
70d0e5ef MK |
68 | int val; /* Value for SETVAL */ |
69 | struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ | |
70 | unsigned short *array; /* Array for GETALL, SETALL */ | |
71 | struct seminfo *__buf; /* Buffer for IPC_INFO | |
72 | (Linux specific) */ | |
fea681da | 73 | }; |
70d0e5ef | 74 | .in -4n |
fea681da MK |
75 | .fi |
76 | .PP | |
70d0e5ef MK |
77 | The |
78 | .I semid_ds | |
79 | data structure is defined in <sys/sem.h> as follows: | |
80 | .nf | |
81 | .in +4n | |
82 | ||
83 | struct semid_ds { | |
84 | struct ipc_perm sem_perm; /* Ownership and permissions | |
85 | time_t sem_otime; /* Last semop time */ | |
86 | time_t sem_ctime; /* Last change time */ | |
87 | unsigned short sem_nsems; /* No. of semaphores in set */ | |
88 | }; | |
89 | .in -4n | |
90 | .fi | |
91 | .PP | |
92 | The | |
93 | .I ipc_perm | |
94 | structure is defined in <sys/ipc.h> as follows | |
95 | (the highlighted fields are settable using | |
96 | .BR IPC_SET ): | |
97 | .PP | |
98 | .nf | |
99 | .in +4n | |
100 | struct ipc_perm { | |
101 | key_t key; /* Key supplied to semget() */ | |
102 | uid_t \fBuid\fP; /* Effective UID of owner */ | |
103 | gid_t \fBgid\fP; /* Effective GID of owner */ | |
104 | uid_t cuid; /* Effective UID of creator */ | |
105 | gid_t cgid; /* Effective GID of creator */ | |
106 | unsigned short \fBmode\fP; /* Permissions */ | |
107 | unsigned short seq; /* Sequence number */ | |
108 | }; | |
109 | .in -4n | |
110 | .fi | |
111 | .PP | |
112 | Valid values for | |
fea681da MK |
113 | .I cmd |
114 | are: | |
115 | .TP 12 | |
116 | .B IPC_STAT | |
70d0e5ef MK |
117 | Copy information from the kernel data structure associated with |
118 | .I semid | |
119 | into the | |
120 | .I semid_ds | |
121 | structure pointed to by | |
122 | .IR arg.buf . | |
fea681da MK |
123 | The argument |
124 | .I semnum | |
125 | is ignored. | |
70d0e5ef | 126 | The calling process must have read permission on the semaphore set. |
fea681da MK |
127 | .TP |
128 | .B IPC_SET | |
129 | Write the values of some members of the | |
70d0e5ef | 130 | .I semid_ds |
fea681da | 131 | structure pointed to by |
70d0e5ef MK |
132 | .I arg.buf |
133 | to the kernel data structure associated with this semaphore set, | |
134 | updating also its | |
135 | .I sem_ctime | |
fea681da | 136 | member. |
70d0e5ef MK |
137 | The following members of the structure are updated: |
138 | .IR sem_perm.uid , | |
139 | .IR sem_perm.gid , | |
140 | and (the least significant 9 bits of) | |
141 | .IR sem_perm.mode . | |
142 | The effective UID of the calling process must match the owner | |
143 | .RI ( sem_perm.uid ) | |
144 | or creator | |
145 | .RI ( sem_perm.cuid ) | |
146 | of the semaphore set, or the caller must be privileged. | |
fea681da MK |
147 | The argument |
148 | .I semnum | |
149 | is ignored. | |
150 | .TP | |
151 | .B IPC_RMID | |
70d0e5ef MK |
152 | Immediately remove the semaphore set, |
153 | awakening all processes blocked in | |
154 | .BR semop () | |
155 | calls on the set (with an error return and | |
156 | .I errno | |
fea681da MK |
157 | set to |
158 | .BR EIDRM ). | |
540036b2 MK |
159 | The effective user\-ID of the calling process must |
160 | match the creator or owner of the semaphore set, | |
161 | or the caller must be privileged. | |
fea681da MK |
162 | The argument |
163 | .I semnum | |
164 | is ignored. | |
165 | .TP | |
166 | .B GETALL | |
167 | Return | |
168 | .B semval | |
70d0e5ef | 169 | (i.e., the current value) |
fea681da | 170 | for all semaphores of the set into |
70d0e5ef | 171 | .IB arg.array . |
fea681da MK |
172 | The argument |
173 | .I semnum | |
174 | is ignored. | |
70d0e5ef | 175 | The calling process must have read permission on the semaphore set. |
fea681da MK |
176 | .TP |
177 | .B GETNCNT | |
178 | The system call returns the value of | |
179 | .B semncnt | |
70d0e5ef MK |
180 | (i.e., the number of processes waiting for the value of |
181 | this semaphore to increase) for the | |
fea681da MK |
182 | .IR semnum \-th |
183 | semaphore of the set | |
184 | (i.e. the number of processes waiting for an increase of | |
185 | .B semval | |
186 | for the | |
187 | .IR semnum \-th | |
188 | semaphore of the set). | |
70d0e5ef | 189 | The calling process must have read permission on the semaphore set. |
fea681da MK |
190 | .TP |
191 | .B GETPID | |
192 | The system call returns the value of | |
193 | .B sempid | |
194 | for the | |
195 | .IR semnum \-th | |
196 | semaphore of the set | |
70d0e5ef MK |
197 | (i.e. the PID of the process that executed the last |
198 | .BR semop () | |
fea681da MK |
199 | call for the |
200 | .IR semnum \-th | |
201 | semaphore of the set). | |
70d0e5ef | 202 | The calling process must have read permission on the semaphore set. |
fea681da MK |
203 | .TP |
204 | .B GETVAL | |
205 | The system call returns the value of | |
206 | .B semval | |
207 | for the | |
208 | .IR semnum \-th | |
209 | semaphore of the set. | |
70d0e5ef | 210 | The calling process must have read permission on the semaphore set. |
fea681da MK |
211 | .TP |
212 | .B GETZCNT | |
213 | The system call returns the value of | |
214 | .B semzcnt | |
70d0e5ef MK |
215 | (i.e., the number of processes waiting for the value of |
216 | this semaphore to become zero) for the | |
fea681da MK |
217 | .IR semnum \-th |
218 | semaphore of the set | |
219 | (i.e. the number of processes waiting for | |
220 | .B semval | |
221 | of the | |
222 | .IR semnum \-th | |
223 | semaphore of the set to become 0). | |
70d0e5ef | 224 | The calling process must have read permission on the semaphore set. |
fea681da MK |
225 | .TP |
226 | .B SETALL | |
227 | Set | |
228 | .B semval | |
229 | for all semaphores of the set using | |
70d0e5ef | 230 | .IB arg.array , |
fea681da | 231 | updating also the |
70d0e5ef | 232 | .I sem_ctime |
fea681da | 233 | member of the |
70d0e5ef MK |
234 | .I semid_ds |
235 | structure associated with the set. | |
236 | Undo entries (see | |
237 | .BR semop (2)) | |
238 | are cleared for altered semaphores in all processes. | |
239 | If the changes to semaphore values would permit blocked | |
240 | .BR semop () | |
241 | calls in other processes to proceed, then those processes are woken up. | |
fea681da MK |
242 | The argument |
243 | .I semnum | |
244 | is ignored. | |
70d0e5ef MK |
245 | The calling process must have alter (write) permission on |
246 | the semaphore set. | |
fea681da MK |
247 | .TP |
248 | .B SETVAL | |
249 | Set the value of | |
250 | .B semval | |
251 | to | |
70d0e5ef | 252 | .IB arg.val |
fea681da MK |
253 | for the |
254 | .IR semnum \-th | |
255 | semaphore of the set, updating also the | |
70d0e5ef | 256 | .I sem_ctime |
fea681da | 257 | member of the |
70d0e5ef MK |
258 | .I semid_ds |
259 | structure associated with the set. | |
fea681da | 260 | Undo entries are cleared for altered semaphores in all processes. |
70d0e5ef MK |
261 | If the changes to semaphore values would permit blocked |
262 | .BR semop () | |
263 | calls in other processes to proceed, then those processes are woken up. | |
264 | The calling process must have alter permission on the semaphore set. | |
fea681da MK |
265 | .SH "RETURN VALUE" |
266 | On failure | |
540036b2 | 267 | .BR semctl () |
70d0e5ef | 268 | returns \-1 |
fea681da | 269 | with |
70d0e5ef | 270 | .I errno |
fea681da MK |
271 | indicating the error. |
272 | Otherwise the system call returns a nonnegative value depending on | |
273 | .I cmd | |
274 | as follows: | |
275 | .TP 11 | |
276 | .B GETNCNT | |
277 | the value of | |
278 | .BR semncnt . | |
279 | .TP | |
280 | .B GETPID | |
281 | the value of | |
282 | .BR sempid . | |
283 | .TP | |
284 | .B GETVAL | |
285 | the value of | |
286 | .BR semval . | |
287 | .TP | |
288 | .B GETZCNT | |
289 | the value of | |
290 | .BR semzcnt . | |
291 | .LP | |
292 | All other | |
293 | .I cmd | |
294 | values return 0 on success. | |
295 | .SH ERRORS | |
296 | On failure, | |
70d0e5ef | 297 | .I errno |
fea681da MK |
298 | will be set to one of the following: |
299 | .TP 11 | |
300 | .B EACCES | |
301 | The argument | |
302 | .I cmd | |
303 | has one of the values | |
304 | .BR GETALL , | |
305 | .BR GETPID , | |
306 | .BR GETVAL , | |
307 | .BR GETNCNT , | |
308 | .BR GETZCNT , | |
309 | .BR IPC_STAT , | |
310 | .BR SEM_STAT , | |
311 | .BR SETALL , | |
312 | or | |
313 | .B SETVAL | |
314 | and the calling process does not have the required | |
315 | permissions on the semaphore set and does not have the | |
316 | .B CAP_IPC_OWNER | |
317 | capability. | |
318 | .TP | |
319 | .B EFAULT | |
320 | The address pointed to by | |
70d0e5ef | 321 | .IB arg.buf |
fea681da | 322 | or |
70d0e5ef | 323 | .IB arg.array |
fea681da MK |
324 | isn't accessible. |
325 | .TP | |
326 | .B EIDRM | |
327 | The semaphore set was removed. | |
328 | .TP | |
329 | .B EINVAL | |
330 | Invalid value for | |
331 | .I cmd | |
332 | or | |
333 | .IR semid . | |
334 | .TP | |
335 | .B EPERM | |
336 | The argument | |
337 | .I cmd | |
70d0e5ef | 338 | has the value |
fea681da MK |
339 | .B IPC_SET |
340 | or | |
341 | .B IPC_RMID | |
70d0e5ef | 342 | but the effective user ID of the calling process is not the creator |
fea681da MK |
343 | (as found in |
344 | .IR sem_perm.cuid ) | |
345 | or the owner | |
346 | (as found in | |
347 | .IR sem_perm.uid ) | |
348 | of the semaphore set, | |
349 | and the process does not have the | |
350 | .B CAP_SYS_ADMIN | |
351 | capability. | |
352 | .TP | |
353 | .B ERANGE | |
354 | The argument | |
355 | .I cmd | |
70d0e5ef | 356 | has the value |
fea681da MK |
357 | .B SETALL |
358 | or | |
359 | .B SETVAL | |
360 | and the value to which | |
361 | .B semval | |
70d0e5ef MK |
362 | is to be set (for some semaphore of the set) is less than 0 |
363 | or greater than the implementation limit | |
fea681da MK |
364 | .BR SEMVMX . |
365 | .SH NOTES | |
366 | The | |
367 | .BR IPC_INFO , | |
368 | .BR SEM_STAT | |
369 | and | |
370 | .B SEM_INFO | |
371 | control calls are used by the | |
372 | .BR ipcs (8) | |
373 | program to provide information on allocated resources. | |
70d0e5ef | 374 | In the future these may modified or moved to a /proc file system |
fea681da MK |
375 | interface. |
376 | .LP | |
377 | Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2 | |
378 | and have become longs under Linux 2.4. To take advantage of this, | |
379 | a recompilation under glibc-2.1.91 or later should suffice. | |
70d0e5ef | 380 | (The kernel distinguishes old and new calls by an IPC_64 flag in |
fea681da MK |
381 | .IR cmd .) |
382 | .PP | |
70d0e5ef MK |
383 | In some earlier versions of glibc, the |
384 | .I semun | |
385 | union was defined in <sys/sem.h>, but POSIX.1-2001 requires | |
386 | that the caller define this union. | |
387 | On versions of glibc where this union is \fInot\fP defined, | |
388 | the macro | |
389 | .B _SEM_SEMUN_UNDEFINED | |
390 | is defined in <sys/sem.h>. | |
391 | .PP | |
fea681da | 392 | The following system limit on semaphore sets affects a |
540036b2 | 393 | .BR semctl () |
fea681da MK |
394 | call: |
395 | .TP 11 | |
396 | .B SEMVMX | |
397 | Maximum value for | |
398 | .BR semval : | |
399 | implementation dependent (32767). | |
400 | .LP | |
401 | For greater portability it is best to always call | |
540036b2 | 402 | .BR semctl () |
fea681da MK |
403 | with four arguments. |
404 | .LP | |
70d0e5ef | 405 | Under Linux, |
540036b2 | 406 | .BR semctl () |
fea681da MK |
407 | is not a system call, but is implemented via the system call |
408 | .BR ipc (2). | |
409 | .SH "CONFORMING TO" | |
410 | SVr4, SVID. SVr4 documents more error conditions EINVAL and EOVERFLOW. | |
411 | .SH "SEE ALSO" | |
412 | .BR ipc (2), | |
413 | .BR semget (2), | |
414 | .BR semop (2), | |
415 | .BR ipc (5), | |
416 | .BR capabilities (7) |