lib/libc/gen/sem_open.3

   1 .\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  17 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  19 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
  20 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  21 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  22 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
  23 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  25 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  26 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd January 9, 2010
  29 .Dt SEM_OPEN 3
  30 .Os
  31 .Sh NAME
  32 .Nm sem_open ,
  33 .Nm sem_close ,
  34 .Nm sem_unlink
  35 .Nd named semaphore operations
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In semaphore.h
  40 .Ft "sem_t *"
  41 .Fn sem_open "const char *name" "int oflag" ...
  42 .Ft int
  43 .Fn sem_close "sem_t *sem"
  44 .Ft int
  45 .Fn sem_unlink "const char *name"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn sem_open
  49 function creates or opens the named semaphore specified by
  50 .Fa name .
  51 The returned semaphore may be used in subsequent calls to
  52 .Xr sem_getvalue 3 ,
  53 .Xr sem_wait 3 ,
  54 .Xr sem_trywait 3 ,
  55 .Xr sem_post 3 ,
  56 and
  57 .Fn sem_close .
  58 .Pp
  59 This implementation places strict requirements on the value of
  60 .Fa name :
  61 it must begin with a slash
  62 .Pq Ql /
  63 and contain no other slash characters.
  64 .Pp
  65 The following bits may be set in the
  66 .Fa oflag
  67 argument:
  68 .Bl -tag -width ".Dv O_CREAT"
  69 .It Dv O_CREAT
  70 Create the semaphore if it does not already exist.
  71 .Pp
  72 The third argument to the call to
  73 .Fn sem_open
  74 must be of type
  75 .Vt mode_t
  76 and specifies the mode for the semaphore.
  77 Only the
  78 .Dv S_IWUSR , S_IWGRP ,
  79 and
  80 .Dv S_IWOTH
  81 bits are examined;
  82 it is not possible to grant only
  83 .Dq read
  84 permission on a semaphore.
  85 The mode is modified according to the process's file creation
  86 mask; see
  87 .Xr umask 2 .
  88 .Pp
  89 The fourth argument must be an
  90 .Vt "unsigned int"
  91 and specifies the initial value for the semaphore,
  92 and must be no greater than
  93 .Dv SEM_VALUE_MAX .
  94 .It Dv O_EXCL
  95 Create the semaphore if it does not exist.
  96 If the semaphore already exists,
  97 .Fn sem_open
  98 will fail.
  99 This flag is ignored unless
 100 .Dv O_CREAT
 101 is also specified.
 102 .El
 103 .Pp
 104 The
 105 .Fn sem_close
 106 function closes a named semaphore that was opened by a call to
 107 .Fn sem_open .
 108 .Pp
 109 The
 110 .Fn sem_unlink
 111 function removes the semaphore named
 112 .Fa name .
 113 Resources allocated to the semaphore are only deallocated when all
 114 processes that have the semaphore open close it.
 115 .Sh RETURN VALUES
 116 If successful,
 117 the
 118 .Fn sem_open
 119 function returns the address of the opened semaphore.
 120 If the same
 121 .Fa name
 122 argument is given to multiple calls to
 123 .Fn sem_open
 124 by the same process without an intervening call to
 125 .Fn sem_close ,
 126 the same address is returned each time.
 127 If the semaphore cannot be opened,
 128 .Fn sem_open
 129 returns
 130 .Dv SEM_FAILED
 131 and the global variable
 132 .Va errno
 133 is set to indicate the error.
 134 .Pp
 135 .Rv -std sem_close sem_unlink
 136 .Sh ERRORS
 137 The
 138 .Fn sem_open
 139 function will fail if:
 140 .Bl -tag -width Er
 141 .It Bq Er EACCES
 142 The semaphore exists and the permissions specified by
 143 .Fa oflag
 144 at the time it was created deny access to this process.
 145 .It Bq Er EACCES
 146 The semaphore does not exist, but permission to create it is denied.
 147 .It Bq Er EEXIST
 148 .Dv O_CREAT
 149 and
 150 .Dv O_EXCL
 151 are set but the semaphore already exists.
 152 .It Bq Er EINTR
 153 The call was interrupted by a signal.
 154 .It Bq Er EINVAL
 155 The
 156 .Fn sem_open
 157 operation is not supported for the given
 158 .Fa name .
 159 .It Bq Er EINVAL
 160 The
 161 .Fa value
 162 argument is greater than
 163 .Dv SEM_VALUE_MAX .
 164 .\"FreeBSD never returns EMFILE
 165 .\".It Bq Er EMFILE
 166 .\"Too many semaphores are in use by this process.
 167 .It Bq Er ENAMETOOLONG
 168 The
 169 .Fa name
 170 argument is too long.
 171 .It Bq Er ENFILE
 172 The system limit on semaphores has been reached.
 173 .It Bq Er ENOENT
 174 .Dv O_CREAT
 175 is not set but the named semaphore does not exist.
 176 .It Bq Er ENOSPC
 177 There is not enough space to create the semaphore.
 178 .El
 179 .Pp
 180 The
 181 .Fn sem_close
 182 function will fail if:
 183 .Bl -tag -width Er
 184 .It Bq Er EINVAL
 185 The
 186 .Fa sem
 187 argument is not a valid semaphore.
 188 .El
 189 .Pp
 190 The
 191 .Fn sem_unlink
 192 function will fail if:
 193 .Bl -tag -width Er
 194 .It Bq Er EACCES
 195 Permission is denied to unlink the semaphore.
 196 .It Bq Er ENAMETOOLONG
 197 The specified
 198 .Fa name
 199 is too long.
 200 .It Bq Er ENOENT
 201 The named semaphore does not exist.
 202 .El
 203 .Sh SEE ALSO
 204 .Xr close 2 ,
 205 .Xr open 2 ,
 206 .Xr umask 2 ,
 207 .Xr unlink 2 ,
 208 .Xr sem_getvalue 3 ,
 209 .Xr sem_post 3 ,
 210 .Xr sem_trywait 3 ,
 211 .Xr sem_wait 3
 212 .Sh STANDARDS
 213 The
 214 .Fn sem_open ,
 215 .Fn sem_close ,
 216 and
 217 .Fn sem_unlink
 218 functions conform to
 219 .St -p1003.1-96 .
 220 .Sh HISTORY
 221 Support for named semaphores first appeared in
 222 .Fx 5.0 .