man2/semctl.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\" and Copyright 2004, 2005 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:53:56 1996 by Eric S. Raymond <esr@thyrsus.com>
  27 .\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl>
  28 .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
  29 .\" Modified 20 Dec 2001, Michael Kerrisk <mtk.manpages@gmail.com>
  30 .\" Modified 21 Dec 2001, aeb
  31 .\" Modified 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  32 .\"     Added notes on CAP_IPC_OWNER requirement
  33 .\" Modified 17 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  34 .\"     Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
  35 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  36 .\"     Language and formatting clean-ups
  37 .\"     Rewrote semun text
  38 .\"     Added semid_ds and ipc_perm structure definitions
  39 .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions.
  40 .\" 2018-03-20, dbueso: Added SEM_STAT_ANY description.
  41 .\"
  42 .TH SEMCTL 2 2017-09-15 "Linux" "Linux Programmer's Manual"
  43 .SH NAME
  44 semctl \- System V semaphore control operations
  45 .SH SYNOPSIS
  46 .nf
  47 .B #include <sys/types.h>
  48 .B #include <sys/ipc.h>
  49 .B #include <sys/sem.h>
  50 .PP
  51 .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);"
  52 .fi
  53 .SH DESCRIPTION
  54 .BR semctl ()
  55 performs the control operation specified by
  56 .I cmd
  57 on the System\ V semaphore set identified by
  58 .IR semid ,
  59 or on the
  60 .IR semnum -th
  61 semaphore of that set.
  62 (The semaphores in a set are numbered starting at 0.)
  63 .PP
  64 This function has three or four arguments, depending on
  65 .IR cmd .
  66 When there are four, the fourth has the type
  67 .IR "union semun" .
  68 The \fIcalling program\fP must define this union as follows:
  69 .PP
  70 .in +4n
  71 .EX
  72 union semun {
  73     int              val;    /* Value for SETVAL */
  74     struct semid_ds *buf;    /* Buffer for IPC_STAT, IPC_SET */
  75     unsigned short  *array;  /* Array for GETALL, SETALL */
  76     struct seminfo  *__buf;  /* Buffer for IPC_INFO
  77                                 (Linux-specific) */
  78 };
  79 .EE
  80 .in
  81 .PP
  82 The
  83 .I semid_ds
  84 data structure is defined in \fI<sys/sem.h>\fP as follows:
  85 .PP
  86 .in +4n
  87 .EX
  88 struct semid_ds {
  89     struct ipc_perm sem_perm;  /* Ownership and permissions */
  90     time_t          sem_otime; /* Last semop time */
  91     time_t          sem_ctime; /* Last change time */
  92     unsigned long   sem_nsems; /* No. of semaphores in set */
  93 };
  94 .EE
  95 .in
  96 .PP
  97 The
  98 .I ipc_perm
  99 structure is defined as follows
 100 (the highlighted fields are settable using
 101 .BR IPC_SET ):
 102 .PP
 103 .in +4n
 104 .EX
 105 struct ipc_perm {
 106     key_t          __key; /* Key supplied to semget(2) */
 107     uid_t          \fBuid\fP;   /* Effective UID of owner */
 108     gid_t          \fBgid\fP;   /* Effective GID of owner */
 109     uid_t          cuid;  /* Effective UID of creator */
 110     gid_t          cgid;  /* Effective GID of creator */
 111     unsigned short \fBmode\fP;  /* Permissions */
 112     unsigned short __seq; /* Sequence number */
 113 };
 114 .EE
 115 .in
 116 .PP
 117 Valid values for
 118 .I cmd
 119 are:
 120 .TP 10
 121 .B IPC_STAT
 122 Copy information from the kernel data structure associated with
 123 .I semid
 124 into the
 125 .I semid_ds
 126 structure pointed to by
 127 .IR arg.buf .
 128 The argument
 129 .I semnum
 130 is ignored.
 131 The calling process must have read permission on the semaphore set.
 132 .TP
 133 .B IPC_SET
 134 Write the values of some members of the
 135 .I semid_ds
 136 structure pointed to by
 137 .I arg.buf
 138 to the kernel data structure associated with this semaphore set,
 139 updating also its
 140 .I sem_ctime
 141 member.
 142 The following members of the structure are updated:
 143 .IR sem_perm.uid ,
 144 .IR sem_perm.gid ,
 145 and (the least significant 9 bits of)
 146 .IR sem_perm.mode .
 147 The effective UID of the calling process must match the owner
 148 .RI ( sem_perm.uid )
 149 or creator
 150 .RI ( sem_perm.cuid )
 151 of the semaphore set, or the caller must be privileged.
 152 The argument
 153 .I semnum
 154 is ignored.
 155 .TP
 156 .B IPC_RMID
 157 Immediately remove the semaphore set,
 158 awakening all processes blocked in
 159 .BR semop (2)
 160 calls on the set (with an error return and
 161 .I errno
 162 set to
 163 .BR EIDRM ).
 164 The effective user ID of the calling process must
 165 match the creator or owner of the semaphore set,
 166 or the caller must be privileged.
 167 The argument
 168 .I semnum
 169 is ignored.
 170 .TP
 171 .BR IPC_INFO " (Linux-specific)"
 172 Return information about system-wide semaphore limits and
 173 parameters in the structure pointed to by
 174 .IR arg.__buf .
 175 This structure is of type
 176 .IR seminfo ,
 177 defined in
 178 .I <sys/sem.h>
 179 if the
 180 .B _GNU_SOURCE
 181 feature test macro is defined:
 182 .IP
 183 .in +4n
 184 .EX
 185 struct  seminfo {
 186     int semmap;  /* Number of entries in semaphore
 187                     map; unused within kernel */
 188     int semmni;  /* Maximum number of semaphore sets */
 189     int semmns;  /* Maximum number of semaphores in all
 190                     semaphore sets */
 191     int semmnu;  /* System-wide maximum number of undo
 192                     structures; unused within kernel */
 193     int semmsl;  /* Maximum number of semaphores in a
 194                     set */
 195     int semopm;  /* Maximum number of operations for
 196                     semop(2) */
 197     int semume;  /* Maximum number of undo entries per
 198                     process; unused within kernel */
 199     int semusz;  /* Size of struct sem_undo */
 200     int semvmx;  /* Maximum semaphore value */
 201     int semaem;  /* Max. value that can be recorded for
 202                     semaphore adjustment (SEM_UNDO) */
 203 };
 204 .EE
 205 .in
 206 .IP
 207 The
 208 .IR semmsl ,
 209 .IR semmns ,
 210 .IR semopm ,
 211 and
 212 .I semmni
 213 settings can be changed via
 214 .IR /proc/sys/kernel/sem ;
 215 see
 216 .BR proc (5)
 217 for details.
 218 .TP
 219 .BR SEM_INFO " (Linux-specific)"
 220 Return a
 221 .I seminfo
 222 structure containing the same information as for
 223 .BR IPC_INFO ,
 224 except that the following fields are returned with information
 225 about system resources consumed by semaphores: the
 226 .I semusz
 227 field returns the number of semaphore sets that currently exist
 228 on the system; and the
 229 .I semaem
 230 field returns the total number of semaphores in all semaphore sets
 231 on the system.
 232 .TP
 233 .BR SEM_STAT " (Linux-specific)"
 234 Return a
 235 .I semid_ds
 236 structure as for
 237 .BR IPC_STAT .
 238 However, the
 239 .I semid
 240 argument is not a semaphore identifier, but instead an index into
 241 the kernel's internal array that maintains information about
 242 all semaphore sets on the system.
 243 .TP
 244 .BR SEM_STAT_ANY " (Linux-specific)"
 245 Return a
 246 .I seminfo
 247 structure containing the same information as for
 248 .BR SEM_STAT .
 249 However, the
 250 .I sem_perm.mode
 251 is not checked for read access for
 252 .IR semid ,
 253 resembing the behaviour of
 254 .IR /proc/sysvipc/sem .
 255 .TP
 256 .B GETALL
 257 Return
 258 .B semval
 259 (i.e., the current value)
 260 for all semaphores of the set into
 261 .IR arg.array .
 262 The argument
 263 .I semnum
 264 is ignored.
 265 The calling process must have read permission on the semaphore set.
 266 .TP
 267 .B GETNCNT
 268 Return the value of
 269 .B semncnt
 270 for the
 271 .IR semnum \-th
 272 semaphore of the set
 273 (i.e., the number of processes waiting for an increase of
 274 .B semval
 275 for the
 276 .IR semnum \-th
 277 semaphore of the set).
 278 The calling process must have read permission on the semaphore set.
 279 .TP
 280 .B GETPID
 281 Return the value of
 282 .B sempid
 283 for the
 284 .IR semnum \-th
 285 semaphore of the set.
 286 This is the PID of the process that last performed an operation on
 287 that semaphore (but see NOTES).
 288 The calling process must have read permission on the semaphore set.
 289 .TP
 290 .B GETVAL
 291 Return the value of
 292 .B semval
 293 for the
 294 .IR semnum \-th
 295 semaphore of the set.
 296 The calling process must have read permission on the semaphore set.
 297 .TP
 298 .B GETZCNT
 299 Return the value of
 300 .B semzcnt
 301 for the
 302 .IR semnum \-th
 303 semaphore of the set
 304 (i.e., the number of processes waiting for
 305 .B semval
 306 of the
 307 .IR semnum \-th
 308 semaphore of the set to become 0).
 309 The calling process must have read permission on the semaphore set.
 310 .TP
 311 .B SETALL
 312 Set
 313 .B semval
 314 for all semaphores of the set using
 315 .IR arg.array ,
 316 updating also the
 317 .I sem_ctime
 318 member of the
 319 .I semid_ds
 320 structure associated with the set.
 321 Undo entries (see
 322 .BR semop (2))
 323 are cleared for altered semaphores in all processes.
 324 If the changes to semaphore values would permit blocked
 325 .BR semop (2)
 326 calls in other processes to proceed, then those processes are woken up.
 327 The argument
 328 .I semnum
 329 is ignored.
 330 The calling process must have alter (write) permission on
 331 the semaphore set.
 332 .TP
 333 .B SETVAL
 334 Set the value of
 335 .B semval
 336 to
 337 .I arg.val
 338 for the
 339 .IR semnum \-th
 340 semaphore of the set, updating also the
 341 .I sem_ctime
 342 member of the
 343 .I semid_ds
 344 structure associated with the set.
 345 Undo entries are cleared for altered semaphores in all processes.
 346 If the changes to semaphore values would permit blocked
 347 .BR semop (2)
 348 calls in other processes to proceed, then those processes are woken up.
 349 The calling process must have alter permission on the semaphore set.
 350 .SH RETURN VALUE
 351 On failure,
 352 .BR semctl ()
 353 returns \-1
 354 with
 355 .I errno
 356 indicating the error.
 357 .PP
 358 Otherwise, the system call returns a nonnegative value depending on
 359 .I cmd
 360 as follows:
 361 .TP 10
 362 .B GETNCNT
 363 the value of
 364 .BR semncnt .
 365 .TP
 366 .B GETPID
 367 the value of
 368 .BR sempid .
 369 .TP
 370 .B GETVAL
 371 the value of
 372 .BR semval .
 373 .TP
 374 .B GETZCNT
 375 the value of
 376 .BR semzcnt .
 377 .TP
 378 .B IPC_INFO
 379 the index of the highest used entry in the
 380 kernel's internal array recording information about all
 381 semaphore sets.
 382 (This information can be used with repeated
 383 .B SEM_STAT
 384 or
 385 .B SEM_STAT_ANY
 386 operations to obtain information about all semaphore sets on the system.)
 387 .TP
 388 .B SEM_INFO
 389 as for
 390 .BR IPC_INFO .
 391 .TP
 392 .B SEM_STAT
 393 the identifier of the semaphore set whose index was given in
 394 .IR semid .
 395 .TP
 396 .B SEM_STAT_ANY
 397 as for
 398 .BR SEM_STAT .
 399 .PP
 400 All other
 401 .I cmd
 402 values return 0 on success.
 403 .SH ERRORS
 404 On failure,
 405 .I errno
 406 will be set to one of the following:
 407 .TP
 408 .B EACCES
 409 The argument
 410 .I cmd
 411 has one of the values
 412 .BR GETALL ,
 413 .BR GETPID ,
 414 .BR GETVAL ,
 415 .BR GETNCNT ,
 416 .BR GETZCNT ,
 417 .BR IPC_STAT ,
 418 .BR SEM_STAT ,
 419 .BR SEM_STAT_ANY ,
 420 .BR SETALL ,
 421 or
 422 .B SETVAL
 423 and the calling process does not have the required
 424 permissions on the semaphore set and does not have the
 425 .B CAP_IPC_OWNER
 426 capability in the user namespace that governs its IPC namespace.
 427 .TP
 428 .B EFAULT
 429 The address pointed to by
 430 .I arg.buf
 431 or
 432 .I arg.array
 433 isn't accessible.
 434 .TP
 435 .B EIDRM
 436 The semaphore set was removed.
 437 .TP
 438 .B EINVAL
 439 Invalid value for
 440 .I cmd
 441 or
 442 .IR semid .
 443 Or: for a
 444 .B SEM_STAT
 445 operation, the index value specified in
 446 .I semid
 447 referred to an array slot that is currently unused.
 448 .TP
 449 .B EPERM
 450 The argument
 451 .I cmd
 452 has the value
 453 .B IPC_SET
 454 or
 455 .B IPC_RMID
 456 but the effective user ID of the calling process is not the creator
 457 (as found in
 458 .IR sem_perm.cuid )
 459 or the owner
 460 (as found in
 461 .IR sem_perm.uid )
 462 of the semaphore set,
 463 and the process does not have the
 464 .B CAP_SYS_ADMIN
 465 capability.
 466 .TP
 467 .B ERANGE
 468 The argument
 469 .I cmd
 470 has the value
 471 .B SETALL
 472 or
 473 .B SETVAL
 474 and the value to which
 475 .B semval
 476 is to be set (for some semaphore of the set) is less than 0
 477 or greater than the implementation limit
 478 .BR SEMVMX .
 479 .SH CONFORMING TO
 480 POSIX.1-2001, POSIX.1-2008, SVr4.
 481 .\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
 482 .PP
 483 POSIX.1 specifies the
 484 .\" POSIX.1-2001, POSIX.1-2008
 485 .I sem_nsems
 486 field of the
 487 .I semid_ds
 488 structure as having the type
 489 .IR "unsigned\ short" ,
 490 and the field is so defined on most other systems.
 491 It was also so defined on Linux 2.2 and earlier,
 492 but, since Linux 2.4, the field has the type
 493 .IR "unsigned\ long" .
 494 .SH NOTES
 495 The inclusion of
 496 .I <sys/types.h>
 497 and
 498 .I <sys/ipc.h>
 499 isn't required on Linux or by any version of POSIX.
 500 However,
 501 some old implementations required the inclusion of these header files,
 502 and the SVID also documented their inclusion.
 503 Applications intended to be portable to such old systems may need
 504 to include these header files.
 505 .\" Like Linux, the FreeBSD man pages still document
 506 .\" the inclusion of these header files.
 507 .PP
 508 The
 509 .BR IPC_INFO ,
 510 .B SEM_STAT
 511 and
 512 .B SEM_INFO
 513 operations are used by the
 514 .BR ipcs (1)
 515 program to provide information on allocated resources.
 516 In the future these may modified or moved to a
 517 .I /proc
 518 filesystem interface.
 519 .PP
 520 Various fields in a \fIstruct semid_ds\fP were typed as
 521 .I short
 522 under Linux 2.2
 523 and have become
 524 .I long
 525 under Linux 2.4.
 526 To take advantage of this,
 527 a recompilation under glibc-2.1.91 or later should suffice.
 528 (The kernel distinguishes old and new calls by an
 529 .B IPC_64
 530 flag in
 531 .IR cmd .)
 532 .PP
 533 In some earlier versions of glibc, the
 534 .I semun
 535 union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires
 536 .\" POSIX.1-2001, POSIX.1-2008
 537 that the caller define this union.
 538 On versions of glibc where this union is \fInot\fP defined,
 539 the macro
 540 .B _SEM_SEMUN_UNDEFINED
 541 is defined in \fI<sys/sem.h>\fP.
 542 .PP
 543 The following system limit on semaphore sets affects a
 544 .BR semctl ()
 545 call:
 546 .TP
 547 .B SEMVMX
 548 Maximum value for
 549 .BR semval :
 550 implementation dependent (32767).
 551 .PP
 552 For greater portability, it is best to always call
 553 .BR semctl ()
 554 with four arguments.
 555 .\"
 556 .SS The sempid value
 557 POSIX.1 defines
 558 .I sempid
 559 as the "process ID of [the] last operation" on a semaphore,
 560 and explicitly notes that this value is set by a successful
 561 .BR semop (2)
 562 call, with the implication that no other interface affects the
 563 .I sempid
 564 value.
 565 .PP
 566 While some implementations conform to the behavior specified in POSIX.1,
 567 others do not.
 568 (The fault here probably lies with POSIX.1 inasmuch as it likely failed
 569 to capture the full range of existing implementation behaviors.)
 570 Various other implementations
 571 .\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin
 572 also update
 573 .I sempid
 574 for the other operations that update the value of a semaphore: the
 575 .B SETVAL
 576 and
 577 .B SETALL
 578 operations, as well as the semaphore adjustments performed
 579 on process termination as a consequence of the use of the
 580 .B SEM_UNDO
 581 flag (see
 582 .BR semop (2)).
 583 .PP
 584 Linux also updates
 585 .I sempid
 586 for
 587 .BR SETVAL
 588 operations and semaphore adjustments.
 589 However, somewhat inconsistently, up to and including 4.5,
 590 Linux did not update
 591 .I sempid
 592 for
 593 .BR SETALL
 594 operations.
 595 This was rectified
 596 .\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
 597 in Linux 4.6.
 598 .SH SEE ALSO
 599 .BR ipc (2),
 600 .BR semget (2),
 601 .BR semop (2),
 602 .BR capabilities (7),
 603 .BR sem_overview (7),
 604 .BR svipc (7)