manual/LDP_man-pages/original/man2/semop.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified 1996-10-22, Eric S. Raymond <esr@thyrsus.com>
  24 .\" Modified 2002-01-08, Michael Kerrisk <mtk.manpages@gmail.com>
  25 .\" Modified 2003-04-28, Ernie Petrides <petrides@redhat.com>
  26 .\" Modified 2004-05-27, Michael Kerrisk <mtk.manpages@gmail.com>
  27 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  28 .\"     Language and formatting clean-ups
  29 .\"     Added notes on /proc files
  30 .\" 2005-04-08, mtk, Noted kernel version numbers for semtimedop()
  31 .\" 2007-07-09, mtk, Added an EXAMPLE code segment.
  32 .\"
  33 .TH SEMOP 2 2008-10-04 "Linux" "Linux Programmer's Manual"
  34 .SH NAME
  35 semop, semtimedop \- semaphore operations
  36 .SH SYNOPSIS
  37 .nf
  38 .B #include <sys/types.h>
  39 .B #include <sys/ipc.h>
  40 .B #include <sys/sem.h>
  41 .sp
  42 .BI "int semop(int " semid ", struct sembuf *" sops ", unsigned " nsops );
  43 .sp
  44 .BI "int semtimedop(int " semid ", struct sembuf *" sops ", unsigned " nsops ,
  45 .BI "               struct timespec *" timeout );
  46 .fi
  47 .sp
  48 .in -4n
  49 Feature Test Macro Requirements for glibc (see
  50 .BR feature_test_macros (7)):
  51 .in
  52 .sp
  53 .BR semtimedop ():
  54 _GNU_SOURCE
  55 .SH DESCRIPTION
  56 Each semaphore in a semaphore set has the following associated values:
  57 .sp
  58 .in +4n
  59 .nf
  60 unsigned short  semval;   /* semaphore value */
  61 unsigned short  semzcnt;  /* # waiting for zero */
  62 unsigned short  semncnt;  /* # waiting for increase */
  63 pid_t           sempid;   /* process that did last op */
  64 .sp
  65 .in -4n
  66 .fi
  67 .BR semop ()
  68 performs operations on selected semaphores in the set indicated by
  69 .IR semid .
  70 Each of the
  71 .I nsops
  72 elements in the array pointed to by
  73 .I sops
  74 specifies an operation to be performed on a single semaphore.
  75 The elements of this structure are of type
  76 .IR "struct sembuf" ,
  77 containing the following members:
  78 .sp
  79 .in +4n
  80 .nf
  81 unsigned short sem_num;  /* semaphore number */
  82 short          sem_op;   /* semaphore operation */
  83 short          sem_flg;  /* operation flags */
  84 .sp
  85 .in -4n
  86 .fi
  87 Flags recognized in
  88 .I sem_flg
  89 are
  90 .B IPC_NOWAIT
  91 and
  92 .BR SEM_UNDO .
  93 If an operation specifies
  94 .BR SEM_UNDO ,
  95 it will be automatically undone when the process terminates.
  96 .PP
  97 The set of operations contained in
  98 .I sops
  99 is performed in
 100 .IR "array order" ,
 101 and
 102 .IR atomically ,
 103 that is, the operations are performed either as a complete unit,
 104 or not at all.
 105 The behavior of the system call if not all operations can be
 106 performed immediately depends on the presence of the
 107 .B IPC_NOWAIT
 108 flag in the individual
 109 .I sem_flg
 110 fields, as noted below.
 111
 112 Each operation is performed on the
 113 .IR sem_num \-th
 114 semaphore of the semaphore set, where the first semaphore of the set
 115 is numbered 0.
 116 There are three types of operation, distinguished by the value of
 117 .IR sem_op .
 118 .PP
 119 If
 120 .I sem_op
 121 is a positive integer, the operation adds this value to
 122 the semaphore value
 123 .RI  ( semval ).
 124 Furthermore, if
 125 .B SEM_UNDO
 126 is specified for this operation, the system updates the process undo count
 127 .RI ( semadj )
 128 for this semaphore.
 129 This operation can always proceed \(em it never forces a process to wait.
 130 The calling process must have alter permission on the semaphore set.
 131 .PP
 132 If
 133 .I sem_op
 134 is zero, the process must have read permission on the semaphore
 135 set.
 136 This is a "wait-for-zero" operation: if
 137 .I semval
 138 is zero, the operation can immediately proceed.
 139 Otherwise, if
 140 .B IPC_NOWAIT
 141 is specified in
 142 .IR sem_flg ,
 143 .BR semop ()
 144 fails with
 145 .I errno
 146 set to
 147 .B EAGAIN
 148 (and none of the operations in
 149 .I sops
 150 is performed).
 151 Otherwise
 152 .I semzcnt
 153 (the count of processes waiting until this semaphore's value becomes zero)
 154 is incremented by one and the process sleeps until
 155 one of the following occurs:
 156 .IP \(bu 3
 157 .I semval
 158 becomes 0, at which time the value of
 159 .I semzcnt
 160 is decremented.
 161 .IP \(bu
 162 The semaphore set
 163 is removed:
 164 .BR semop ()
 165 fails, with
 166 .I errno
 167 set to
 168 .BR EIDRM .
 169 .IP \(bu
 170 The calling process catches a signal:
 171 the value of
 172 .I semzcnt
 173 is decremented and
 174 .BR semop ()
 175 fails, with
 176 .I errno
 177 set to
 178 .BR EINTR .
 179 .IP \(bu
 180 The time limit specified by
 181 .I timeout
 182 in a
 183 .BR semtimedop ()
 184 call expires:
 185 .BR semop ()
 186 fails, with
 187 .I errno
 188 set to
 189 .BR EAGAIN .
 190 .PP
 191 If
 192 .I sem_op
 193 is less than zero, the process must have alter permission on the
 194 semaphore set.
 195 If
 196 .I semval
 197 is greater than or equal to the absolute value of
 198 .IR sem_op ,
 199 the operation can proceed immediately:
 200 the absolute value of
 201 .I sem_op
 202 is subtracted from
 203 .IR semval ,
 204 and, if
 205 .B SEM_UNDO
 206 is specified for this operation, the system updates the process undo count
 207 .RI ( semadj )
 208 for this semaphore.
 209 If the absolute value of
 210 .I sem_op
 211 is greater than
 212 .IR semval ,
 213 and
 214 .B IPC_NOWAIT
 215 is specified in
 216 .IR sem_flg ,
 217 .BR semop ()
 218 fails, with
 219 .I errno
 220 set to
 221 .B EAGAIN
 222 (and none of the operations in
 223 .I sops
 224 is performed).
 225 Otherwise
 226 .I semncnt
 227 (the counter of processes waiting for this semaphore's value to increase)
 228 is incremented by one and the process sleeps until
 229 one of the following occurs:
 230 .IP \(bu 3
 231 .I semval
 232 becomes greater than or equal to the absolute value of
 233 .IR sem_op ,
 234 at which time the value of
 235 .I semncnt
 236 is decremented, the absolute value of
 237 .I sem_op
 238 is subtracted from
 239 .I semval
 240 and, if
 241 .B SEM_UNDO
 242 is specified for this operation, the system updates the process undo count
 243 .RI ( semadj )
 244 for this semaphore.
 245 .IP \(bu
 246 The semaphore set is removed from the system:
 247 .BR semop ()
 248 fails, with
 249 .I errno
 250 set to
 251 .BR EIDRM .
 252 .IP \(bu
 253 The calling process catches a signal:
 254 the value of
 255 .I semncnt
 256 is decremented and
 257 .BR semop ()
 258 fails, with
 259 .I errno
 260 set to
 261 .BR EINTR .
 262 .IP \(bu
 263 The time limit specified by
 264 .I timeout
 265 in a
 266 .BR semtimedop ()
 267 call expires: the system call fails, with
 268 .I errno
 269 set to
 270 .BR EAGAIN .
 271 .PP
 272 On successful completion, the
 273 .I sempid
 274 value for each semaphore specified in the array pointed to by
 275 .I sops
 276 is set to the process ID of the calling process.
 277 In addition, the
 278 .I sem_otime
 279 .\" and
 280 .\" .I sem_ctime
 281 is set to the current time.
 282 .PP
 283 .BR semtimedop ()
 284 behaves identically to
 285 .BR semop ()
 286 except that in those cases were the calling process would sleep,
 287 the duration of that sleep is limited by the amount of elapsed
 288 time specified by the
 289 .I timespec
 290 structure whose address is passed in the
 291 .I timeout
 292 argument.
 293 If the specified time limit has been reached,
 294 .BR semtimedop ()
 295 fails with
 296 .I errno
 297 set to
 298 .B EAGAIN
 299 (and none of the operations in
 300 .I sops
 301 is performed).
 302 If the
 303 .I timeout
 304 argument is NULL,
 305 then
 306 .BR semtimedop ()
 307 behaves exactly like
 308 .BR semop ().
 309 .SH "RETURN VALUE"
 310 If successful
 311 .BR semop ()
 312 and
 313 .BR semtimedop ()
 314 return 0;
 315 otherwise they return \-1
 316 with
 317 .I errno
 318 indicating the error.
 319 .SH ERRORS
 320 On failure,
 321 .I errno
 322 is set to one of the following:
 323 .TP
 324 .B E2BIG
 325 The argument
 326 .I nsops
 327 is greater than
 328 .BR SEMOPM ,
 329 the maximum number of operations allowed per system
 330 call.
 331 .TP
 332 .B EACCES
 333 The calling process does not have the permissions required
 334 to perform the specified semaphore operations,
 335 and does not have the
 336 .B CAP_IPC_OWNER
 337 capability.
 338 .TP
 339 .B EAGAIN
 340 An operation could not proceed immediately and either
 341 .B IPC_NOWAIT
 342 was specified in
 343 .I sem_flg
 344 or the time limit specified in
 345 .I timeout
 346 expired.
 347 .TP
 348 .B EFAULT
 349 An address specified in either the
 350 .I sops
 351 or the
 352 .I timeout
 353 argument isn't accessible.
 354 .TP
 355 .B EFBIG
 356 For some operation the value of
 357 .I sem_num
 358 is less than 0 or greater than or equal to the number
 359 of semaphores in the set.
 360 .TP
 361 .B EIDRM
 362 The semaphore set was removed.
 363 .TP
 364 .B EINTR
 365 While blocked in this system call, the process caught a signal; see
 366 .BR signal (7).
 367 .TP
 368 .B EINVAL
 369 The semaphore set doesn't exist, or
 370 .I semid
 371 is less than zero, or
 372 .I nsops
 373 has a nonpositive value.
 374 .TP
 375 .B ENOMEM
 376 The
 377 .I sem_flg
 378 of some operation specified
 379 .B SEM_UNDO
 380 and the system does not have enough memory to allocate the undo
 381 structure.
 382 .TP
 383 .B ERANGE
 384 For some operation
 385 .I sem_op+semval
 386 is greater than
 387 .BR SEMVMX ,
 388 the implementation dependent maximum value for
 389 .IR semval .
 390 .SH VERSIONS
 391 .BR semtimedop ()
 392 first appeared in Linux 2.5.52,
 393 and was subsequently backported into kernel 2.4.22.
 394 Glibc support for
 395 .BR semtimedop ()
 396 first appeared in version 2.3.3.
 397 .SH "CONFORMING TO"
 398 SVr4, POSIX.1-2001.
 399 .\" SVr4 documents additional error conditions EINVAL, EFBIG, ENOSPC.
 400 .SH NOTES
 401 The
 402 .I sem_undo
 403 structures of a process aren't inherited by the child produced by
 404 .BR fork (2),
 405 but they are inherited across an
 406 .BR execve (2)
 407 system call.
 408 .PP
 409 .BR semop ()
 410 is never automatically restarted after being interrupted by a signal handler,
 411 regardless of the setting of the
 412 .B SA_RESTART
 413 flag when establishing a signal handler.
 414 .PP
 415 .I semadj
 416 is a per-process integer which is simply the (negative) count
 417 of all semaphore operations performed specifying the
 418 .B SEM_UNDO
 419 flag.
 420 When a semaphore's value is directly set using the
 421 .B SETVAL
 422 or
 423 .B SETALL
 424 request to
 425 .BR semctl (2),
 426 the corresponding
 427 .I semadj
 428 values in all processes are cleared.
 429 .PP
 430 The \fIsemval\fP, \fIsempid\fP, \fIsemzcnt\fP, and \fIsemnct\fP values
 431 for a semaphore can all be retrieved using appropriate
 432 .BR semctl (2)
 433 calls.
 434 .PP
 435 The following limits on semaphore set resources affect the
 436 .BR semop ()
 437 call:
 438 .TP
 439 .B SEMOPM
 440 Maximum number of operations allowed for one
 441 .BR semop ()
 442 call (32)
 443 (on Linux, this limit can be read and modified via the third field of
 444 .IR /proc/sys/kernel/sem ).
 445 .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 446 .TP
 447 .B SEMVMX
 448 Maximum allowable value for
 449 .IR semval :
 450 implementation dependent (32767).
 451 .PP
 452 The implementation has no intrinsic limits for
 453 the adjust on exit maximum value
 454 .RB ( SEMAEM ),
 455 the system wide maximum number of undo structures
 456 .RB ( SEMMNU )
 457 and the per-process maximum number of undo entries system parameters.
 458 .SH BUGS
 459 When a process terminates, its set of associated
 460 .I semadj
 461 structures is used to undo the effect of all of the
 462 semaphore operations it performed with the
 463 .B SEM_UNDO
 464 flag.
 465 This raises a difficulty: if one (or more) of these semaphore adjustments
 466 would result in an attempt to decrease a semaphore's value below zero,
 467 what should an implementation do?
 468 One possible approach would be to block until all the semaphore
 469 adjustments could be performed.
 470 This is however undesirable since it could force process termination to
 471 block for arbitrarily long periods.
 472 Another possibility is that such semaphore adjustments could be ignored
 473 altogether (somewhat analogously to failing when
 474 .B IPC_NOWAIT
 475 is specified for a semaphore operation).
 476 Linux adopts a third approach: decreasing the semaphore value
 477 as far as possible (i.e., to zero) and allowing process
 478 termination to proceed immediately.
 479
 480 In kernels 2.6.x, x <= 10, there is a bug that in some circumstances
 481 prevents a process that is waiting for a semaphore value to become
 482 zero from being woken up when the value does actually become zero.
 483 This bug is fixed in kernel 2.6.11.
 484 .\" The bug report:
 485 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110260821123863&w=2
 486 .\" the fix:
 487 .\" http://marc.theaimsgroup.com/?l=linux-kernel&m=110261701025794&w=2
 488 .SH EXAMPLE
 489 The following code segment uses
 490 .BR semop ()
 491 to atomically wait for the value of semaphore 0 to become zero,
 492 and then increment the semaphore value by one.
 493 .nf
 494
 495     struct sembuf sops[2];
 496     int semid;
 497
 498     /* Code to set \fIsemid\fP omitted */
 499
 500     sops[0].sem_num = 0;        /* Operate on semaphore 0 */
 501     sops[0].sem_op = 0;         /* Wait for value to equal 0 */
 502     sops[0].sem_flg = 0;
 503
 504     sops[1].sem_num = 0;        /* Operate on semaphore 0 */
 505     sops[1].sem_op = 1;         /* Increment value by one */
 506     sops[1].sem_flg = 0;
 507
 508     if (semop(semid, sops, 2) == \-1) {
 509         perror("semop");
 510         exit(EXIT_FAILURE);
 511     }
 512 .fi
 513 .SH "SEE ALSO"
 514 .BR semctl (2),
 515 .BR semget (2),
 516 .BR sigaction (2),
 517 .BR capabilities (7),
 518 .BR sem_overview (7),
 519 .BR svipc (7),
 520 .BR time (7)