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.Dd January 15, 2003 30.Dt SEM_OPEN 3 31.Os 32.Sh NAME 33.Nm sem_open , 34.Nm sem_close , 35.Nm sem_unlink 36.Nd named semaphore operations 37.Sh LIBRARY 38.Lb libc_r 39.Sh SYNOPSIS 40.In semaphore.h 41.Ft sem_t * 42.Fn sem_open "const char *name" "int oflag" "..." 43.Ft int 44.Fn sem_close "sem_t *sem" 45.Ft int 46.Fn sem_unlink "const char *name" 47.Sh DESCRIPTION 48The 49.Fn sem_open 50function creates or opens the named semaphore specified by 51.Fa name . 52The returned semaphore may be used in subsequent calls to 53.Fn sem_getvalue , 54.Fn sem_wait , 55.Fn sem_trywait , 56.Fn sem_post 57and 58.Fn sem_close . 59.Pp 60The following bits may be set in the 61.Fa oflag 62argument: 63.Bl -tag -width ".Dv O_CREAT" 64.It Dv O_CREAT 65Create the semaphore if it does not already exist. 66.Pp 67The third argument to the call to 68.Fn sem_open 69must be of type 70.Vt mode_t 71and specifies the mode for the semaphore. 72Only the 73.Dv S_IWUSR , 74.Dv S_IWGRP , 75and 76.Dv S_IWOTH 77bits are examined; 78it is not possible to grant only 79.Dq read 80permission on a semaphore. 81The mode is modified according to the process's file creation 82mask; see 83.Xr umask 2 . 84.Pp 85The fourth argument must be an 86.Vt "unsigned int" 87and specifies the initial value for the semaphore, 88and must be no greater than 89.Dv SEM_VALUE_MAX . 90.It Dv O_EXCL 91Create the semaphore if it does not exist. 92If the semaphore already exists, 93.Fn sem_open 94will fail. 95This flag is ignored unless 96.Dv O_CREAT 97is also specified. 98.El 99.Pp 100The 101.Fn sem_close 102function closes a named semaphore that was opened by a call to 103.Fn sem_open . 104.Pp 105The 106.Fn sem_unlink 107function removes the semaphore named 108.Fa name . 109Resources allocated to the semaphore are only deallocated when all 110processes that have the semaphore open close it. 111.Sh RETURN VALUES 112If successful, 113the 114.Fn sem_open 115function returns the address of the opened semaphore. 116If the same 117.Fa name 118argument is given to multiple calls to 119.Fn sem_open 120by the same process without an intervening call to 121.Fn sem_close , 122the same address is returned each time. 123If the semaphore cannot be opened, 124.Fn sem_open 125returns 126.Dv SEM_FAILED 127and the global variable 128.Va errno 129is set to indicate the error. 130.Pp 131.Rv -std sem_close 132.Pp 133.Rv -std 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 the 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 set but 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_wait 3 , 208.Xr sem_trywait 3 , 209.Xr sem_post 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.Fx 5.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 not including the terminating null. 229