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 .\" $FreeBSD$
  29 .\"
  30 .Dd January 9, 2010
  31 .Dt SEM_OPEN 3
  32 .Os
  33 .Sh NAME
  34 .Nm sem_open ,
  35 .Nm sem_close ,
  36 .Nm sem_unlink
  37 .Nd named semaphore operations
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In semaphore.h
  42 .Ft "sem_t *"
  43 .Fn sem_open "const char *name" "int oflag" ...
  44 .Ft int
  45 .Fn sem_close "sem_t *sem"
  46 .Ft int
  47 .Fn sem_unlink "const char *name"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn sem_open
  51 function creates or opens the named semaphore specified by
  52 .Fa name .
  53 The returned semaphore may be used in subsequent calls to
  54 .Xr sem_getvalue 3 ,
  55 .Xr sem_wait 3 ,
  56 .Xr sem_trywait 3 ,
  57 .Xr sem_post 3 ,
  58 and
  59 .Fn sem_close .
  60 .Pp
  61 This implementation places strict requirements on the value of
  62 .Fa name :
  63 it must begin with a slash
  64 .Pq Ql /
  65 and contain no other slash characters.
  66 .Pp
  67 The following bits may be set in the
  68 .Fa oflag
  69 argument:
  70 .Bl -tag -width ".Dv O_CREAT"
  71 .It Dv O_CREAT
  72 Create the semaphore if it does not already exist.
  73 .Pp
  74 The third argument to the call to
  75 .Fn sem_open
  76 must be of type
  77 .Vt mode_t
  78 and specifies the mode for the semaphore.
  79 Only the
  80 .Dv S_IWUSR , S_IWGRP ,
  81 and
  82 .Dv S_IWOTH
  83 bits are examined;
  84 it is not possible to grant only
  85 .Dq read
  86 permission on a semaphore.
  87 The mode is modified according to the process's file creation
  88 mask; see
  89 .Xr umask 2 .
  90 .Pp
  91 The fourth argument must be an
  92 .Vt "unsigned int"
  93 and specifies the initial value for the semaphore,
  94 and must be no greater than
  95 .Dv SEM_VALUE_MAX .
  96 .It Dv O_EXCL
  97 Create the semaphore if it does not exist.
  98 If the semaphore already exists,
  99 .Fn sem_open
 100 will fail.
 101 This flag is ignored unless
 102 .Dv O_CREAT
 103 is also specified.
 104 .El
 105 .Pp
 106 The
 107 .Fn sem_close
 108 function closes a named semaphore that was opened by a call to
 109 .Fn sem_open .
 110 .Pp
 111 The
 112 .Fn sem_unlink
 113 function removes the semaphore named
 114 .Fa name .
 115 Resources allocated to the semaphore are only deallocated when all
 116 processes that have the semaphore open close it.
 117 .Sh RETURN VALUES
 118 If successful,
 119 the
 120 .Fn sem_open
 121 function returns the address of the opened semaphore.
 122 If the same
 123 .Fa name
 124 argument is given to multiple calls to
 125 .Fn sem_open
 126 by the same process without an intervening call to
 127 .Fn sem_close ,
 128 the same address is returned each time.
 129 If the semaphore cannot be opened,
 130 .Fn sem_open
 131 returns
 132 .Dv SEM_FAILED
 133 and the global variable
 134 .Va errno
 135 is set to indicate the error.
 136 .Pp
 137 .Rv -std sem_close sem_unlink
 138 .Sh ERRORS
 139 The
 140 .Fn sem_open
 141 function will fail if:
 142 .Bl -tag -width Er
 143 .It Bq Er EACCES
 144 The semaphore exists and the permissions specified by
 145 .Fa oflag
 146 at the time it was created deny access to this process.
 147 .It Bq Er EACCES
 148 The semaphore does not exist, but permission to create it is denied.
 149 .It Bq Er EEXIST
 150 .Dv O_CREAT
 151 and
 152 .Dv O_EXCL
 153 are set but the semaphore already exists.
 154 .It Bq Er EINTR
 155 The call was interrupted by a signal.
 156 .It Bq Er EINVAL
 157 The
 158 .Fn sem_open
 159 operation is not supported for the given
 160 .Fa name .
 161 .It Bq Er EINVAL
 162 The
 163 .Fa value
 164 argument is greater than
 165 .Dv SEM_VALUE_MAX .
 166 .\"FreeBSD never returns EMFILE
 167 .\".It Bq Er EMFILE
 168 .\"Too many semaphores are in use by this process.
 169 .It Bq Er ENAMETOOLONG
 170 The
 171 .Fa name
 172 argument is too long.
 173 .It Bq Er ENFILE
 174 The system limit on semaphores has been reached.
 175 .It Bq Er ENOENT
 176 .Dv O_CREAT
 177 is not set but the named semaphore does not exist.
 178 .It Bq Er ENOSPC
 179 There is not enough space to create the semaphore.
 180 .El
 181 .Pp
 182 The
 183 .Fn sem_close
 184 function will fail if:
 185 .Bl -tag -width Er
 186 .It Bq Er EINVAL
 187 The
 188 .Fa sem
 189 argument is not a valid semaphore.
 190 .El
 191 .Pp
 192 The
 193 .Fn sem_unlink
 194 function will fail if:
 195 .Bl -tag -width Er
 196 .It Bq Er EACCES
 197 Permission is denied to unlink the semaphore.
 198 .It Bq Er ENAMETOOLONG
 199 The specified
 200 .Fa name
 201 is too long.
 202 .It Bq Er ENOENT
 203 The named semaphore does not exist.
 204 .El
 205 .Sh SEE ALSO
 206 .Xr close 2 ,
 207 .Xr open 2 ,
 208 .Xr umask 2 ,
 209 .Xr unlink 2 ,
 210 .Xr sem_getvalue 3 ,
 211 .Xr sem_post 3 ,
 212 .Xr sem_trywait 3 ,
 213 .Xr sem_wait 3 ,
 214 .Xr sem 4
 215 .Sh STANDARDS
 216 The
 217 .Fn sem_open ,
 218 .Fn sem_close ,
 219 and
 220 .Fn sem_unlink
 221 functions conform to
 222 .St -p1003.1-96 .
 223 .Sh HISTORY
 224 Support for named semaphores first appeared in
 225 .Fx 5.0 .