lib/libc/sys/semop.2

   1 .\"     $NetBSD: semop.2,v 1.17 2010/03/22 19:30:55 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 1995 Frank van der Linden
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"      This product includes software developed for the NetBSD Project
  17 .\"      by Frank van der Linden
  18 .\" 4. The name of the author may not be used to endorse or promote products
  19 .\"    derived from this software without specific prior written permission
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  22 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  23 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  24 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  25 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  26 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  30 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31 .\"
  32 .Dd November 3, 2005
  33 .Dt SEMOP 2
  34 .Os
  35 .Sh NAME
  36 .Nm semop
  37 .Nd semaphore operations
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/sem.h
  42 .Ft int
  43 .Fn semop "int semid" "struct sembuf *sops" "size_t nsops"
  44 .Sh DESCRIPTION
  45 .Fn semop
  46 provides a number of atomic operations on a set of semaphores.
  47 The semaphore set is specified by
  48 .Fa semid ,
  49 .Fa sops
  50 is an array of semaphore operations, and
  51 .Fa nsops
  52 is the number of operations in this array.
  53 The
  54 .Va sembuf
  55 structures in the array contain the following members:
  56 .Bd -literal
  57     unsigned short sem_num; /* semaphore # */
  58     short          sem_op;  /* semaphore operation */
  59     short          sem_flg; /* operation flags */
  60 .Ed
  61 .Pp
  62 Each operation (specified in
  63 .Va sem_op )
  64 is applied to semaphore number
  65 .Va sem_num
  66 in the set of semaphores specified by
  67 .Fa semid .
  68 The value of
  69 .Va sem_op
  70 determines the action taken in the following way:
  71 .Bl -bullet
  72 .It
  73 .Va sem_op
  74 is less than 0.
  75 The current process is blocked until the value of the
  76 semaphore is greater than or equal to the absolute value of
  77 .Va sem_op .
  78 The absolute value of
  79 .Va sem_op
  80 is then subtracted from the value of the semaphore, and the calling
  81 process continues.
  82 Negative values of
  83 .Va sem_op
  84 are thus used to enter critical regions.
  85 .It
  86 .Va sem_op
  87 is greater than 0.
  88 Its value is added to the value of the specified semaphore.
  89 This is used to leave critical regions.
  90 .It
  91 .Va sem_op
  92 is equal to 0.
  93 The calling process is blocked until the value of the
  94 specified semaphore reaches 0.
  95 .El
  96 .Pp
  97 The behaviour of each operation is influenced by the flags set in
  98 .Va sem_flg
  99 in the following way:
 100 .Bl -tag -width IPC_NOWAITX
 101 .It Dv IPC_NOWAIT
 102 In the case where the calling process would normally block, waiting
 103 for a semaphore to reach a certain value,
 104 .Dv IPC_NOWAIT
 105 makes the
 106 call return immediately, returning a value of \-1 and setting
 107 .Va errno
 108 to
 109 .Er EAGAIN .
 110 .It SEM_UNDO
 111 Keep track of the changes that this call makes to the value of a semaphore,
 112 so that they can be undone when the calling process terminates.
 113 This is useful to prevent other processes waiting on a semaphore to block
 114 forever, should the process that has the semaphore locked terminate in a
 115 critical section.
 116 .El
 117 .Sh RETURN VALUES
 118 Upon successful completion, a value of 0 is returned.
 119 Otherwise, \-1 is returned and the global variable
 120 .Va errno
 121 is set to indicate the error.
 122 .Sh ERRORS
 123 .Fn semop
 124 will fail if:
 125 .Bl -tag -width Er
 126 .It Bq Er EINVAL
 127 There is no semaphore associated with
 128 .Fa semid .
 129 .It Bq Er EIDRM
 130 The semaphore set was removed while the process was waiting for one of
 131 its semaphores to reach a certain value.
 132 .It Bq Er EACCES
 133 The calling process has no permission to access the specified semaphore set.
 134 .It Bq Er E2BIG
 135 The value of
 136 .Fa nsops
 137 is too big.
 138 The maximum is defined as
 139 .Dv MAX_SOPS
 140 in
 141 .In sys/sem.h .
 142 .It Bq Er EFBIG
 143 .Va sem_num
 144 in one of the sem_buf structures is less than 0, or greater than the actual
 145 number of semaphores in the set specified by
 146 .Fa semid .
 147 .It Bq Er ENOSPC
 148 .Dv SEM_UNDO
 149 was requested, and there is not enough space left in the kernel to
 150 store the undo information.
 151 .It Bq Er EAGAIN
 152 The requested operation can not immediately be performed, and
 153 .Dv IPC_NOWAIT
 154 was set in
 155 .Va sem_flg .
 156 .It Bq Er EFAULT
 157 .Fa sops
 158 points to an illegal address.
 159 .El
 160 .Sh SEE ALSO
 161 .Xr semctl 2 ,
 162 .Xr semget 2
 163 .Sh STANDARDS
 164 The
 165 .Nm
 166 system call conforms to
 167 .St -xsh5 .
 168 .Sh HISTORY
 169 Semaphores appeared in the first release of
 170 .At V .