lib/librt/sem_open.3

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