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.Dd January 9, 2010 29.Dt SEM_OPEN 3 30.Os 31.Sh NAME 32.Nm sem_open , 33.Nm sem_close , 34.Nm sem_unlink 35.Nd named semaphore operations 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In semaphore.h 40.Ft "sem_t *" 41.Fn sem_open "const char *name" "int oflag" ... 42.Ft int 43.Fn sem_close "sem_t *sem" 44.Ft int 45.Fn sem_unlink "const char *name" 46.Sh DESCRIPTION 47The 48.Fn sem_open 49function creates or opens the named semaphore specified by 50.Fa name . 51The returned semaphore may be used in subsequent calls to 52.Xr sem_getvalue 3 , 53.Xr sem_wait 3 , 54.Xr sem_trywait 3 , 55.Xr sem_post 3 , 56and 57.Fn sem_close . 58.Pp 59This implementation places strict requirements on the value of 60.Fa name : 61it must begin with a slash 62.Pq Ql / 63and contain no other slash characters. 64.Pp 65The following bits may be set in the 66.Fa oflag 67argument: 68.Bl -tag -width ".Dv O_CREAT" 69.It Dv O_CREAT 70Create the semaphore if it does not already exist. 71.Pp 72The third argument to the call to 73.Fn sem_open 74must be of type 75.Vt mode_t 76and specifies the mode for the semaphore. 77Only the 78.Dv S_IWUSR , S_IWGRP , 79and 80.Dv S_IWOTH 81bits are examined; 82it is not possible to grant only 83.Dq read 84permission on a semaphore. 85The mode is modified according to the process's file creation 86mask; see 87.Xr umask 2 . 88.Pp 89The fourth argument must be an 90.Vt "unsigned int" 91and specifies the initial value for the semaphore, 92and must be no greater than 93.Dv SEM_VALUE_MAX . 94.It Dv O_EXCL 95Create the semaphore if it does not exist. 96If the semaphore already exists, 97.Fn sem_open 98will fail. 99This flag is ignored unless 100.Dv O_CREAT 101is also specified. 102.El 103.Pp 104The 105.Fn sem_close 106function closes a named semaphore that was opened by a call to 107.Fn sem_open . 108.Pp 109The 110.Fn sem_unlink 111function removes the semaphore named 112.Fa name . 113Resources allocated to the semaphore are only deallocated when all 114processes that have the semaphore open close it. 115.Sh RETURN VALUES 116If successful, 117the 118.Fn sem_open 119function returns the address of the opened semaphore. 120If the same 121.Fa name 122argument is given to multiple calls to 123.Fn sem_open 124by the same process without an intervening call to 125.Fn sem_close , 126the same address is returned each time. 127If the semaphore cannot be opened, 128.Fn sem_open 129returns 130.Dv SEM_FAILED 131and the global variable 132.Va errno 133is set to indicate the error. 134.Pp 135.Rv -std sem_close sem_unlink 136.Sh ERRORS 137The 138.Fn sem_open 139function will fail if: 140.Bl -tag -width Er 141.It Bq Er EACCES 142The semaphore exists and the permissions specified by 143.Fa oflag 144at the time it was created deny access to this process. 145.It Bq Er EACCES 146The semaphore does not exist, but permission to create it is denied. 147.It Bq Er EEXIST 148.Dv O_CREAT 149and 150.Dv O_EXCL 151are set but the semaphore already exists. 152.It Bq Er EINTR 153The call was interrupted by a signal. 154.It Bq Er EINVAL 155The 156.Fn sem_open 157operation is not supported for the given 158.Fa name . 159.It Bq Er EINVAL 160The 161.Fa value 162argument is greater than 163.Dv SEM_VALUE_MAX . 164.\"FreeBSD never returns EMFILE 165.\".It Bq Er EMFILE 166.\"Too many semaphores are in use by this process. 167.It Bq Er ENAMETOOLONG 168The 169.Fa name 170argument is too long. 171.It Bq Er ENFILE 172The system limit on semaphores has been reached. 173.It Bq Er ENOENT 174.Dv O_CREAT 175is not set but the named semaphore does not exist. 176.It Bq Er ENOSPC 177There is not enough space to create the semaphore. 178.El 179.Pp 180The 181.Fn sem_close 182function will fail if: 183.Bl -tag -width Er 184.It Bq Er EINVAL 185The 186.Fa sem 187argument is not a valid semaphore. 188.El 189.Pp 190The 191.Fn sem_unlink 192function will fail if: 193.Bl -tag -width Er 194.It Bq Er EACCES 195Permission is denied to unlink the semaphore. 196.It Bq Er ENAMETOOLONG 197The specified 198.Fa name 199is too long. 200.It Bq Er ENOENT 201The named semaphore does not exist. 202.El 203.Sh SEE ALSO 204.Xr close 2 , 205.Xr open 2 , 206.Xr umask 2 , 207.Xr unlink 2 , 208.Xr sem_getvalue 3 , 209.Xr sem_post 3 , 210.Xr sem_trywait 3 , 211.Xr sem_wait 3 212.Sh STANDARDS 213The 214.Fn sem_open , 215.Fn sem_close , 216and 217.Fn sem_unlink 218functions conform to 219.St -p1003.1-96 . 220.Sh HISTORY 221Support for named semaphores first appeared in 222.Fx 5.0 . 223