man2/semget.2

   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
 342
 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
 385
 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>
 395
 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 }
 405
 406 int
 407 main(int argc, char *argv[])
 408 {
 409     int semid, nsems, flags, opt;
 410     key_t key;
 411
 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     }
 420
 421     if (argc != optind + 3)
 422         usage(argv[0]);
 423
 424     key = ftok(argv[optind], argv[optind + 1][0]);
 425     if (key == \-1) {
 426         perror("ftok");
 427         exit(EXIT_FAILURE);
 428     }
 429
 430     nsems = atoi(argv[optind + 2]);
 431
 432     semid = semget(key, nsems, flags | 0600);
 433     if (semid == \-1) {
 434         perror("semget");
 435         exit(EXIT_FAILURE);
 436     }
 437
 438     printf("ID = %d\en", semid);
 439
 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)