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: head/lib/libc/gen/sem_open.3 202133 2010-01-12 01:30:05Z davidxu $ 29.\" 30.Dd June 4, 2014 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 libpthread 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. 78The mode is modified according to the process's file creation 79mask; see 80.Xr umask 2 . 81.Pp 82The fourth argument must be an 83.Vt "unsigned int" 84and specifies the initial value for the semaphore, 85and must be no greater than 86.Dv SEM_VALUE_MAX . 87.It Dv O_EXCL 88Create the semaphore if it does not exist. 89If the semaphore already exists, 90.Fn sem_open 91will fail. 92This flag is ignored unless 93.Dv O_CREAT 94is also specified. 95.El 96.Pp 97The 98.Fn sem_close 99function closes a named semaphore that was opened by a call to 100.Fn sem_open . 101.Pp 102The 103.Fn sem_unlink 104function removes the semaphore named 105.Fa name . 106Resources allocated to the semaphore are only deallocated when all 107processes that have the semaphore open close it. 108.Sh IMPLEMENTATION NOTES 109The current implementation uses shared memory mappings of files. 110The semaphore files are created at the path pointed to by 111.Fa name . 112If 113.Fa name 114is an absolute path, 115.Pa /var/run/sem 116is prepended to 117.Fa name . 118The environnment variable 119.Ev LIBTHREAD_SEM_PREFIX 120can be set to change this value. 121.Pp 122It is not possible to grant only 123.Dq read 124permission on a semaphore. 125.Sh RETURN VALUES 126If successful, 127the 128.Fn sem_open 129function returns the address of the opened semaphore. 130If the same 131.Fa name 132argument is given to multiple calls to 133.Fn sem_open 134by the same process without an intervening call to 135.Fn sem_close , 136the same address is returned each time. 137If the semaphore cannot be opened, 138.Fn sem_open 139returns 140.Dv SEM_FAILED 141and the global variable 142.Va errno 143is set to indicate the error. 144.Rv -std sem_close sem_unlink 145.Sh ERRORS 146The 147.Fn sem_open 148function will fail if: 149.Bl -tag -width Er 150.It Bq Er EACCES 151The semaphore exists and the permissions specified by 152.Fa oflag 153at the time it was created deny access to this process. 154.It Bq Er EACCES 155The semaphore does not exist and permission to create it is denied. 156.It Bq Er EEXIST 157.Dv O_CREAT 158and 159.Dv O_EXCL 160are set but the semaphore already exists. 161.It Bq Er EINTR 162The call was interrupted by a signal. 163.It Bq Er EINVAL 164The 165.Fn sem_open 166operation is not supported for the given 167.Fa name . 168.It Bq Er EINVAL 169The 170.Fa value 171argument is greater than 172.Dv SEM_VALUE_MAX . 173.It Bq Er EMFILE 174Too many filedescriptors are in use by this process. 175.It Bq Er ENAMETOOLONG 176The 177.Fa name 178argument is too long or a pathname component is too long. 179.It Bq Er ENFILE 180The system limit on semaphores or open files has been reached. 181.It Bq Er ENOENT 182.Dv O_CREAT 183is not set but the named semaphore does not exist. 184.It Bq Er ENOSPC 185There is not enough space to create the semaphore. 186.It Bq Er ENOMEM 187There is insufficient memory for the creation of the new named semaphore. 188.El 189.Pp 190The 191.Fn sem_close 192function will fail if: 193.Bl -tag -width Er 194.It Bq Er EINVAL 195The 196.Fa sem 197argument is not a valid semaphore. 198.El 199.Pp 200The 201.Fn sem_unlink 202function will fail if: 203.Bl -tag -width Er 204.It Bq Er EACCES 205Permission is denied to unlink the semaphore. 206.It Bq Er ENAMETOOLONG 207The specified 208.Fa name 209is too long or a pathname component is too long. 210.It Bq Er ENOENT 211The named semaphore does not exist. 212.El 213.Sh SEE ALSO 214.Xr close 2 , 215.Xr open 2 , 216.Xr umask 2 , 217.Xr unlink 2 , 218.Xr sem_getvalue 3 , 219.Xr sem_post 3 , 220.Xr sem_trywait 3 , 221.Xr sem_wait 3 222.Sh STANDARDS 223The 224.Fn sem_open , 225.Fn sem_close , 226and 227.Fn sem_unlink 228functions conform to 229.St -p1003.1-96 . 230.Sh HISTORY 231Support for named semaphores first appeared in 232.Dx 3.9 . 233