lib/libpthread/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: head/lib/libc/gen/sem_open.3 202133 2010-01-12 01:30:05Z davidxu $
  29 .\"
  30 .Dd June 4, 2014
  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 libpthread
  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 The mode is modified according to the process's file creation
  79 mask; see
  80 .Xr umask 2 .
  81 .Pp
  82 The fourth argument must be an
  83 .Vt "unsigned int"
  84 and specifies the initial value for the semaphore,
  85 and must be no greater than
  86 .Dv SEM_VALUE_MAX .
  87 .It Dv O_EXCL
  88 Create the semaphore if it does not exist.
  89 If the semaphore already exists,
  90 .Fn sem_open
  91 will fail.
  92 This flag is ignored unless
  93 .Dv O_CREAT
  94 is also specified.
  95 .El
  96 .Pp
  97 The
  98 .Fn sem_close
  99 function closes a named semaphore that was opened by a call to
 100 .Fn sem_open .
 101 .Pp
 102 The
 103 .Fn sem_unlink
 104 function removes the semaphore named
 105 .Fa name .
 106 Resources allocated to the semaphore are only deallocated when all
 107 processes that have the semaphore open close it.
 108 .Sh IMPLEMENTATION NOTES
 109 The current implementation uses shared memory mappings of files.
 110 The semaphore files are created at the path pointed to by
 111 .Fa name .
 112 If
 113 .Fa name
 114 is an absolute path,
 115 .Pa /var/run/sem
 116 is prepended to
 117 .Fa name .
 118 The environnment variable
 119 .Ev LIBTHREAD_SEM_PREFIX
 120 can be set to change this value.
 121 .Pp
 122 It is not possible to grant only
 123 .Dq read
 124 permission on a semaphore.
 125 .Sh RETURN VALUES
 126 If successful,
 127 the
 128 .Fn sem_open
 129 function returns the address of the opened semaphore.
 130 If the same
 131 .Fa name
 132 argument is given to multiple calls to
 133 .Fn sem_open
 134 by the same process without an intervening call to
 135 .Fn sem_close ,
 136 the same address is returned each time.
 137 If the semaphore cannot be opened,
 138 .Fn sem_open
 139 returns
 140 .Dv SEM_FAILED
 141 and the global variable
 142 .Va errno
 143 is set to indicate the error.
 144 .Rv -std sem_close sem_unlink
 145 .Sh ERRORS
 146 The
 147 .Fn sem_open
 148 function will fail if:
 149 .Bl -tag -width Er
 150 .It Bq Er EACCES
 151 The semaphore exists and the permissions specified by
 152 .Fa oflag
 153 at the time it was created deny access to this process.
 154 .It Bq Er EACCES
 155 The semaphore does not exist and permission to create it is denied.
 156 .It Bq Er EEXIST
 157 .Dv O_CREAT
 158 and
 159 .Dv O_EXCL
 160 are set but the semaphore already exists.
 161 .It Bq Er EINTR
 162 The call was interrupted by a signal.
 163 .It Bq Er EINVAL
 164 The
 165 .Fn sem_open
 166 operation is not supported for the given
 167 .Fa name .
 168 .It Bq Er EINVAL
 169 The
 170 .Fa value
 171 argument is greater than
 172 .Dv SEM_VALUE_MAX .
 173 .It Bq Er EMFILE
 174 Too many filedescriptors are in use by this process.
 175 .It Bq Er ENAMETOOLONG
 176 The
 177 .Fa name
 178 argument is too long or a pathname component is too long.
 179 .It Bq Er ENFILE
 180 The system limit on semaphores or open files has been reached.
 181 .It Bq Er ENOENT
 182 .Dv O_CREAT
 183 is not set but the named semaphore does not exist.
 184 .It Bq Er ENOSPC
 185 There is not enough space to create the semaphore.
 186 .It Bq Er ENOMEM
 187 There is insufficient memory for the creation of the new named semaphore.
 188 .El
 189 .Pp
 190 The
 191 .Fn sem_close
 192 function will fail if:
 193 .Bl -tag -width Er
 194 .It Bq Er EINVAL
 195 The
 196 .Fa sem
 197 argument is not a valid semaphore.
 198 .El
 199 .Pp
 200 The
 201 .Fn sem_unlink
 202 function will fail if:
 203 .Bl -tag -width Er
 204 .It Bq Er EACCES
 205 Permission is denied to unlink the semaphore.
 206 .It Bq Er ENAMETOOLONG
 207 The specified
 208 .Fa name
 209 is too long or a pathname component is too long.
 210 .It Bq Er ENOENT
 211 The named semaphore does not exist.
 212 .El
 213 .Sh SEE ALSO
 214 .Xr close 2 ,
 215 .Xr open 2 ,
 216 .Xr umask 2 ,
 217 .Xr unlink 2 ,
 218 .Xr sem_getvalue 3 ,
 219 .Xr sem_post 3 ,
 220 .Xr sem_trywait 3 ,
 221 .Xr sem_wait 3 ,
 222 .Sh STANDARDS
 223 The
 224 .Fn sem_open ,
 225 .Fn sem_close ,
 226 and
 227 .Fn sem_unlink
 228 functions conform to
 229 .St -p1003.1-96 .
 230 .Sh HISTORY
 231 Support for named semaphores first appeared in
 232 .Dx 3.9 .