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