Debian Codegraph @

upstream/debian-unstable/man2/semget.2

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