]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it) |
c11b1abf | 2 | .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com> | |
27 | .\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl> | |
28 | .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl> | |
c11b1abf | 29 | .\" Modified 20 Dec 2001, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 30 | .\" Modified 21 Dec 2001, aeb |
c11b1abf | 31 | .\" Modified 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 32 | .\" Added notes on CAP_IPC_OWNER requirement |
c11b1abf | 33 | .\" Modified 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 34 | .\" Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID |
c11b1abf | 35 | .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com> |
70d0e5ef MK |
36 | .\" Language and formatting clean-ups |
37 | .\" Rewrote semun text | |
38 | .\" Added semid_ds and ipc_perm structure definitions | |
24ed820a | 39 | .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions. |
d2ff4f86 | 40 | .\" 2018-03-20, dbueso: Added SEM_STAT_ANY description. |
fea681da | 41 | .\" |
4b8c67d9 | 42 | .TH SEMCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 43 | .SH NAME |
47f065d6 | 44 | semctl \- System V semaphore control operations |
fea681da MK |
45 | .SH SYNOPSIS |
46 | .nf | |
47 | .B #include <sys/types.h> | |
48 | .B #include <sys/ipc.h> | |
49 | .B #include <sys/sem.h> | |
68e4db0a | 50 | .PP |
fea681da MK |
51 | .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" |
52 | .fi | |
53 | .SH DESCRIPTION | |
540036b2 | 54 | .BR semctl () |
fea681da MK |
55 | performs the control operation specified by |
56 | .I cmd | |
efbfd7ec | 57 | on the System\ V semaphore set identified by |
fea681da MK |
58 | .IR semid , |
59 | or on the | |
60 | .IR semnum -th | |
61 | semaphore of that set. | |
70d0e5ef | 62 | (The semaphores in a set are numbered starting at 0.) |
fea681da | 63 | .PP |
70d0e5ef MK |
64 | This function has three or four arguments, depending on |
65 | .IR cmd . | |
66 | When there are four, the fourth has the type | |
67 | .IR "union semun" . | |
68 | The \fIcalling program\fP must define this union as follows: | |
efeece04 | 69 | .PP |
70d0e5ef | 70 | .in +4n |
b8302363 | 71 | .EX |
fea681da | 72 | union semun { |
70d0e5ef MK |
73 | int val; /* Value for SETVAL */ |
74 | struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ | |
75 | unsigned short *array; /* Array for GETALL, SETALL */ | |
c13182ef | 76 | struct seminfo *__buf; /* Buffer for IPC_INFO |
8382f16d | 77 | (Linux-specific) */ |
fea681da | 78 | }; |
b8302363 | 79 | .EE |
e646a1ba | 80 | .in |
fea681da | 81 | .PP |
70d0e5ef MK |
82 | The |
83 | .I semid_ds | |
c84371c6 | 84 | data structure is defined in \fI<sys/sem.h>\fP as follows: |
e646a1ba | 85 | .PP |
70d0e5ef | 86 | .in +4n |
e646a1ba | 87 | .EX |
70d0e5ef | 88 | struct semid_ds { |
45cbde66 | 89 | struct ipc_perm sem_perm; /* Ownership and permissions */ |
70d0e5ef MK |
90 | time_t sem_otime; /* Last semop time */ |
91 | time_t sem_ctime; /* Last change time */ | |
32398a62 | 92 | unsigned long sem_nsems; /* No. of semaphores in set */ |
70d0e5ef | 93 | }; |
b8302363 | 94 | .EE |
e646a1ba | 95 | .in |
70d0e5ef MK |
96 | .PP |
97 | The | |
98 | .I ipc_perm | |
548be2a6 | 99 | structure is defined as follows |
70d0e5ef MK |
100 | (the highlighted fields are settable using |
101 | .BR IPC_SET ): | |
102 | .PP | |
70d0e5ef | 103 | .in +4n |
b8302363 | 104 | .EX |
70d0e5ef | 105 | struct ipc_perm { |
b546318a | 106 | key_t __key; /* Key supplied to semget(2) */ |
58413227 MK |
107 | uid_t \fBuid\fP; /* Effective UID of owner */ |
108 | gid_t \fBgid\fP; /* Effective GID of owner */ | |
109 | uid_t cuid; /* Effective UID of creator */ | |
110 | gid_t cgid; /* Effective GID of creator */ | |
70d0e5ef | 111 | unsigned short \fBmode\fP; /* Permissions */ |
b546318a | 112 | unsigned short __seq; /* Sequence number */ |
70d0e5ef | 113 | }; |
b8302363 | 114 | .EE |
e646a1ba | 115 | .in |
70d0e5ef MK |
116 | .PP |
117 | Valid values for | |
fea681da MK |
118 | .I cmd |
119 | are: | |
f3690310 | 120 | .TP 10 |
fea681da | 121 | .B IPC_STAT |
70d0e5ef MK |
122 | Copy information from the kernel data structure associated with |
123 | .I semid | |
124 | into the | |
125 | .I semid_ds | |
126 | structure pointed to by | |
127 | .IR arg.buf . | |
fea681da MK |
128 | The argument |
129 | .I semnum | |
130 | is ignored. | |
70d0e5ef | 131 | The calling process must have read permission on the semaphore set. |
fea681da MK |
132 | .TP |
133 | .B IPC_SET | |
134 | Write the values of some members of the | |
70d0e5ef | 135 | .I semid_ds |
fea681da | 136 | structure pointed to by |
70d0e5ef MK |
137 | .I arg.buf |
138 | to the kernel data structure associated with this semaphore set, | |
139 | updating also its | |
140 | .I sem_ctime | |
fea681da | 141 | member. |
c13182ef | 142 | The following members of the structure are updated: |
70d0e5ef MK |
143 | .IR sem_perm.uid , |
144 | .IR sem_perm.gid , | |
145 | and (the least significant 9 bits of) | |
146 | .IR sem_perm.mode . | |
147 | The effective UID of the calling process must match the owner | |
148 | .RI ( sem_perm.uid ) | |
c13182ef | 149 | or creator |
70d0e5ef MK |
150 | .RI ( sem_perm.cuid ) |
151 | of the semaphore set, or the caller must be privileged. | |
fea681da MK |
152 | The argument |
153 | .I semnum | |
154 | is ignored. | |
155 | .TP | |
156 | .B IPC_RMID | |
70d0e5ef MK |
157 | Immediately remove the semaphore set, |
158 | awakening all processes blocked in | |
0bfa087b | 159 | .BR semop (2) |
70d0e5ef MK |
160 | calls on the set (with an error return and |
161 | .I errno | |
fea681da MK |
162 | set to |
163 | .BR EIDRM ). | |
499d62f2 | 164 | The effective user ID of the calling process must |
540036b2 MK |
165 | match the creator or owner of the semaphore set, |
166 | or the caller must be privileged. | |
fea681da MK |
167 | The argument |
168 | .I semnum | |
169 | is ignored. | |
170 | .TP | |
8382f16d | 171 | .BR IPC_INFO " (Linux-specific)" |
5fe2d5b7 | 172 | Return information about system-wide semaphore limits and |
24ed820a MK |
173 | parameters in the structure pointed to by |
174 | .IR arg.__buf . | |
175 | This structure is of type | |
176 | .IR seminfo , | |
177 | defined in | |
178 | .I <sys/sem.h> | |
682edefb | 179 | if the |
0daa9e92 | 180 | .B _GNU_SOURCE |
682edefb | 181 | feature test macro is defined: |
e646a1ba | 182 | .IP |
088a639b | 183 | .in +4n |
e646a1ba | 184 | .EX |
24ed820a | 185 | struct seminfo { |
ffc19357 MK |
186 | int semmap; /* Number of entries in semaphore |
187 | map; unused within kernel */ | |
188 | int semmni; /* Maximum number of semaphore sets */ | |
189 | int semmns; /* Maximum number of semaphores in all | |
24ed820a | 190 | semaphore sets */ |
ffc19357 MK |
191 | int semmnu; /* System-wide maximum number of undo |
192 | structures; unused within kernel */ | |
193 | int semmsl; /* Maximum number of semaphores in a | |
194 | set */ | |
195 | int semopm; /* Maximum number of operations for | |
196 | semop(2) */ | |
197 | int semume; /* Maximum number of undo entries per | |
198 | process; unused within kernel */ | |
199 | int semusz; /* Size of struct sem_undo */ | |
24ed820a | 200 | int semvmx; /* Maximum semaphore value */ |
c13182ef | 201 | int semaem; /* Max. value that can be recorded for |
24ed820a MK |
202 | semaphore adjustment (SEM_UNDO) */ |
203 | }; | |
e646a1ba | 204 | .EE |
088a639b | 205 | .in |
e646a1ba | 206 | .IP |
c13182ef | 207 | The |
24ed820a MK |
208 | .IR semmsl , |
209 | .IR semmns , | |
210 | .IR semopm , | |
211 | and | |
212 | .I semmni | |
213 | settings can be changed via | |
214 | .IR /proc/sys/kernel/sem ; | |
215 | see | |
c13182ef | 216 | .BR proc (5) |
24ed820a MK |
217 | for details. |
218 | .TP | |
8382f16d | 219 | .BR SEM_INFO " (Linux-specific)" |
5fe2d5b7 | 220 | Return a |
24ed820a MK |
221 | .I seminfo |
222 | structure containing the same information as for | |
223 | .BR IPC_INFO , | |
c13182ef | 224 | except that the following fields are returned with information |
24ed820a MK |
225 | about system resources consumed by semaphores: the |
226 | .I semusz | |
c13182ef | 227 | field returns the number of semaphore sets that currently exist |
24ed820a MK |
228 | on the system; and the |
229 | .I semaem | |
c13182ef | 230 | field returns the total number of semaphores in all semaphore sets |
24ed820a MK |
231 | on the system. |
232 | .TP | |
8382f16d | 233 | .BR SEM_STAT " (Linux-specific)" |
5fe2d5b7 | 234 | Return a |
c13182ef | 235 | .I semid_ds |
24ed820a MK |
236 | structure as for |
237 | .BR IPC_STAT . | |
238 | However, the | |
239 | .I semid | |
240 | argument is not a semaphore identifier, but instead an index into | |
241 | the kernel's internal array that maintains information about | |
242 | all semaphore sets on the system. | |
243 | .TP | |
f7246c6d | 244 | .BR SEM_STAT_ANY " (Linux-specific, since Linux 4.17)" |
d2ff4f86 DB |
245 | Return a |
246 | .I seminfo | |
247 | structure containing the same information as for | |
248 | .BR SEM_STAT . | |
c020b5a2 | 249 | However, |
d2ff4f86 DB |
250 | .I sem_perm.mode |
251 | is not checked for read access for | |
c020b5a2 MK |
252 | .IR semid |
253 | meaning that any user can employ this operation (just as any user may read | |
254 | .IR /proc/sysvipc/sem | |
255 | to obtain the same information). | |
14cbb25e | 256 | .TP |
fea681da MK |
257 | .B GETALL |
258 | Return | |
259 | .B semval | |
70d0e5ef | 260 | (i.e., the current value) |
fea681da | 261 | for all semaphores of the set into |
d6c57ce6 | 262 | .IR arg.array . |
fea681da MK |
263 | The argument |
264 | .I semnum | |
265 | is ignored. | |
70d0e5ef | 266 | The calling process must have read permission on the semaphore set. |
fea681da MK |
267 | .TP |
268 | .B GETNCNT | |
5fe2d5b7 | 269 | Return the value of |
fea681da | 270 | .B semncnt |