path: root/man3p/sem_open.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SEM_OPEN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" sem_open 
.SH NAME
sem_open \- initialize and open a named semaphore (\fBREALTIME\fP)
.SH SYNOPSIS
.LP
\fB#include <semaphore.h>
.br
.sp
sem_t *sem_open(const char *\fP\fIname\fP\fB, int\fP \fIoflag\fP\fB,
\&...); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIsem_open\fP() function shall establish a connection between
a named semaphore and a process. Following a call to
\fIsem_open\fP() with semaphore name \fIname\fP, the process may reference
the semaphore associated with \fIname\fP using the
address returned from the call. This semaphore may be used in subsequent
calls to \fIsem_wait\fP(), \fIsem_trywait\fP(), \fIsem_post\fP(),
and \fIsem_close\fP(). The semaphore
remains usable by this process until the semaphore is closed by a
successful call to \fIsem_close\fP(), \fI_exit\fP(), or one of the
\fIexec\fP functions.
.LP
The \fIoflag\fP argument controls whether the semaphore is created
or merely accessed by the call to \fIsem_open\fP(). The
following flag bits may be set in \fIoflag\fP:
.TP 7
O_CREAT
This flag is used to create a semaphore if it does not already exist.
If O_CREAT is set and the semaphore already exists, then
O_CREAT has no effect, except as noted under O_EXCL. Otherwise, \fIsem_open\fP()
creates a named semaphore. The O_CREAT flag
requires a third and a fourth argument: \fImode\fP, which is of type
\fBmode_t\fP, and \fIvalue\fP, which is of type
\fBunsigned\fP. The semaphore is created with an initial value of
\fIvalue\fP. Valid initial values for semaphores are less than
or equal to {SEM_VALUE_MAX}. 
.LP
The user ID of the semaphore is set to the effective user ID of the
process; the group ID of the semaphore is set to a system
default group ID or to the effective group ID of the process. The
permission bits of the semaphore are set to the value of the
\fImode\fP argument except those set in the file mode creation mask
of the process. When bits in \fImode\fP other than the file
permission bits are specified, the effect is unspecified.
.LP
After the semaphore named \fIname\fP has been created by \fIsem_open\fP()
with the O_CREAT flag, other processes can connect
to the semaphore by calling \fIsem_open\fP() with the same value of
\fIname\fP.
.TP 7
O_EXCL
If O_EXCL and O_CREAT are set, \fIsem_open\fP() fails if the semaphore
\fIname\fP exists. The check for the existence of the
semaphore and the creation of the semaphore if it does not exist are
atomic with respect to other processes executing
\fIsem_open\fP() with O_EXCL and O_CREAT set. If O_EXCL is set and
O_CREAT is not set, the effect is undefined. 
.LP
If flags other than O_CREAT and O_EXCL are specified in the \fIoflag\fP
parameter, the effect is unspecified.
.sp
.LP
The \fIname\fP argument points to a string naming a semaphore object.
It is unspecified whether the name appears in the file
system and is visible to functions that take pathnames as arguments.
The \fIname\fP argument conforms to the construction rules
for a pathname. If \fIname\fP begins with the slash character, then
processes calling \fIsem_open\fP() with the same value of
\fIname\fP shall refer to the same semaphore object, as long as that
name has not been removed. If \fIname\fP does not begin with
the slash character, the effect is implementation-defined. The interpretation
of slash characters other than the leading slash
character in \fIname\fP is implementation-defined.
.LP
If a process makes multiple successful calls to \fIsem_open\fP() with
the same value for \fIname\fP, the same semaphore
address shall be returned for each such successful call, provided
that there have been no calls to \fIsem_unlink\fP() for this semaphore.
.LP
References to copies of the semaphore produce undefined results.
.SH RETURN VALUE
.LP
Upon successful completion, the \fIsem_open\fP() function shall return
the address of the semaphore. Otherwise, it shall return
a value of SEM_FAILED and set \fIerrno\fP to indicate the error. The
symbol SEM_FAILED is defined in the \fI<semaphore.h>\fP header. No
successful return from \fIsem_open\fP() shall return the
value SEM_FAILED.
.SH ERRORS
.LP
If any of the following conditions occur, the \fIsem_open\fP() function
shall return SEM_FAILED and set \fIerrno\fP to the
corresponding value:
.TP 7
.B EACCES
The named semaphore exists and the permissions specified by \fIoflag\fP
are denied, or the named semaphore does not exist and
permission to create the named semaphore is denied.
.TP 7
.B EEXIST
O_CREAT and O_EXCL are set and the named semaphore already exists.
.TP 7
.B EINTR
The \fIsem_open\fP() operation was interrupted by a signal.
.TP 7
.B EINVAL
The \fIsem_open\fP() operation is not supported for the given name,
or O_CREAT was specified in \fIoflag\fP and \fIvalue\fP
was greater than {SEM_VALUE_MAX}.
.TP 7
.B EMFILE
Too many semaphore descriptors or file descriptors are currently in
use by this process.
.TP 7
.B ENAMETOOLONG
The length of the \fIname\fP argument exceeds {PATH_MAX} or a pathname
component is longer than {NAME_MAX}.
.TP 7
.B ENFILE
Too many semaphores are currently open in the system.
.TP 7
.B ENOENT
O_CREAT is not set and the named semaphore does not exist.
.TP 7
.B ENOSPC
There is insufficient space for the creation of the new named semaphore.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The \fIsem_open\fP() function is part of the Semaphores option and
need not be available on all implementations.
.SH RATIONALE
.LP
Early drafts required an error return value of -1 with the type \fBsem_t
*\fP for the \fIsem_open\fP() function, which is not
guaranteed to be portable across implementations. The revised text
provides the symbolic error code SEM_FAILED to eliminate the
type conflict.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIsemctl\fP() , \fIsemget\fP() , \fIsemop\fP()
, \fIsem_close\fP() , \fIsem_post\fP() , \fIsem_timedwait\fP() , \fIsem_trywait\fP()
, \fIsem_unlink\fP() , \fIsem_wait\fP() , the Base Definitions volume
of
IEEE\ Std\ 1003.1-2001, \fI<semaphore.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .