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