--- /dev/null
+.\" $Darwin$
+.\"
+.\" Copyright (c) 2000-2002 Apple Computer, Inc. All rights reserved.
+.\"
+.\" @APPLE_LICENSE_HEADER_START@
+.\"
+.\" The contents of this file constitute Original Code as defined in and
+.\" are subject to the Apple Public Source License Version 1.1 (the
+.\" "License"). You may not use this file except in compliance with the
+.\" License. Please obtain a copy of the License at
+.\" http://www.apple.com/publicsource and read it before using this file.
+.\"
+.\" This Original Code and all software distributed under the License are
+.\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT. Please see the
+.\" License for the specific language governing rights and limitations
+.\" under the License.
+.\"
+.\" @APPLE_LICENSE_HEADER_END@
+.\"
+.Dd June 8, 2000
+.Dt SEM_OPEN 2
+.Os Darwin
+.Sh NAME
+.Nm sem_open
+.Nd initialize and open a named semaphore
+.Sh SYNOPSIS
+.Fd #include <semaphore.h>
+.Ft sem_t *
+.Fo sem_open
+.Fa "const char *name"
+.Fa "int oflag"
+.Fa "..."
+.Fc
+.Pp
+The parameters "mode_t mode" and "unsigned int value"
+are optional.
+.Sh DESCRIPTION
+The named semaphore named
+.Fa name
+is initialized and opened as specified by the argument
+.Fa oflag
+and a semaphore descriptor is returned to the calling process.
+.Pp
+The value of
+.Fa oflag
+is formed by
+.Em or Ns 'ing
+the following values:
+.Pp
+.Bd -literal -offset indent -compact
+O_CREAT create the semaphore if it does not exist
+O_EXCL error if create and semaphore exists
+.Ed
+.Pp
+If
+.Dv O_CREAT
+is specified,
+.Fn sem_open
+requires an additional two arguments.
+.Fa mode
+specifies the permissions for the semaphore as described in
+.Xr chmod 2
+and modified by the process' umask value (see
+.Xr umask 2 ) .
+The semaphore is created with an initial
+.Fa value ,
+which must be less than or equal to
+.Dv SEM_VALUE_MAX .
+.Pp
+If
+.Dv O_EXCL
+is specified and the semaphore exists,
+.Fn sem_open
+fails. The check for the existence of the semaphore and the creation
+of the semaphore are atomic with respect to all processes calling
+.Fn sem_open
+with
+.Dv O_CREAT
+and
+.Dv O_EXCL
+set.
+.Pp
+When a new semaphore is created, it is given the user ID and group ID
+which correspond to the effective user and group IDs of the calling
+process. There is no visible entry in the file system for the created
+object in this implementation.
+.Pp
+The returned semaphore descriptor is available to the calling process
+until it is closed with
+.Fn sem_close ,
+or until the caller exits or execs.
+.Pp
+If a process makes repeated calls to
+.Fn sem_open ,
+with the same
+.Fa name
+argument, the same descriptor is returned for each successful call,
+unless
+.Fn sem_unlink
+has been called on the semaphore in the interim.
+.Pp
+If
+.Fn sem_open
+fails for any reason, it will return a value of
+.Dv SEM_FAILED
+and sets
+.Va errno .
+On success, it returns a semaphore descriptor.
+.Sh ERRORS
+The named semaphore is opened unless:
+.Bl -tag -width Er
+.It Bq Er EACCES
+The required permissions (for reading and/or writing)
+are denied for the given flags; or
+.Dv O_CREAT
+is specified, the object does not exist, and permission to
+create the semaphore is denied.
+.It Bq Er EEXIST
+.Dv O_CREAT
+and
+.Dv O_EXCL
+were specified and the semaphore exists.
+.It Bq Er EINTR
+The
+.Fn sem_open
+operation was interrupted by a signal.
+.It Bq Er EINVAL
+The
+.Fn shm_open
+operation is not supported; or
+.Dv O_CREAT
+is specified and
+.Fa value
+exceeds
+.Dv SEM_VALUE_MAX .
+.It Bq Er EMFILE
+The process has already reached its limit for semaphores or file
+descriptors in use.
+.It Bq Er ENAMETOOLONG
+.Fa name
+exceeded
+.Dv SEM_NAME_LEN
+characters.
+.It Bq Er ENFILE
+Too many semaphores or file descriptors are open on the system.
+.It Bq Er ENOENT
+.Dv O_CREAT
+is not set and the named semaphore does not exist.
+.It Bq Er ENOSPC
+.Dv O_CREAT
+is specified, the file does not exist, and there is insufficient
+space available to create the semaphore.
+.El
+.Sh SEE ALSO
+.Xr sem_close 2 ,
+.Xr sem_post 2 ,
+.Xr sem_trywait 2 ,
+.Xr sem_unlink 2 ,
+.Xr sem_wait 2 ,
+.Xr semctl 2 ,
+.Xr semget 2 ,
+.Xr semop 2 ,
+.Xr umask 2
+.Sh HISTORY
+.Fn sem_open
+is specified in the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995).
projects / apple / xnu.git / blobdiff