man2/semctl.2

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