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