| blob | 167957b3a5628b104ddc1c77ea1b7de6d6ce31df |
1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
2 .\" and Copyright (C) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
7 .\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
8 .\" Modified 4 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
9 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
10 .\" Added notes on capability requirements
11 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
12 .\" Language and formatting clean-ups
13 .\" Added notes on /proc files
14 .\" Rewrote BUGS note about semget()'s failure to initialize
15 .\" semaphore values
16 .\"
17 .TH semget 2 (date) "Linux man-pages (unreleased)"
18 .SH NAME
19 semget \- get a System V semaphore set identifier
20 .SH LIBRARY
21 Standard C library
22 .RI ( libc ", " \-lc )
23 .SH SYNOPSIS
24 .nf
25 .B #include <sys/sem.h>
26 .fi
27 .P
28 .BI "int semget(key_t " key ,
29 .BI "int " nsems ,
30 .BI "int " semflg );
31 .SH DESCRIPTION
32 The
33 .BR semget ()
34 system call returns the System\ V semaphore set identifier
35 associated with the argument
36 .IR key .
37 It may be used either to obtain the identifier of a previously created
38 semaphore set (when
39 .I semflg
40 is zero and
41 .I key
42 does not have the value
43 .BR IPC_PRIVATE ),
44 or to create a new set.
45 .P
46 A new set of
47 .I nsems
48 semaphores is created if
49 .I key
50 has the value
51 .B IPC_PRIVATE
52 or if no existing semaphore set is associated with
53 .I key
54 and
55 .B IPC_CREAT
56 is specified in
57 .IR semflg .
58 .P
59 If
60 .I semflg
61 specifies both
62 .B IPC_CREAT
63 and
64 .B IPC_EXCL
65 and a semaphore set already exists for
66 .IR key ,
67 then
68 .BR semget ()
69 fails with
70 .I errno
71 set to
72 .BR EEXIST .
73 (This is analogous to the effect of the combination
74 .B O_CREAT | O_EXCL
75 for
76 .BR open (2).)
77 .P
78 Upon creation, the least significant 9 bits of the argument
79 .I semflg
80 define the permissions (for owner, group, and others)
81 for the semaphore set.
82 These bits have the same format, and the same
83 meaning, as the
84 .I mode
85 argument of
86 .BR open (2)
87 (though the execute permissions are
88 not meaningful for semaphores, and write permissions mean permission
89 to alter semaphore values).
90 .P
91 When creating a new semaphore set,
92 .BR semget ()
93 initializes the set's associated data structure,
94 .I semid_ds
95 (see
96 .BR semctl (2)),
97 as follows:
98 .IP \[bu] 3
99 .I sem_perm.cuid
100 and
101 .I sem_perm.uid
102 are set to the effective user ID of the calling process.
103 .IP \[bu]
104 .I sem_perm.cgid
105 and
106 .I sem_perm.gid
107 are set to the effective group ID of the calling process.
108 .IP \[bu]
109 The least significant 9 bits of
110 .I sem_perm.mode
111 are set to the least significant 9 bits of
112 .IR semflg .
113 .IP \[bu]
114 .I sem_nsems
115 is set to the value of
116 .IR nsems .
117 .IP \[bu]
118 .I sem_otime
119 is set to 0.
120 .IP \[bu]
121 .I sem_ctime
122 is set to the current time.
123 .P
124 The argument
125 .I nsems
126 can be 0
127 (a don't care)
128 when a semaphore set is not being created.
129 Otherwise,
130 .I nsems
131 must be greater than 0
132 and less than or equal to the maximum number of semaphores per semaphore set
133 .RB ( SEMMSL ).
134 .P
135 If the semaphore set already exists, the permissions are
136 verified.
137 .\" and a check is made to see if it is marked for destruction.
138 .SH RETURN VALUE
139 On success,
140 .BR semget ()
141 returns the semaphore set identifier (a nonnegative integer).
142 On failure, \-1 is returned, and
143 .I errno
144 is set to indicate the error.
145 .SH ERRORS
146 .TP
147 .B EACCES
148 A semaphore set exists for
149 .IR key ,
150 but the calling process does not have permission to access the set,
151 and does not have the
152 .B CAP_IPC_OWNER
153 capability in the user namespace that governs its IPC namespace.
154 .TP
155 .B EEXIST
156 .B IPC_CREAT
157 and
158 .B IPC_EXCL
159 were specified in
160 .IR semflg ,
161 but a semaphore set already exists for
162 .IR key .
163 .\" .TP
164 .\" .B EIDRM
165 .\" The semaphore set is marked to be deleted.
166 .TP
167 .B EINVAL
168 .I nsems
169 is less than 0 or greater than the limit on the number
170 of semaphores per semaphore set
171 .RB ( SEMMSL ).
172 .TP
173 .B EINVAL
174 A semaphore set corresponding to
175 .I key
176 already exists, but
177 .I nsems
178 is larger than the number of semaphores in that set.
179 .TP
180 .B ENOENT
181 No semaphore set exists for
182 .I key
183 and
184 .I semflg
185 did not specify
186 .BR IPC_CREAT .
187 .TP
188 .B ENOMEM
189 A semaphore set has to be created but the system does not have
190 enough memory for the new data structure.
191 .TP
192 .B ENOSPC
193 A semaphore set has to be created but the system limit for the maximum
194 number of semaphore sets
195 .RB ( SEMMNI ),
196 or the system wide maximum number of semaphores
197 .RB ( SEMMNS ),
198 would be exceeded.
199 .SH STANDARDS
200 POSIX.1-2008.
201 .SH HISTORY
202 SVr4, POSIX.1-2001.
203 .\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
204 .\" ERANGE, EFAULT.
205 .SH NOTES
206 .B IPC_PRIVATE
207 isn't a flag field but a
208 .I key_t
209 type.
210 If this special value is used for
211 .IR key ,
212 the system call ignores all but the least significant 9 bits of
213 .I semflg
214 and creates a new semaphore set (on success).
215 .\"
216 .SS Semaphore initialization
217 The values of the semaphores in a newly created set are indeterminate.
218 (POSIX.1-2001 and POSIX.1-2008 are explicit on this point,
219 although POSIX.1-2008 notes that a future version of the standard
220 may require an implementation to initialize the semaphores to 0.)
221 Although Linux, like many other implementations,
222 initializes the semaphore values to 0,
223 a portable application cannot rely on this:
224 it should explicitly initialize the semaphores to the desired values.
225 .\" In truth, every one of the many implementations that I've tested sets
226 .\" the values to zero, but I suppose there is/was some obscure
227 .\" implementation out there that does not.
228 .P
229 Initialization can be done using
230 .BR semctl (2)
231 .B SETVAL
232 or
233 .B SETALL
234 operation.
235 Where multiple peers do not know who will be the first to
236 initialize the set, checking for a nonzero
237 .I sem_otime
238 in the associated data structure retrieved by a
239 .BR semctl (2)
240 .B IPC_STAT
241 operation can be used to avoid races.
242 .\"
243 .SS Semaphore limits
244 The following limits on semaphore set resources affect the
245 .BR semget ()
246 call:
247 .TP
248 .B SEMMNI
249 System-wide limit on the number of semaphore sets.
250 Before Linux 3.19,
251 the default value for this limit was 128.
252 Since Linux 3.19,
253 .\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4
254 the default value is 32,000.
255 On Linux, this limit can be read and modified via the fourth field of
256 .IR /proc/sys/kernel/sem .
257 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
258 .TP
259 .B SEMMSL
260 Maximum number of semaphores per semaphore ID.
261 Before Linux 3.19,
262 the default value for this limit was 250.
263 Since Linux 3.19,
264 .\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4
265 the default value is 32,000.
266 On Linux, this limit can be read and modified via the first field of
267 .IR /proc/sys/kernel/sem .
268 .TP
269 .B SEMMNS
270 System-wide limit on the number of semaphores: policy dependent
271 (on Linux, this limit can be read and modified via the second field of
272 .IR /proc/sys/kernel/sem ).
273 Note that the number of semaphores system-wide
274 is also limited by the product of
275 .B SEMMSL
276 and
277 .BR SEMMNI .
278 .SH BUGS
279 The name choice
280 .B IPC_PRIVATE
281 was perhaps unfortunate,
282 .B IPC_NEW
283 would more clearly show its function.
284 .SH EXAMPLES
285 The program shown below uses
286 .BR semget ()
287 to create a new semaphore set or retrieve the ID of an existing set.
288 It generates the
289 .I key
290 for
291 .BR semget ()
292 using
293 .BR ftok (3).
294 The first two command-line arguments are used as the
295 .I pathname
296 and
297 .I proj_id
298 arguments for
299 .BR ftok (3).
300 The third command-line argument is an integer that specifies the
301 .I nsems
302 argument for
303 .BR semget ().
304 Command-line options can be used to specify the
305 .B IPC_CREAT
306 .RI ( \-c )
307 and
308 .B IPC_EXCL
309 .RI ( \-x )
310 flags for the call to
311 .BR semget ().
312 The usage of this program is demonstrated below.
313 .P
314 We first create two files that will be used to generate keys using
315 .BR ftok (3),
316 create two semaphore sets using those files, and then list the sets using
317 .BR ipcs (1):
318 .P
319 .in +4n
320 .EX
321 $ \fBtouch mykey mykey2\fP
322 $ \fB./t_semget \-c mykey p 1\fP
323 ID = 9
324 $ \fB./t_semget \-c mykey2 p 2\fP
325 ID = 10
326 $ \fBipcs \-s\fP
327 \&
328 \-\-\-\-\-\- Semaphore Arrays \-\-\-\-\-\-\-\-
329 key semid owner perms nsems
330 0x7004136d 9 mtk 600 1
331 0x70041368 10 mtk 600 2
332 .EE
333 .in
334 .P
335 Next, we demonstrate that when
336 .BR semctl (2)
337 is given the same
338 .I key
339 (as generated by the same arguments to
340 .BR ftok (3)),
341 it returns the ID of the already existing semaphore set:
342 .P
343 .in +4n
344 .EX
345 $ \fB./t_semget \-c mykey p 1\fP
346 ID = 9
347 .EE
348 .in
349 .P
350 Finally, we demonstrate the kind of collision that can occur when
351 .BR ftok (3)
352 is given different
353 .I pathname
354 arguments that have the same inode number:
355 .P
356 .in +4n
357 .EX
358 $ \fBln mykey link\fP
359 $ \fBls \-i1 link mykey\fP
360 2233197 link
361 2233197 mykey
362 $ \fB./t_semget link p 1\fP # Generates same key as \[aq]mykey\[aq]
363 ID = 9
364 .EE
365 .in
366 .SS Program source
367 \&
368 .\" SRC BEGIN (t_semget.c)
369 .EX
370 /* t_semget.c
371 \&
372 Licensed under GNU General Public License v2 or later.
373 */
374 #include <stdio.h>
375 #include <stdlib.h>
376 #include <sys/ipc.h>
377 #include <sys/sem.h>
378 #include <unistd.h>
379 \&
380 static void
381 usage(const char *pname)
382 {
383 fprintf(stderr, "Usage: %s [\-cx] pathname proj\-id num\-sems\en",
384 pname);
385 fprintf(stderr, " \-c Use IPC_CREAT flag\en");
386 fprintf(stderr, " \-x Use IPC_EXCL flag\en");
387 exit(EXIT_FAILURE);
388 }
389 \&
390 int
391 main(int argc, char *argv[])
392 {
393 int semid, nsems, flags, opt;
394 key_t key;
395 \&
396 flags = 0;
397 while ((opt = getopt(argc, argv, "cx")) != \-1) {
398 switch (opt) {
399 case \[aq]c\[aq]: flags |= IPC_CREAT; break;
400 case \[aq]x\[aq]: flags |= IPC_EXCL; break;
401 default: usage(argv[0]);
402 }
403 }
404 \&
405 if (argc != optind + 3)
406 usage(argv[0]);
407 \&
408 key = ftok(argv[optind], argv[optind + 1][0]);
409 if (key == \-1) {
410 perror("ftok");
411 exit(EXIT_FAILURE);
412 }
413 \&
414 nsems = atoi(argv[optind + 2]);
415 \&
416 semid = semget(key, nsems, flags | 0600);
417 if (semid == \-1) {
418 perror("semget");
419 exit(EXIT_FAILURE);
420 }
421 \&
422 printf("ID = %d\en", semid);
423 \&
424 exit(EXIT_SUCCESS);
425 }
426 .EE
427 .\" SRC END
428 .SH SEE ALSO
429 .BR semctl (2),
430 .BR semop (2),
431 .BR ftok (3),
432 .BR capabilities (7),
433 .BR sem_overview (7),
434 .BR sysvipc (7)