1.\" $NetBSD: sem_open.3,v 1.8 2018/05/05 06:39:10 wiz Exp $ 2.\" 3.\" Copyright (C) 2000 Jason Evans <jasone@FreeBSD.org>. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice(s), this list of conditions and the following disclaimer as 11.\" the first lines of this file unmodified other than the possible 12.\" addition of one or more copyright notices. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice(s), this list of conditions and the following disclaimer in 15.\" the documentation and/or other materials provided with the 16.\" distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 19.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 22.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 25.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 26.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 27.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 28.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.\" From: FreeBSD: src/lib/libc/gen/sem_open.3,v 1.12 2004/07/02 16:45:56 ru 31.\" 32.Dd May 4, 2018 33.Dt SEM_OPEN 3 34.Os 35.Sh NAME 36.Nm sem_open , 37.Nm sem_close , 38.Nm sem_unlink 39.Nd named semaphore operations 40.Sh LIBRARY 41.Lb librt 42.Sh SYNOPSIS 43.In semaphore.h 44.Ft "sem_t *" 45.Fn sem_open "const char *name" "int oflag" ... 46.Ft int 47.Fn sem_close "sem_t *sem" 48.Ft int 49.Fn sem_unlink "const char *name" 50.Sh DESCRIPTION 51The 52.Fn sem_open 53function creates or opens the named semaphore specified by 54.Fa name . 55The returned semaphore may be used in subsequent calls to 56.Xr sem_getvalue 3 , 57.Xr sem_timedwait 3 , 58.Xr sem_trywait 3 , 59.Xr sem_wait 3 , 60.Xr sem_post 3 , 61and 62.Fn sem_close . 63.Pp 64The following bits may be set in the 65.Fa oflag 66argument: 67.Bl -tag -width ".Dv O_CREAT" 68.It Dv O_CREAT 69Create the semaphore if it does not already exist. 70.Pp 71The third argument to the call to 72.Fn sem_open 73must be of type 74.Vt mode_t 75and specifies the mode for the semaphore. 76Only the 77.Dv S_IWUSR , S_IWGRP , 78and 79.Dv S_IWOTH 80bits are examined; 81it is not possible to grant only 82.Dq read 83permission on a semaphore. 84The mode is modified according to the process's file creation 85mask; see 86.Xr umask 2 . 87.Pp 88The fourth argument must be an 89.Vt "unsigned int" 90and specifies the initial value for the semaphore, 91and must be no greater than 92.Dv SEM_VALUE_MAX . 93.It Dv O_EXCL 94Create the semaphore if it does not exist. 95If the semaphore already exists, 96.Fn sem_open 97will fail. 98This flag is ignored unless 99.Dv O_CREAT 100is also specified. 101.El 102.Pp 103The 104.Fn sem_close 105function closes a named semaphore that was opened by a call to 106.Fn sem_open . 107.Pp 108The 109.Fn sem_unlink 110function removes the semaphore named 111.Fa name . 112Resources allocated to the semaphore are only deallocated when all 113processes that have the semaphore open close it. 114.Sh RETURN VALUES 115If successful, 116the 117.Fn sem_open 118function returns the address of the opened semaphore. 119If the same 120.Fa name 121argument is given to multiple calls to 122.Fn sem_open 123by the same process without an intervening call to 124.Fn sem_close , 125the same address is returned each time. 126If the semaphore cannot be opened, 127.Fn sem_open 128returns 129.Dv SEM_FAILED 130and the global variable 131.Va errno 132is set to indicate the error. 133.Pp 134.Rv -std sem_close sem_unlink 135.Sh ERRORS 136The 137.Fn sem_open 138function will fail if: 139.Bl -tag -width Er 140.It Bq Er EACCES 141The semaphore exists and the permissions specified by 142.Fa oflag 143at the time it was created deny access to this process; 144or the 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.Fa name 155argument does not begin with a 156.Sq / 157or contains more slashes. 158This is implementation-specific behavior and allowed by 159.St -p1003.1-96 . 160Or, the 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 specified 169.Fa name 170is longer than 171.Dv NAME_MAX , 172or longer than the implementing file system will allow. 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 and 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 longer than 202.Dv NAME_MAX , 203or longer than the implementing file system will allow. 204.It Bq Er ENOENT 205The named semaphore does not exist. 206.El 207.Sh SEE ALSO 208.Xr close 2 , 209.Xr open 2 , 210.Xr umask 2 , 211.Xr unlink 2 , 212.Xr sem_getvalue 3 , 213.Xr sem_post 3 , 214.Xr sem_trywait 3 , 215.Xr sem_wait 3 , 216.Xr sem 4 217.Sh STANDARDS 218The 219.Fn sem_open , 220.Fn sem_close , 221and 222.Fn sem_unlink 223functions conform to 224.St -p1003.1-96 . 225.Sh HISTORY 226Support for named semaphores first appeared in 227.Nx 2.0 . 228