169 lines
4.2 KiB
Groff
169 lines
4.2 KiB
Groff
.\" $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 PSEMNAMLEN
|
|
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).
|