# sem_open

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           sem_open — initialize and open a named semaphore
    


## SYNOPSIS



           #include <semaphore.h>
    
           sem_t *sem_open(const char *_name_ , int _oflag_ , ...);
    


## DESCRIPTION



           The _sem_open_() function shall establish a connection between a
           named semaphore and a process. Following a call to _sem_open_() with
           semaphore name _name_ , the process may reference the semaphore
           associated with _name_ using the address returned from the call.
           This semaphore may be used in subsequent calls to _sem_wait_(),
           _sem_timedwait_(), _sem_trywait_(), _sem_post_(), and _sem_close_().  The
           semaphore remains usable by this process until the semaphore is
           closed by a successful call to _sem_close_(), __exit_(), or one of the
           _exec_ functions.
    
           The _oflag_ argument controls whether the semaphore is created or
           merely accessed by the call to _sem_open_().  The following flag
           bits may be set in _oflag_ :
    
           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, _sem_open_() creates a
                     named semaphore. The O_CREAT flag requires a third and a
                     fourth argument: _mode_ , which is of type **mode_t** , and
                     _value_ , which is of type **unsigned**.  The semaphore is
                     created with an initial value of _value_.  Valid initial
                     values for semaphores are less than or equal to
                     {SEM_VALUE_MAX}.
    
                     The user ID of the semaphore shall be set to the
                     effective user ID of the process. The group ID of the
                     semaphore shall be set to the effective group ID of the
                     process; however, if the _name_ argument is visible in the
                     file system, the group ID may be set to the group ID of
                     the containing directory. The permission bits of the
                     semaphore are set to the value of the _mode_ argument
                     except those set in the file mode creation mask of the
                     process. When bits in _mode_ other than the file
                     permission bits are specified, the effect is
                     unspecified.
    
                     After the semaphore named _name_ has been created by
                     _sem_open_() with the O_CREAT flag, other processes can
                     connect to the semaphore by calling _sem_open_() with the
                     same value of _name_.
    
           O_EXCL    If O_EXCL and O_CREAT are set, _sem_open_() fails if the
                     semaphore _name_ 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 _sem_open_() with O_EXCL and O_CREAT
                     set. If O_EXCL is set and O_CREAT is not set, the effect
                     is undefined.
    
                     If flags other than O_CREAT and O_EXCL are specified in
                     the _oflag_ parameter, the effect is unspecified.
    
           The _name_ 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 _name_
           argument conforms to the construction rules for a pathname, except
           that the interpretation of <slash> characters other than the
           leading <slash> character in _name_ is implementation-defined, and
           that the length limits for the _name_ argument are implementation-
           defined and need not be the same as the pathname limits {PATH_MAX}
           and {NAME_MAX}.  If _name_ begins with the <slash> character, then
           processes calling _sem_open_() with the same value of _name_ shall
           refer to the same semaphore object, as long as that name has not
           been removed. If _name_ does not begin with the <slash> character,
           the effect is implementation-defined.
    
           If a process makes multiple successful calls to _sem_open_() with
           the same value for _name_ , the same semaphore address shall be
           returned for each such successful call, provided that there have
           been no calls to _sem_unlink_() for this semaphore, and at least one
           previous successful _sem_open_() call for this semaphore has not
           been matched with a _sem_close_() call.
    
           References to copies of the semaphore produce undefined results.
    


## RETURN VALUE



           Upon successful completion, the _sem_open_() function shall return
           the address of the semaphore. Otherwise, it shall return a value
           of SEM_FAILED and set _errno_ to indicate the error. The symbol
           SEM_FAILED is defined in the _< semaphore.h>_ header. No successful
           return from _sem_open_() shall return the value SEM_FAILED.
    


## ERRORS



           If any of the following conditions occur, the _sem_open_() function
           shall return SEM_FAILED and set _errno_ to the corresponding value:
    
           **EACCES** The named semaphore exists and the permissions specified by
                  _oflag_ are denied, or the named semaphore does not exist and
                  permission to create the named semaphore is denied.
    
           **EEXIST** O_CREAT and O_EXCL are set and the named semaphore already
                  exists.
    
           **EINTR** The _sem_open_() operation was interrupted by a signal.
    
           **EINVAL** The _sem_open_() operation is not supported for the given
                  name, or O_CREAT was specified in _oflag_ and _value_ was
                  greater than {SEM_VALUE_MAX}.
    
           **EMFILE** Too many semaphore descriptors or file descriptors are
                  currently in use by this process.
    
           **ENFILE** Too many semaphores are currently open in the system.
    
           **ENOENT** O_CREAT is not set and the named semaphore does not exist.
    
           **ENOMEM** There is insufficient memory for the creation of the new
                  named semaphore.
    
           **ENOSPC** There is insufficient space on a storage device for the
                  creation of the new named semaphore.
    
           If any of the following conditions occur, the _sem_open_() function
           may return SEM_FAILED and set _errno_ to the corresponding value:
    
           **ENAMETOOLONG**
                  The length of the _name_ argument exceeds {_POSIX_PATH_MAX}
                  on systems that do not support the XSI option or exceeds
                  {_XOPEN_PATH_MAX} on XSI systems, or has a pathname
                  component that is longer than {_POSIX_NAME_MAX} on systems
                  that do not support the XSI option or longer than
                  {_XOPEN_NAME_MAX} on XSI systems.
    
           _The following sections are informative._
    


## EXAMPLES



           None.
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           Early drafts required an error return value of -1 with the type
           **sem_t *** for the _sem_open_() 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.
    


## FUTURE DIRECTIONS



           A future version might require the _sem_open_() and _sem_unlink_()
           functions to have semantics similar to normal file system
           operations.
    


* * *