original/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 2013-06-03 "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 (i.e., the PID of the process that executed the last
 274 .BR semop (2)
 275 call 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 GETVAL
 281 Return the value of
 282 .B semval
 283 for the
 284 .IR semnum \-th
 285 semaphore of the set.
 286 The calling process must have read permission on the semaphore set.
 287 .TP
 288 .B GETZCNT
 289 Return the value of
 290 .B semzcnt
 291 for the
 292 .IR semnum \-th
 293 semaphore of the set
 294 (i.e., the number of processes waiting for
 295 .B semval
 296 of the
 297 .IR semnum \-th
 298 semaphore of the set to become 0).
 299 The calling process must have read permission on the semaphore set.
 300 .TP
 301 .B SETALL
 302 Set
 303 .B semval
 304 for all semaphores of the set using
 305 .IR arg.array ,
 306 updating also the
 307 .I sem_ctime
 308 member of the
 309 .I semid_ds
 310 structure associated with the set.
 311 Undo entries (see
 312 .BR semop (2))
 313 are cleared for altered semaphores in all processes.
 314 If the changes to semaphore values would permit blocked
 315 .BR semop (2)
 316 calls in other processes to proceed, then those processes are woken up.
 317 The argument
 318 .I semnum
 319 is ignored.
 320 The calling process must have alter (write) permission on
 321 the semaphore set.
 322 .TP
 323 .B SETVAL
 324 Set the value of
 325 .B semval
 326 to
 327 .I arg.val
 328 for the
 329 .IR semnum \-th
 330 semaphore of the set, updating also the
 331 .I sem_ctime
 332 member of the
 333 .I semid_ds
 334 structure associated with the set.
 335 Undo entries are cleared for altered semaphores in all processes.
 336 If the changes to semaphore values would permit blocked
 337 .BR semop (2)
 338 calls in other processes to proceed, then those processes are woken up.
 339 The calling process must have alter permission on the semaphore set.
 340 .SH RETURN VALUE
 341 On failure,
 342 .BR semctl ()
 343 returns \-1
 344 with
 345 .I errno
 346 indicating the error.
 347
 348 Otherwise, the system call returns a nonnegative value depending on
 349 .I cmd
 350 as follows:
 351 .TP 10
 352 .B GETNCNT
 353 the value of
 354 .BR semncnt .
 355 .TP
 356 .B GETPID
 357 the value of
 358 .BR sempid .
 359 .TP
 360 .B GETVAL
 361 the value of
 362 .BR semval .
 363 .TP
 364 .B GETZCNT
 365 the value of
 366 .BR semzcnt .
 367 .TP
 368 .B IPC_INFO
 369 the index of the highest used entry in the
 370 kernel's internal array recording information about all
 371 semaphore sets.
 372 (This information can be used with repeated
 373 .B SEM_STAT
 374 operations to obtain information about all semaphore sets on the system.)
 375 .TP
 376 .B SEM_INFO
 377 as for
 378 .BR IPC_INFO .
 379 .TP
 380 .B SEM_STAT
 381 the identifier of the semaphore set whose index was given in
 382 .IR semid .
 383 .LP
 384 All other
 385 .I cmd
 386 values return 0 on success.
 387 .SH ERRORS
 388 On failure,
 389 .I errno
 390 will be set to one of the following:
 391 .TP
 392 .B EACCES
 393 The argument
 394 .I cmd
 395 has one of the values
 396 .BR GETALL ,
 397 .BR GETPID ,
 398 .BR GETVAL ,
 399 .BR GETNCNT ,
 400 .BR GETZCNT ,
 401 .BR IPC_STAT ,
 402 .BR SEM_STAT ,
 403 .BR SETALL ,
 404 or
 405 .B SETVAL
 406 and the calling process does not have the required
 407 permissions on the semaphore set and does not have the
 408 .B CAP_IPC_OWNER
 409 capability.
 410 .TP
 411 .B EFAULT
 412 The address pointed to by
 413 .I arg.buf
 414 or
 415 .I arg.array
 416 isn't accessible.
 417 .TP
 418 .B EIDRM
 419 The semaphore set was removed.
 420 .TP
 421 .B EINVAL
 422 Invalid value for
 423 .I cmd
 424 or
 425 .IR semid .
 426 Or: for a
 427 .B SEM_STAT
 428 operation, the index value specified in
 429 .I semid
 430 referred to an array slot that is currently unused.
 431 .TP
 432 .B EPERM
 433 The argument
 434 .I cmd
 435 has the value
 436 .B IPC_SET
 437 or
 438 .B IPC_RMID
 439 but the effective user ID of the calling process is not the creator
 440 (as found in
 441 .IR sem_perm.cuid )
 442 or the owner
 443 (as found in
 444 .IR sem_perm.uid )
 445 of the semaphore set,
 446 and the process does not have the
 447 .B CAP_SYS_ADMIN
 448 capability.
 449 .TP
 450 .B ERANGE
 451 The argument
 452 .I cmd
 453 has the value
 454 .B SETALL
 455 or
 456 .B SETVAL
 457 and the value to which
 458 .B semval
 459 is to be set (for some semaphore of the set) is less than 0
 460 or greater than the implementation limit
 461 .BR SEMVMX .
 462 .SH CONFORMING TO
 463 SVr4, POSIX.1-2001.
 464 .\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
 465
 466 POSIX.1-2001 specifies the
 467 .I sem_nsems
 468 field of the
 469 .I semid_ds
 470 structure as having the type
 471 .IR "unsigned\ short" ,
 472 and the field is so defined on most other systems.
 473 It was also so defined on Linux 2.2 and earlier,
 474 but, since Linux 2.4, the field has the type
 475 .IR "unsigned\ long" .
 476 .SH NOTES
 477 The inclusion of
 478 .I <sys/types.h>
 479 and
 480 .I <sys/ipc.h>
 481 isn't required on Linux or by any version of POSIX.
 482 However,
 483 some old implementations required the inclusion of these header files,
 484 and the SVID also documented their inclusion.
 485 Applications intended to be portable to such old systems may need
 486 to include these header files.
 487 .\" Like Linux, the FreeBSD man pages still document
 488 .\" the inclusion of these header files.
 489
 490 The
 491 .BR IPC_INFO ,
 492 .B SEM_STAT
 493 and
 494 .B SEM_INFO
 495 operations are used by the
 496 .BR ipcs (1)
 497 program to provide information on allocated resources.
 498 In the future these may modified or moved to a
 499 .I /proc
 500 filesystem interface.
 501 .LP
 502 Various fields in a \fIstruct semid_ds\fP were typed as
 503 .I short
 504 under Linux 2.2
 505 and have become
 506 .I long
 507 under Linux 2.4.
 508 To take advantage of this,
 509 a recompilation under glibc-2.1.91 or later should suffice.
 510 (The kernel distinguishes old and new calls by an
 511 .B IPC_64
 512 flag in
 513 .IR cmd .)
 514 .PP
 515 In some earlier versions of glibc, the
 516 .I semun
 517 union was defined in \fI<sys/sem.h>\fP, but POSIX.1-2001 requires
 518 that the caller define this union.
 519 On versions of glibc where this union is \fInot\fP defined,
 520 the macro
 521 .B _SEM_SEMUN_UNDEFINED
 522 is defined in \fI<sys/sem.h>\fP.
 523 .PP
 524 The following system limit on semaphore sets affects a
 525 .BR semctl ()
 526 call:
 527 .TP
 528 .B SEMVMX
 529 Maximum value for
 530 .BR semval :
 531 implementation dependent (32767).
 532 .LP
 533 For greater portability, it is best to always call
 534 .BR semctl ()
 535 with four arguments.
 536 .SH SEE ALSO
 537 .BR ipc (2),
 538 .BR semget (2),
 539 .BR semop (2),
 540 .BR capabilities (7),
 541 .BR sem_overview (7),
 542 .BR svipc (7)
 543 .SH COLOPHON
 544 This page is part of release 3.68 of the Linux
 545 .I man-pages
 546 project.
 547 A description of the project,
 548 information about reporting bugs,
 549 and the latest version of this page,
 550 can be found at
 551 \%http://www.kernel.org/doc/man\-pages/.