1.\" $Darwin$ 2.\" 3.\" Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved. 4.\" 5.\" @APPLE_LICENSE_HEADER_START@ 6.\" 7.\" The contents of this file constitute Original Code as defined in and 8.\" are subject to the Apple Public Source License Version 1.1 (the 9.\" "License"). You may not use this file except in compliance with the 10.\" License. Please obtain a copy of the License at 11.\" http://www.apple.com/publicsource and read it before using this file. 12.\" 13.\" This Original Code and all software distributed under the License are 14.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER 15.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 16.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 17.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the 18.\" License for the specific language governing rights and limitations 19.\" under the License. 20.\" 21.\" @APPLE_LICENSE_HEADER_END@ 22.\" 23.Dd June 8, 2000 24.Dt SEM_OPEN 2 25.Os Darwin 26.Sh NAME 27.Nm sem_open 28.Nd initialize and open a named semaphore 29.Sh SYNOPSIS 30.Fd #include <semaphore.h> 31.Ft sem_t * 32.Fo sem_open 33.Fa "const char *name" 34.Fa "int oflag" 35.Fa "..." 36.Fc 37.Pp 38The parameters "mode_t mode" and "unsigned int value" 39are optional. 40.Sh DESCRIPTION 41The named semaphore named 42.Fa name 43is initialized and opened as specified by the argument 44.Fa oflag 45and a semaphore descriptor is returned to the calling process. 46.Pp 47The value of 48.Fa oflag 49is formed by 50.Em or Ns 'ing 51the following values: 52.Pp 53.Bd -literal -offset indent -compact 54O_CREAT create the semaphore if it does not exist 55O_EXCL error if create and semaphore exists 56.Ed 57.Pp 58If 59.Dv O_CREAT 60is specified, 61.Fn sem_open 62requires an additional two arguments. 63.Fa mode 64specifies the permissions for the semaphore as described in 65.Xr chmod 2 66and modified by the process' umask value (see 67.Xr umask 2 ) . 68The semaphore is created with an initial 69.Fa value , 70which must be less than or equal to 71.Dv SEM_VALUE_MAX . 72.Pp 73If 74.Dv O_EXCL 75is specified and the semaphore exists, 76.Fn sem_open 77fails. The check for the existence of the semaphore and the creation 78of the semaphore are atomic with respect to all processes calling 79.Fn sem_open 80with 81.Dv O_CREAT 82and 83.Dv O_EXCL 84set. 85.Pp 86When a new semaphore is created, it is given the user ID and group ID 87which correspond to the effective user and group IDs of the calling 88process. There is no visible entry in the file system for the created 89object in this implementation. 90.Pp 91The returned semaphore descriptor is available to the calling process 92until it is closed with 93.Fn sem_close , 94or until the caller exits or execs. 95.Pp 96If a process makes repeated calls to 97.Fn sem_open , 98with the same 99.Fa name 100argument, the same descriptor is returned for each successful call, 101unless 102.Fn sem_unlink 103has been called on the semaphore in the interim. 104.Pp 105If 106.Fn sem_open 107fails for any reason, it will return a value of 108.Dv SEM_FAILED 109and sets 110.Va errno . 111On success, it returns a semaphore descriptor. 112.Sh ERRORS 113The named semaphore is opened unless: 114.Bl -tag -width Er 115.It Bq Er EACCES 116The required permissions (for reading and/or writing) 117are denied for the given flags; or 118.Dv O_CREAT 119is specified, the object does not exist, and permission to 120create the semaphore is denied. 121.It Bq Er EEXIST 122.Dv O_CREAT 123and 124.Dv O_EXCL 125were specified and the semaphore exists. 126.It Bq Er EINTR 127The 128.Fn sem_open 129operation was interrupted by a signal. 130.It Bq Er EINVAL 131The 132.Fn shm_open 133operation is not supported; or 134.Dv O_CREAT 135is specified and 136.Fa value 137exceeds 138.Dv SEM_VALUE_MAX . 139.It Bq Er EMFILE 140The process has already reached its limit for semaphores or file 141descriptors in use. 142.It Bq Er ENAMETOOLONG 143.Fa name 144exceeded 145.Dv PSEMNAMLEN 146characters. 147.It Bq Er ENFILE 148Too many semaphores or file descriptors are open on the system. 149.It Bq Er ENOENT 150.Dv O_CREAT 151is not set and the named semaphore does not exist. 152.It Bq Er ENOSPC 153.Dv O_CREAT 154is specified, the file does not exist, and there is insufficient 155space available to create the semaphore. 156.El 157.Sh SEE ALSO 158.Xr sem_close 2 , 159.Xr sem_post 2 , 160.Xr sem_trywait 2 , 161.Xr sem_unlink 2 , 162.Xr sem_wait 2 , 163.Xr semctl 2 , 164.Xr semget 2 , 165.Xr semop 2 , 166.Xr umask 2 167.Sh HISTORY 168.Fn sem_open 169is specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995). 170