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