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