]>
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. |
fea681da | 40 | .\" |
f6652463 | 41 | .TH SEMCTL 2 2012-05-31 "Linux" "Linux Programmer's Manual" |
fea681da MK |
42 | .SH NAME |
43 | semctl \- semaphore control operations | |
44 | .SH SYNOPSIS | |
45 | .nf | |
46 | .B #include <sys/types.h> | |
47 | .B #include <sys/ipc.h> | |
48 | .B #include <sys/sem.h> | |
49 | .sp | |
50 | .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);" | |
51 | .fi | |
52 | .SH DESCRIPTION | |
540036b2 | 53 | .BR semctl () |
fea681da MK |
54 | performs the control operation specified by |
55 | .I cmd | |
56 | on the semaphore set identified by | |
57 | .IR semid , | |
58 | or on the | |
59 | .IR semnum -th | |
60 | semaphore of that set. | |
70d0e5ef | 61 | (The semaphores in a set are numbered starting at 0.) |
fea681da | 62 | .PP |
70d0e5ef MK |
63 | This function has three or four arguments, depending on |
64 | .IR cmd . | |
65 | When there are four, the fourth has the type | |
66 | .IR "union semun" . | |
67 | The \fIcalling program\fP must define this union as follows: | |
fea681da MK |
68 | |
69 | .nf | |
70d0e5ef | 70 | .in +4n |
fea681da | 71 | union semun { |
70d0e5ef MK |
72 | int val; /* Value for SETVAL */ |
73 | struct semid_ds *buf; /* Buffer for IPC_STAT, IPC_SET */ | |
74 | unsigned short *array; /* Array for GETALL, SETALL */ | |
c13182ef | 75 | struct seminfo *__buf; /* Buffer for IPC_INFO |
8382f16d | 76 | (Linux-specific) */ |
fea681da | 77 | }; |
088a639b | 78 | .in |
fea681da MK |
79 | .fi |
80 | .PP | |
70d0e5ef MK |
81 | The |
82 | .I semid_ds | |
c84371c6 | 83 | data structure is defined in \fI<sys/sem.h>\fP as follows: |
70d0e5ef MK |
84 | .nf |
85 | .in +4n | |
86 | ||
87 | struct semid_ds { | |
45cbde66 | 88 | struct ipc_perm sem_perm; /* Ownership and permissions */ |
70d0e5ef MK |
89 | time_t sem_otime; /* Last semop time */ |
90 | time_t sem_ctime; /* Last change time */ | |
91 | unsigned short sem_nsems; /* No. of semaphores in set */ | |
92 | }; | |
088a639b | 93 | .in |
70d0e5ef MK |
94 | .fi |
95 | .PP | |
96 | The | |
97 | .I ipc_perm | |
548be2a6 | 98 | structure is defined as follows |
70d0e5ef MK |
99 | (the highlighted fields are settable using |
100 | .BR IPC_SET ): | |
101 | .PP | |
102 | .nf | |
103 | .in +4n | |
104 | struct ipc_perm { | |
b546318a | 105 | key_t __key; /* Key supplied to semget(2) */ |
58413227 MK |
106 | uid_t \fBuid\fP; /* Effective UID of owner */ |
107 | gid_t \fBgid\fP; /* Effective GID of owner */ | |
108 | uid_t cuid; /* Effective UID of creator */ | |
109 | gid_t cgid; /* Effective GID of creator */ | |
70d0e5ef | 110 | unsigned short \fBmode\fP; /* Permissions */ |
b546318a | 111 | unsigned short __seq; /* Sequence number */ |
70d0e5ef | 112 | }; |
088a639b | 113 | .in |
70d0e5ef MK |
114 | .fi |
115 | .PP | |
116 | Valid values for | |
fea681da MK |
117 | .I cmd |
118 | are: | |
f3690310 | 119 | .TP 10 |
fea681da | 120 | .B IPC_STAT |
70d0e5ef MK |
121 | Copy information from the kernel data structure associated with |
122 | .I semid | |
123 | into the | |
124 | .I semid_ds | |
125 | structure pointed to by | |
126 | .IR arg.buf . | |
fea681da MK |
127 | The argument |
128 | .I semnum | |
129 | is ignored. | |
70d0e5ef | 130 | The calling process must have read permission on the semaphore set. |
fea681da MK |
131 | .TP |
132 | .B IPC_SET | |
133 | Write the values of some members of the | |
70d0e5ef | 134 | .I semid_ds |
fea681da | 135 | structure pointed to by |
70d0e5ef MK |
136 | .I arg.buf |
137 | to the kernel data structure associated with this semaphore set, | |
138 | updating also its | |
139 | .I sem_ctime | |
fea681da | 140 | member. |
c13182ef | 141 | The following members of the structure are updated: |
70d0e5ef MK |
142 | .IR sem_perm.uid , |
143 | .IR sem_perm.gid , | |
144 | and (the least significant 9 bits of) | |
145 | .IR sem_perm.mode . | |
146 | The effective UID of the calling process must match the owner | |
147 | .RI ( sem_perm.uid ) | |
c13182ef | 148 | or creator |
70d0e5ef MK |
149 | .RI ( sem_perm.cuid ) |
150 | of the semaphore set, or the caller must be privileged. | |
fea681da MK |
151 | The argument |
152 | .I semnum | |
153 | is ignored. | |
154 | .TP | |
155 | .B IPC_RMID | |
70d0e5ef MK |
156 | Immediately remove the semaphore set, |
157 | awakening all processes blocked in | |
0bfa087b | 158 | .BR semop (2) |
70d0e5ef MK |
159 | calls on the set (with an error return and |
160 | .I errno | |
fea681da MK |
161 | set to |
162 | .BR EIDRM ). | |
499d62f2 | 163 | The effective user ID of the calling process must |
540036b2 MK |
164 | match the creator or owner of the semaphore set, |
165 | or the caller must be privileged. | |
fea681da MK |
166 | The argument |
167 | .I semnum | |
168 | is ignored. | |
169 | .TP | |
8382f16d | 170 | .BR IPC_INFO " (Linux-specific)" |
c13182ef | 171 | Returns information about system-wide semaphore limits and |
24ed820a MK |
172 | parameters in the structure pointed to by |
173 | .IR arg.__buf . | |
174 | This structure is of type | |
175 | .IR seminfo , | |
176 | defined in | |
177 | .I <sys/sem.h> | |
682edefb | 178 | if the |
0daa9e92 | 179 | .B _GNU_SOURCE |
682edefb | 180 | feature test macro is defined: |
24ed820a | 181 | .nf |
088a639b | 182 | .in +4n |
24ed820a MK |
183 | |
184 | struct seminfo { | |
ffc19357 MK |
185 | int semmap; /* Number of entries in semaphore |
186 | map; unused within kernel */ | |
187 | int semmni; /* Maximum number of semaphore sets */ | |
188 | int semmns; /* Maximum number of semaphores in all | |
24ed820a | 189 | semaphore sets */ |
ffc19357 MK |
190 | int semmnu; /* System-wide maximum number of undo |
191 | structures; unused within kernel */ | |
192 | int semmsl; /* Maximum number of semaphores in a | |
193 | set */ | |
194 | int semopm; /* Maximum number of operations for | |
195 | semop(2) */ | |
196 | int semume; /* Maximum number of undo entries per | |
197 | process; unused within kernel */ | |
198 | int semusz; /* Size of struct sem_undo */ | |
24ed820a | 199 | int semvmx; /* Maximum semaphore value */ |
c13182ef | 200 | int semaem; /* Max. value that can be recorded for |
24ed820a MK |
201 | semaphore adjustment (SEM_UNDO) */ |
202 | }; | |
203 | ||
088a639b | 204 | .in |
24ed820a | 205 | .fi |
c13182ef | 206 | The |
24ed820a MK |
207 | .IR semmsl , |
208 | .IR semmns , | |
209 | .IR semopm , | |
210 | and | |
211 | .I semmni | |
212 | settings can be changed via | |
213 | .IR /proc/sys/kernel/sem ; | |
214 | see | |
c13182ef | 215 | .BR proc (5) |
24ed820a MK |
216 | for details. |
217 | .TP | |
8382f16d | 218 | .BR SEM_INFO " (Linux-specific)" |
24ed820a MK |
219 | Returns a |
220 | .I seminfo | |
221 | structure containing the same information as for | |
222 | .BR IPC_INFO , | |
c13182ef | 223 | except that the following fields are returned with information |
24ed820a MK |
224 | about system resources consumed by semaphores: the |
225 | .I semusz | |
c13182ef | 226 | field returns the number of semaphore sets that currently exist |
24ed820a MK |
227 | on the system; and the |
228 | .I semaem | |
c13182ef | 229 | field returns the total number of semaphores in all semaphore sets |
24ed820a MK |
230 | on the system. |
231 | .TP | |
8382f16d | 232 | .BR SEM_STAT " (Linux-specific)" |
c13182ef MK |
233 | Returns a |
234 | .I semid_ds | |
24ed820a MK |
235 | structure as for |
236 | .BR IPC_STAT . | |
237 | However, the | |
238 | .I semid | |
239 | argument is not a semaphore identifier, but instead an index into | |
240 | the kernel's internal array that maintains information about | |
241 | all semaphore sets on the system. | |
242 | .TP | |
fea681da MK |
243 | .B GETALL |
244 | Return | |
245 | .B semval | |
70d0e5ef | 246 | (i.e., the current value) |
fea681da | 247 | for all semaphores of the set into |
d6c57ce6 | 248 | .IR arg.array . |
fea681da MK |
249 | The argument |
250 | .I semnum | |
251 | is ignored. | |
70d0e5ef | 252 | The calling process must have read permission on the semaphore set. |
fea681da MK |
253 | .TP |
254 | .B GETNCNT | |
255 | The system call returns the value of | |
256 | .B semncnt | |