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