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 49The 50.Fn sem_open 51function creates or opens the named semaphore specified by 52.Fa name . 53The 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 , 58and 59.Fn sem_close . 60.Pp 61The following bits may be set in the 62.Fa oflag 63argument: 64.Bl -tag -width ".Dv O_CREAT" 65.It Dv O_CREAT 66Create the semaphore if it does not already exist. 67.Pp 68The third argument to the call to 69.Fn sem_open 70must be of type 71.Vt mode_t 72and specifies the mode for the semaphore. 73Only the 74.Dv S_IWUSR , 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 sem_unlink 132.Sh ERRORS 133The 134.Fn sem_open 135function will fail if: 136.Bl -tag -width Er 137.It Bq Er EACCES 138The semaphore exists and the permissions specified by 139.Fa oflag 140at the time it was created deny access to this process. 141.It Bq Er EACCES 142The semaphore does not exist, but permission to create it is denied. 143.It Bq Er EEXIST 144.Dv O_CREAT 145and 146.Dv O_EXCL 147are set but the semaphore already exists. 148.It Bq Er EINTR 149The call was interrupted by a signal. 150.It Bq Er EINVAL 151The 152.Fn sem_open 153operation is not supported for the given 154.Fa name . 155.It Bq Er EINVAL 156The 157.Fa value 158argument 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 164The 165.Fa name 166argument is too long. 167.It Bq Er ENFILE 168The system limit on semaphores has been reached. 169.It Bq Er ENOENT 170.Dv O_CREAT 171is not set but the named semaphore does not exist. 172.It Bq Er ENOSPC 173There is not enough space to create the semaphore. 174.El 175.Pp 176The 177.Fn sem_close 178function will fail if: 179.Bl -tag -width Er 180.It Bq Er EINVAL 181The 182.Fa sem 183argument is not a valid semaphore. 184.El 185.Pp 186The 187.Fn sem_unlink 188function will fail if: 189.Bl -tag -width Er 190.It Bq Er EACCES 191Permission is denied to unlink the semaphore. 192.It Bq Er ENAMETOOLONG 193The specified 194.Fa name 195is too long. 196.It Bq Er ENOENT 197The 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 210The 211.Fn sem_open , 212.Fn sem_close , 213and 214.Fn sem_unlink 215functions conform to 216.St -p1003.1-96 . 217.Sh HISTORY 218Support for named semaphores first appeared in 219.Fx 5.0 . 220.Sh BUGS 221This implementation places strict requirements on the value of 222.Fa name : 223it must begin with a slash 224.Pq Ql / , 225contain no other slash characters, 226and be less than 14 characters in length 227not including the terminating null character. 228