lib/libc/sys/semop.2

   1 .\"
   2 .\" Copyright (c) 1995 David Hovemeyer <daveho@infocom.com>
   3 .\"
   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 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
  16 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  17 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  18 .\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
  19 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  20 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  21 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  22 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  24 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/lib/libc/sys/semop.2,v 1.7.2.6 2001/12/14 18:34:01 ru Exp $
  27 .\"
  28 .Dd January 4, 2014
  29 .Dt SEMOP 2
  30 .Os
  31 .Sh NAME
  32 .Nm semop
  33 .Nd atomic array of operations on a semaphore set
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/types.h
  38 .In sys/ipc.h
  39 .In sys/sem.h
  40 .Ft int
  41 .Fn semop "int semid" "struct sembuf array[]" "unsigned nops"
  42 .Sh DESCRIPTION
  43 .Fn Semop
  44 atomically performs the array of operations indicated by
  45 .Fa array
  46 on the semaphore set indicated by
  47 .Fa semid .
  48 The length of
  49 .Fa array
  50 is indicated by
  51 .Fa nops .
  52 Each operation is encoded in a
  53 .Fa "struct sembuf" ,
  54 which is defined as follows:
  55 .Bd -literal
  56 .\"
  57 .\" From <sys/sem.h>
  58 .\"
  59 struct sembuf {
  60         u_short sem_num;        /* semaphore # */
  61         short   sem_op;         /* semaphore operation */
  62         short   sem_flg;        /* operation flags */
  63 };
  64 .Ed
  65 .Pp
  66 For each element in
  67 .Fa array ,
  68 .Fa sem_op
  69 and
  70 .Fa sem_flg
  71 determine an operation to be performed on semaphore number
  72 .Fa sem_num
  73 in the set.
  74 The values
  75 .Dv SEM_UNDO
  76 and
  77 .Dv IPC_NOWAIT
  78 may be
  79 .Em OR Ns 'ed
  80 into the
  81 .Fa sem_flg
  82 member in order to modify the behavior of the given operation.
  83 .Pp
  84 The operation performed depends as follows on the value of
  85 .Fa sem_op :
  86 .\"
  87 .\" This section is based on the description of semop() in
  88 .\" Stevens, _Advanced Programming in the UNIX Environment_.
  89 .\"
  90 .Bl -bullet
  91 .It
  92 When
  93 .Fa sem_op
  94 is positive, the semaphore's value is incremented by
  95 .Fa sem_op Ns 's
  96 value.
  97 If
  98 .Dv SEM_UNDO
  99 is specified, the semaphore's adjust on exit value is decremented by
 100 .Fa sem_op Ns 's
 101 value.
 102 A positive value for
 103 .Fa sem_op
 104 generally corresponds to a process releasing a resource
 105 associated with the semaphore.
 106 .It
 107 The behavior when
 108 .Fa sem_op
 109 is negative depends on the current value of the semaphore:
 110 .Bl -bullet
 111 .It
 112 If the current value of the semaphore is greater than or equal to
 113 the absolute value of
 114 .Fa sem_op ,
 115 then the value is decremented by the absolute value of
 116 .Fa sem_op .
 117 If
 118 .Dv SEM_UNDO
 119 is specified, the semaphore's adjust on exit
 120 value is incremented by the absolute value of
 121 .Fa sem_op .
 122 .It
 123 If the current value of the semaphore is less than
 124 .Fa sem_op Ns 's
 125 value, one of the following happens:
 126 .\" XXX a *second* sublist?
 127 .Bl -bullet
 128 .It
 129 If
 130 .Dv IPC_NOWAIT
 131 was specified, then
 132 .Fn semop
 133 returns immediately with a return value of
 134 .Er EAGAIN .
 135 .It
 136 If some other process has removed the semaphore with the
 137 .Dv IPC_RMID
 138 option of
 139 .Fn semctl ,
 140 then
 141 .Fn semop
 142 returns immediately with a return value of
 143 .Er EINVAL .
 144 .It
 145 Otherwise, the calling process is put to sleep until the semaphore's
 146 value is greater than or equal to the absolute value of
 147 .Fa sem_op .
 148 When this condition becomes true, the semaphore's value is decremented
 149 by the absolute value of
 150 .Fa sem_op ,
 151 and the semaphore's adjust on exit value is incremented by the
 152 absolute value of
 153 .Fa sem_op .
 154 .El
 155 .Pp
 156 A negative value for
 157 .Fa sem_op
 158 generally means that a process is waiting for a resource to become
 159 available.
 160 .El
 161 .It
 162 When
 163 .Fa sem_op
 164 is zero, the process waits for the semaphore's value to become zero.
 165 If it is already zero, the call to
 166 .Fn semop
 167 can return immediately.
 168 Otherwise, the calling process is put to
 169 sleep until the semaphore's value becomes zero.
 170 .El
 171 .Pp
 172 For each semaphore a process has in use, the kernel maintains an
 173 `adjust on exit' value, as alluded to earlier.
 174 When a process
 175 exits, either voluntarily or involuntarily, the adjust on exit value
 176 for each semaphore is added to the semaphore's value.
 177 This can
 178 be used to insure that a resource is released if a process terminates
 179 unexpectedly.
 180 .Sh RETURN VALUES
 181 .Rv -std semop
 182 .Sh ENVIRONMENT
 183 The XSI Interprocess Communication family of functions is also available
 184 as an implementation in userspace.
 185 To use it, the
 186 .Xr sysvipcd 8
 187 daemon has to be running.
 188 .Pp
 189 If the
 190 .Ev USR_SYSVIPC
 191 variable is set in a process' environment, the process and its children
 192 will use the userspace implementation.
 193 .Sh ERRORS
 194 .Fn Semop
 195 will fail if:
 196 .Bl -tag -width Er
 197 .It Bq Er EINVAL
 198 No semaphore set corresponds to
 199 .Fa semid .
 200 .It Bq Er EACCES
 201 Permission denied due to mismatch between operation and mode of
 202 semaphore set.
 203 .It Bq Er EAGAIN
 204 The semaphore's value was less than
 205 .Fa sem_op ,
 206 and
 207 .Dv IPC_NOWAIT
 208 was specified.
 209 .It Bq Er E2BIG
 210 Too many operations were specified.
 211 .It Bq Er EFBIG
 212 .\"
 213 .\" I'd have thought this would be EINVAL, but the source says
 214 .\" EFBIG.
 215 .\"
 216 .Fa sem_num
 217 was not in the range of valid semaphores for the set.
 218 .El
 219 .Sh SEE ALSO
 220 .Xr semctl 2 ,
 221 .Xr semget 2
 222 .Sh AUTHORS
 223 .An -nosplit
 224 The
 225 .Dx
 226 specific userspace implementation (see
 227 .Sx ENVIRONMENT )
 228 was written by
 229 .An Larisa Grigore .