man2/semctl.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk-manpages@gmx.net>
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\"
  24 .\" Modified Tue Oct 22 17:53:56 1996 by Eric S. Raymond <esr@thyrsus.com>
  25 .\" Modified Fri Jun 19 10:59:15 1998 by Andries Brouwer <aeb@cwi.nl>
  26 .\" Modified Sun Feb 18 01:59:29 2001 by Andries Brouwer <aeb@cwi.nl>
  27 .\" Modified 20 Dec 2001, Michael Kerrisk <mtk-manpages@gmx.net>
  28 .\" Modified 21 Dec 2001, aeb
  29 .\" Modified 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net>
  30 .\"     Added notes on CAP_IPC_OWNER requirement
  31 .\" Modified 17 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net>
  32 .\"     Added notes on CAP_SYS_ADMIN requirement for IPC_SET and IPC_RMID
  33 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk-manpages@gmx.net>
  34 .\"     Language and formatting clean-ups
  35 .\"     Rewrote semun text
  36 .\"     Added semid_ds and ipc_perm structure definitions
  37 .\" 2005-08-02, mtk: Added IPC_INFO, SEM_INFO, SEM_STAT descriptions.
  38 .\"
  39 .TH SEMCTL 2 2004-11-10 "Linux 2.6.9" "Linux Programmer's Manual"
  40 .SH NAME
  41 semctl \- semaphore control operations
  42 .SH SYNOPSIS
  43 .nf
  44 .B #include <sys/types.h>
  45 .B #include <sys/ipc.h>
  46 .B #include <sys/sem.h>
  47 .sp
  48 .BI "int semctl(int " semid ", int " semnum ", int " cmd ", ...);"
  49 .fi
  50 .SH DESCRIPTION
  51 .BR semctl ()
  52 performs the control operation specified by
  53 .I cmd
  54 on the semaphore set identified by
  55 .IR semid ,
  56 or on the
  57 .IR semnum -th
  58 semaphore of that set.
  59 (The semaphores in a set are numbered starting at 0.)
  60 .PP
  61 This function has three or four arguments, depending on
  62 .IR cmd .
  63 When there are four, the fourth has the type
  64 .IR "union semun" .
  65 The \fIcalling program\fP must define this union as follows:
  66
  67 .nf
  68 .in +4n
  69 union semun {
  70     int              val;    /* Value for SETVAL */
  71     struct semid_ds *buf;    /* Buffer for IPC_STAT, IPC_SET */
  72     unsigned short  *array;  /* Array for GETALL, SETALL */
  73     struct seminfo  *__buf;  /* Buffer for IPC_INFO
  74                                 (Linux specific) */
  75 };
  76 .in -4n
  77 .fi
  78 .PP
  79 The
  80 .I semid_ds
  81 data structure is defined in <sys/sem.h> as follows:
  82 .nf
  83 .in +4n
  84
  85 struct semid_ds {
  86     struct ipc_perm sem_perm;  /* Ownership and permissions
  87     time_t          sem_otime; /* Last semop time */
  88     time_t          sem_ctime; /* Last change time */
  89     unsigned short  sem_nsems; /* No. of semaphores in set */
  90 };
  91 .in -4n
  92 .fi
  93 .PP
  94 The
  95 .I ipc_perm
  96 structure is defined in <sys/ipc.h> as follows
  97 (the highlighted fields are settable using
  98 .BR IPC_SET ):
  99 .PP
 100 .nf
 101 .in +4n
 102 struct ipc_perm {
 103     key_t key;            /* Key supplied to semget(2) */
 104     uid_t \fBuid\fP;            /* Effective UID of owner */
 105     gid_t \fBgid\fP;            /* Effective GID of owner */
 106     uid_t cuid;           /* Effective UID of creator */
 107     gid_t cgid;           /* Effective GID of creator */
 108     unsigned short \fBmode\fP;  /* Permissions */
 109     unsigned short seq;   /* Sequence number */
 110 };
 111 .in -4n
 112 .fi
 113 .PP
 114 Valid values for
 115 .I cmd
 116 are:
 117 .TP 12
 118 .B IPC_STAT
 119 Copy information from the kernel data structure associated with
 120 .I semid
 121 into the
 122 .I semid_ds
 123 structure pointed to by
 124 .IR arg.buf .
 125 The argument
 126 .I semnum
 127 is ignored.
 128 The calling process must have read permission on the semaphore set.
 129 .TP
 130 .B IPC_SET
 131 Write the values of some members of the
 132 .I semid_ds
 133 structure pointed to by
 134 .I arg.buf
 135 to the kernel data structure associated with this semaphore set,
 136 updating also its
 137 .I sem_ctime
 138 member.
 139 The following members of the structure are updated:
 140 .IR sem_perm.uid ,
 141 .IR sem_perm.gid ,
 142 and (the least significant 9 bits of)
 143 .IR sem_perm.mode .
 144 The effective UID of the calling process must match the owner
 145 .RI ( sem_perm.uid )
 146 or creator
 147 .RI ( sem_perm.cuid )
 148 of the semaphore set, or the caller must be privileged.
 149 The argument
 150 .I semnum
 151 is ignored.
 152 .TP
 153 .B IPC_RMID
 154 Immediately remove the semaphore set,
 155 awakening all processes blocked in
 156 .BR semop (2)
 157 calls on the set (with an error return and
 158 .I errno
 159 set to
 160 .BR EIDRM ).
 161 The effective user ID of the calling process must
 162 match the creator or owner of the semaphore set,
 163 or the caller must be privileged.
 164 The argument
 165 .I semnum
 166 is ignored.
 167 .TP
 168 .BR IPC_INFO " (Linux specific)"
 169 Returns information about system-wide semaphore limits and
 170 parameters in the structure pointed to by
 171 .IR arg.__buf .
 172 This structure is of type
 173 .IR seminfo ,
 174 defined in
 175 .I <sys/sem.h>
 176 if the _GNU_SOURCE feature test macro is defined:
 177 .nf
 178 .in +2n
 179
 180 struct  seminfo {
 181     int semmap;  /* # of entries in semaphore map;
 182                     unused */
 183     int semmni;  /* Max. # of semaphore sets */
 184     int semmns;  /* Max. # of semaphores in all
 185                     semaphore sets */
 186     int semmnu;  /* System-wide max. # of undo
 187                     structures; unused */
 188     int semmsl;  /* Max. # of semaphores in a set */
 189     int semopm;  /* Max. # of operations for semop(2) */
 190     int semume;  /* Max. # of undo entries per
 191                     process; unused */
 192     int semusz;  /* size of struct sem_undo */
 193     int semvmx;  /* Maximum semaphore value */
 194     int semaem;  /* Max. value that can be recorded for
 195                     semaphore adjustment (SEM_UNDO) */
 196 };
 197
 198 .in -2n
 199 .fi
 200 The
 201 .IR semmsl ,
 202 .IR semmns ,
 203 .IR semopm ,
 204 and
 205 .I semmni
 206 settings can be changed via
 207 .IR /proc/sys/kernel/sem ;
 208 see
 209 .BR proc (5)
 210 for details.
 211 .TP
 212 .BR SEM_INFO " (Linux specific)"
 213 Returns a
 214 .I seminfo
 215 structure containing the same information as for
 216 .BR IPC_INFO ,
 217 except that the following fields are returned with information
 218 about system resources consumed by semaphores: the
 219 .I semusz
 220 field returns the number of semaphore sets that currently exist
 221 on the system; and the
 222 .I semaem
 223 field returns the total number of semaphores in all semaphore sets
 224 on the system.
 225 .TP
 226 .BR SEM_STAT " (Linux specific)"
 227 Returns a
 228 .I semid_ds
 229 structure as for
 230 .BR IPC_STAT .
 231 However, the
 232 .I semid
 233 argument is not a semaphore identifier, but instead an index into
 234 the kernel's internal array that maintains information about
 235 all semaphore sets on the system.
 236 .TP
 237 .B GETALL
 238 Return
 239 .B semval
 240 (i.e., the current value)
 241 for all semaphores of the set into
 242 .IB arg.array .
 243 The argument
 244 .I semnum
 245 is ignored.
 246 The calling process must have read permission on the semaphore set.
 247 .TP
 248 .B GETNCNT
 249 The system call returns the value of
 250 .B semncnt
 251 (i.e., the number of processes waiting for the value of
 252 this semaphore to increase) for the
 253 .IR semnum \-th
 254 semaphore of the set
 255 (i.e. the number of processes waiting for an increase of
 256 .B semval
 257 for the
 258 .IR semnum \-th
 259 semaphore of the set).
 260 The calling process must have read permission on the semaphore set.
 261 .TP
 262 .B GETPID
 263 The system call returns the value of
 264 .B sempid
 265 for the
 266 .IR semnum \-th
 267 semaphore of the set
 268 (i.e. the PID of the process that executed the last
 269 .BR semop (2)
 270 call for the
 271 .IR semnum \-th
 272 semaphore of the set).
 273 The calling process must have read permission on the semaphore set.
 274 .TP
 275 .B GETVAL
 276 The system call returns the value of
 277 .B semval
 278 for the
 279 .IR semnum \-th
 280 semaphore of the set.
 281 The calling process must have read permission on the semaphore set.
 282 .TP
 283 .B GETZCNT
 284 The system call returns the value of
 285 .B semzcnt
 286 (i.e., the number of processes waiting for the value of
 287 this semaphore to become zero) for the
 288 .IR semnum \-th
 289 semaphore of the set
 290 (i.e. the number of processes waiting for
 291 .B semval
 292 of the
 293 .IR semnum \-th
 294 semaphore of the set to become 0).
 295 The calling process must have read permission on the semaphore set.
 296 .TP
 297 .B SETALL
 298 Set
 299 .B semval
 300 for all semaphores of the set using
 301 .IB arg.array ,
 302 updating also the
 303 .I sem_ctime
 304 member of the
 305 .I semid_ds
 306 structure associated with the set.
 307 Undo entries (see
 308 .BR semop (2))
 309 are cleared for altered semaphores in all processes.
 310 If the changes to semaphore values would permit blocked
 311 .BR semop (2)
 312 calls in other processes to proceed, then those processes are woken up.
 313 The argument
 314 .I semnum
 315 is ignored.
 316 The calling process must have alter (write) permission on
 317 the semaphore set.
 318 .TP
 319 .B SETVAL
 320 Set the value of
 321 .B semval
 322 to
 323 .IB arg.val
 324 for the
 325 .IR semnum \-th
 326 semaphore of the set, updating also the
 327 .I sem_ctime
 328 member of the
 329 .I semid_ds
 330 structure associated with the set.
 331 Undo entries are cleared for altered semaphores in all processes.
 332 If the changes to semaphore values would permit blocked
 333 .BR semop (2)
 334 calls in other processes to proceed, then those processes are woken up.
 335 The calling process must have alter permission on the semaphore set.
 336 .SH "RETURN VALUE"
 337 On failure
 338 .BR semctl ()
 339 returns \-1
 340 with
 341 .I errno
 342 indicating the error.
 343
 344 Otherwise the system call returns a non-negative value depending on
 345 .I cmd
 346 as follows:
 347 .TP 11
 348 .B GETNCNT
 349 the value of
 350 .BR semncnt .
 351 .TP
 352 .B GETPID
 353 the value of
 354 .BR sempid .
 355 .TP
 356 .B GETVAL
 357 the value of
 358 .BR semval .
 359 .TP
 360 .B GETZCNT
 361 the value of
 362 .BR semzcnt .
 363 .TP
 364 .B IPC_INFO
 365 the index of the highest used entry in the
 366 kernel's internal array recording information about all
 367 semaphore sets.
 368 (This information can be used with repeated
 369 .B SEM_STAT
 370 operations to obtain information about all semaphore sets on the system.)
 371 .TP
 372 .B SEM_INFO
 373 As for
 374 .BR IPC_INFO .
 375 .TP
 376 .B SEM_STAT
 377 the identifier of the semaphore set whose index was given in
 378 .IR semid .
 379 .LP
 380 All other
 381 .I cmd
 382 values return 0 on success.
 383 .SH ERRORS
 384 On failure,
 385 .I errno
 386 will be set to one of the following:
 387 .TP 11
 388 .B EACCES
 389 The argument
 390 .I cmd
 391 has one of the values
 392 .BR GETALL ,
 393 .BR GETPID ,
 394 .BR GETVAL ,
 395 .BR GETNCNT ,
 396 .BR GETZCNT ,
 397 .BR IPC_STAT ,
 398 .BR SEM_STAT ,
 399 .BR SETALL ,
 400 or
 401 .B SETVAL
 402 and the calling process does not have the required
 403 permissions on the semaphore set and does not have the
 404 .B CAP_IPC_OWNER
 405 capability.
 406 .TP
 407 .B EFAULT
 408 The address pointed to by
 409 .IB arg.buf
 410 or
 411 .IB arg.array
 412 isn't accessible.
 413 .TP
 414 .B EIDRM
 415 The semaphore set was removed.
 416 .TP
 417 .B EINVAL
 418 Invalid value for
 419 .I cmd
 420 or
 421 .IR semid .
 422 Or: for a
 423 .B SEM_STAT
 424 operation, the index value specified in
 425 .I semid
 426 referred to an array slot that is currently unused.
 427 .TP
 428 .B EPERM
 429 The argument
 430 .I cmd
 431 has the value
 432 .B IPC_SET
 433 or
 434 .B IPC_RMID
 435 but the effective user ID of the calling process is not the creator
 436 (as found in
 437 .IR sem_perm.cuid )
 438 or the owner
 439 (as found in
 440 .IR sem_perm.uid )
 441 of the semaphore set,
 442 and the process does not have the
 443 .B CAP_SYS_ADMIN
 444 capability.
 445 .TP
 446 .B ERANGE
 447 The argument
 448 .I cmd
 449 has the value
 450 .B SETALL
 451 or
 452 .B SETVAL
 453 and the value to which
 454 .B semval
 455 is to be set (for some semaphore of the set) is less than 0
 456 or greater than the implementation limit
 457 .BR SEMVMX .
 458 .SH "CONFORMING TO"
 459 SVr4, POSIX.1-2001.
 460 .\" SVr4 documents more error conditions EINVAL and EOVERFLOW.
 461 .SH NOTES
 462 The
 463 .BR IPC_INFO ,
 464 .BR SEM_STAT
 465 and
 466 .B SEM_INFO
 467 operations are used by the
 468 .BR ipcs (8)
 469 program to provide information on allocated resources.
 470 In the future these may modified or moved to a /proc file system
 471 interface.
 472 .LP
 473 Various fields in a \fIstruct semid_ds\fP were shorts under Linux 2.2
 474 and have become longs under Linux 2.4. To take advantage of this,
 475 a recompilation under glibc-2.1.91 or later should suffice.
 476 (The kernel distinguishes old and new calls by an IPC_64 flag in
 477 .IR cmd .)
 478 .PP
 479 In some earlier versions of glibc, the
 480 .I semun
 481 union was defined in <sys/sem.h>, but POSIX.1-2001 requires
 482 that the caller define this union.
 483 On versions of glibc where this union is \fInot\fP defined,
 484 the macro
 485 .B _SEM_SEMUN_UNDEFINED
 486 is defined in <sys/sem.h>.
 487 .PP
 488 The following system limit on semaphore sets affects a
 489 .BR semctl ()
 490 call:
 491 .TP 11
 492 .B SEMVMX
 493 Maximum value for
 494 .BR semval :
 495 implementation dependent (32767).
 496 .LP
 497 For greater portability it is best to always call
 498 .BR semctl ()
 499 with four arguments.
 500 .LP
 501 Under Linux,
 502 .BR semctl ()
 503 is not a system call, but is implemented via the system call
 504 .BR ipc (2).
 505 .SH "SEE ALSO"
 506 .BR ipc (2),
 507 .BR semget (2),
 508 .BR semop (2),
 509 .BR capabilities (7),
 510 .BR sem_overview (7),
 511 .BR svipc (7)