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