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, since Linux 4.17)"
 245 Return a
 246 .I seminfo
 247 structure containing the same information as for
 248 .BR SEM_STAT .
 249 However,
 250 .I sem_perm.mode
 251 is not checked for read access for
 252 .IR semid
 253 meaning that any user can employ this operation (just as any user may read
 254 .IR /proc/sysvipc/sem
 255 to obtain the same information).
 256 .TP
 257 .B GETALL
 258 Return
 259 .B semval
 260 (i.e., the current value)
 261 for all semaphores of the set into
 262 .IR arg.array .
 263 The argument
 264 .I semnum
 265 is ignored.
 266 The calling process must have read permission on the semaphore set.
 267 .TP
 268 .B GETNCNT
 269 Return the value of
 270 .B semncnt
 271 for the
 272 .IR semnum \-th
 273 semaphore of the set
 274 (i.e., the number of processes waiting for an increase of
 275 .B semval
 276 for the
 277 .IR semnum \-th
 278 semaphore of the set).
 279 The calling process must have read permission on the semaphore set.
 280 .TP
 281 .B GETPID
 282 Return the value of
 283 .B sempid
 284 for the
 285 .IR semnum \-th
 286 semaphore of the set.
 287 This is the PID of the process that last performed an operation on
 288 that semaphore (but see NOTES).
 289 The calling process must have read permission on the semaphore set.
 290 .TP
 291 .B GETVAL
 292 Return the value of
 293 .B semval
 294 for the
 295 .IR semnum \-th
 296 semaphore of the set.
 297 The calling process must have read permission on the semaphore set.
 298 .TP
 299 .B GETZCNT
 300 Return the value of
 301 .B semzcnt
 302 for the
 303 .IR semnum \-th
 304 semaphore of the set
 305 (i.e., the number of processes waiting for
 306 .B semval
 307 of the
 308 .IR semnum \-th
 309 semaphore of the set to become 0).
 310 The calling process must have read permission on the semaphore set.
 311 .TP
 312 .B SETALL
 313 Set
 314 .B semval
 315 for all semaphores of the set using
 316 .IR arg.array ,
 317 updating also the
 318 .I sem_ctime
 319 member of the
 320 .I semid_ds
 321 structure associated with the set.
 322 Undo entries (see
 323 .BR semop (2))
 324 are cleared for altered semaphores in all processes.
 325 If the changes to semaphore values would permit blocked
 326 .BR semop (2)
 327 calls in other processes to proceed, then those processes are woken up.
 328 The argument
 329 .I semnum
 330 is ignored.
 331 The calling process must have alter (write) permission on
 332 the semaphore set.
 333 .TP
 334 .B SETVAL
 335 Set the value of
 336 .B semval
 337 to
 338 .I arg.val
 339 for the
 340 .IR semnum \-th
 341 semaphore of the set, updating also the
 342 .I sem_ctime
 343 member of the
 344 .I semid_ds
 345 structure associated with the set.
 346 Undo entries are cleared for altered semaphores in all processes.
 347 If the changes to semaphore values would permit blocked
 348 .BR semop (2)
 349 calls in other processes to proceed, then those processes are woken up.
 350 The calling process must have alter permission on the semaphore set.
 351 .SH RETURN VALUE
 352 On failure,
 353 .BR semctl ()
 354 returns \-1
 355 with
 356 .I errno
 357 indicating the error.
 358 .PP
 359 Otherwise, the system call returns a nonnegative value depending on
 360 .I cmd
 361 as follows:
 362 .TP 10
 363 .B GETNCNT
 364 the value of
 365 .BR semncnt .
 366 .TP
 367 .B GETPID
 368 the value of
 369 .BR sempid .
 370 .TP
 371 .B GETVAL
 372 the value of
 373 .BR semval .
 374 .TP
 375 .B GETZCNT
 376 the value of
 377 .BR semzcnt .
 378 .TP
 379 .B IPC_INFO
 380 the index of the highest used entry in the
 381 kernel's internal array recording information about all
 382 semaphore sets.
 383 (This information can be used with repeated
 384 .B SEM_STAT
 385 or
 386 .B SEM_STAT_ANY
 387 operations to obtain information about all semaphore sets on the system.)
 388 .TP
 389 .B SEM_INFO
 390 as for
 391 .BR IPC_INFO .
 392 .TP
 393 .B SEM_STAT
 394 the identifier of the semaphore set whose index was given in
 395 .IR semid .
 396 .TP
 397 .B SEM_STAT_ANY
 398 as for
 399 .BR SEM_STAT .
 400 .PP
 401 All other
 402 .I cmd
 403 values return 0 on success.
 404 .SH ERRORS
 405 On failure,
 406 .I errno
 407 will be set to one of the following:
 408 .TP
 409 .B EACCES
 410 The argument
 411 .I cmd
 412 has one of the values
 413 .BR GETALL ,
 414 .BR GETPID ,
 415 .BR GETVAL ,
 416 .BR GETNCNT ,
 417 .BR GETZCNT ,
 418 .BR IPC_STAT ,
 419 .BR SEM_STAT ,
 420 .BR SEM_STAT_ANY ,
 421 .BR SETALL ,
 422 or
 423 .B SETVAL
 424 and the calling process does not have the required
 425 permissions on the semaphore set and does not have the
 426 .B CAP_IPC_OWNER
 427 capability in the user namespace that governs its IPC namespace.
 428 .TP
 429 .B EFAULT
 430 The address pointed to by
 431 .I arg.buf
 432 or
 433 .I arg.array
 434 isn't accessible.
 435 .TP
 436 .B EIDRM
 437 The semaphore set was removed.
 438 .TP
 439 .B EINVAL
 440 Invalid value for
 441 .I cmd
 442 or
 443 .IR semid .
 444 Or: for a
 445 .B SEM_STAT
 446 operation, the index value specified in
 447 .I semid
 448 referred to an array slot that is currently unused.
 449 .TP
 450 .B EPERM
 451 The argument
 452 .I cmd
 453 has the value
 454 .B IPC_SET
 455 or
 456 .B IPC_RMID
 457 but the effective user ID of the calling process is not the creator
 458 (as found in
 459 .IR sem_perm.cuid )
 460 or the owner
 461 (as found in
 462 .IR sem_perm.uid )
 463 of the semaphore set,
 464 and the process does not have the
 465 .B CAP_SYS_ADMIN
 466 capability.
 467 .TP
 468 .B ERANGE
 469 The argument
 470 .I cmd
 471 has the value
 472 .B SETALL
 473 or
 474 .B SETVAL
 475 and the value to which
 476 .B semval
 477 is to be set (for some semaphore of the set) is less than 0
 478 or greater than the implementation limit
 479 .BR SEMVMX .
 480 .SH CONFORMING TO
 481 POSIX.1-2001, POSIX.1-2008, SVr4.
 482 .\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
 483 .PP
 484 POSIX.1 specifies the
 485 .\" POSIX.1-2001, POSIX.1-2008
 486 .I sem_nsems
 487 field of the
 488 .I semid_ds
 489 structure as having the type
 490 .IR "unsigned\ short" ,
 491 and the field is so defined on most other systems.
 492 It was also so defined on Linux 2.2 and earlier,
 493 but, since Linux 2.4, the field has the type
 494 .IR "unsigned\ long" .
 495 .SH NOTES
 496 The inclusion of
 497 .I <sys/types.h>
 498 and
 499 .I <sys/ipc.h>
 500 isn't required on Linux or by any version of POSIX.
 501 However,
 502 some old implementations required the inclusion of these header files,
 503 and the SVID also documented their inclusion.
 504 Applications intended to be portable to such old systems may need
 505 to include these header files.
 506 .\" Like Linux, the FreeBSD man pages still document
 507 .\" the inclusion of these header files.
 508 .PP
 509 The
 510 .BR IPC_INFO ,
 511 .B SEM_STAT
 512 and
 513 .B SEM_INFO
 514 operations are used by the
 515 .BR ipcs (1)
 516 program to provide information on allocated resources.
 517 In the future these may modified or moved to a
 518 .I /proc
 519 filesystem interface.
 520 .PP
 521 Various fields in a \fIstruct semid_ds\fP were typed as
 522 .I short
 523 under Linux 2.2
 524 and have become
 525 .I long
 526 under Linux 2.4.
 527 To take advantage of this,
 528 a recompilation under glibc-2.1.91 or later should suffice.
 529 (The kernel distinguishes old and new calls by an
 530 .B IPC_64
 531 flag in
 532 .IR cmd .)
 533 .PP
 534 In some earlier versions of glibc, the
 535 .I semun
 536 union was defined in \fI<sys/sem.h>\fP, but POSIX.1 requires
 537 .\" POSIX.1-2001, POSIX.1-2008
 538 that the caller define this union.
 539 On versions of glibc where this union is \fInot\fP defined,
 540 the macro
 541 .B _SEM_SEMUN_UNDEFINED
 542 is defined in \fI<sys/sem.h>\fP.
 543 .PP
 544 The following system limit on semaphore sets affects a
 545 .BR semctl ()
 546 call:
 547 .TP
 548 .B SEMVMX
 549 Maximum value for
 550 .BR semval :
 551 implementation dependent (32767).
 552 .PP
 553 For greater portability, it is best to always call
 554 .BR semctl ()
 555 with four arguments.
 556 .\"
 557 .SS The sempid value
 558 POSIX.1 defines
 559 .I sempid
 560 as the "process ID of [the] last operation" on a semaphore,
 561 and explicitly notes that this value is set by a successful
 562 .BR semop (2)
 563 call, with the implication that no other interface affects the
 564 .I sempid
 565 value.
 566 .PP
 567 While some implementations conform to the behavior specified in POSIX.1,
 568 others do not.
 569 (The fault here probably lies with POSIX.1 inasmuch as it likely failed
 570 to capture the full range of existing implementation behaviors.)
 571 Various other implementations
 572 .\" At least OpenSolaris (and, one supposes, older Solaris) and Darwin
 573 also update
 574 .I sempid
 575 for the other operations that update the value of a semaphore: the
 576 .B SETVAL
 577 and
 578 .B SETALL
 579 operations, as well as the semaphore adjustments performed
 580 on process termination as a consequence of the use of the
 581 .B SEM_UNDO
 582 flag (see
 583 .BR semop (2)).
 584 .PP
 585 Linux also updates
 586 .I sempid
 587 for
 588 .BR SETVAL
 589 operations and semaphore adjustments.
 590 However, somewhat inconsistently, up to and including 4.5,
 591 Linux did not update
 592 .I sempid
 593 for
 594 .BR SETALL
 595 operations.
 596 This was rectified
 597 .\" commit a5f4db877177d2a3d7ae62a7bac3a5a27e083d7f
 598 in Linux 4.6.
 599 .SH SEE ALSO
 600 .BR ipc (2),
 601 .BR semget (2),
 602 .BR semop (2),
 603 .BR capabilities (7),
 604 .BR sem_overview (7),
 605 .BR svipc (7)