SEM_OPEN(3P)                                        POSIX Programmer's Manual                                       SEM_OPEN(3P)



PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may differ (con-
       sult 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 (REALTIME)

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_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 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 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 exe-
              cuting 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. 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. The interpretation of slash  characters  other  than  the  leading
       slash character in name 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.

       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  corre-
       sponding 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.

       ENAMETOOLONG
              The length of the name argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

       ENFILE Too many semaphores are currently open in the system.

       ENOENT O_CREAT is not set and the named semaphore does not exist.

       ENOSPC There is insufficient space for the creation of the new named semaphore.


       The following sections are informative.

EXAMPLES
       None.

APPLICATION USAGE
       The sem_open() function is part of the Semaphores option and need not be available on all implementations.

RATIONALE
       Early drafts required an error return value of -1 with the type sem_t * for the sem_open() function, which is not guaran-
       teed to be portable across implementations. The revised text provides the symbolic error code SEM_FAILED to eliminate the
       type conflict.

FUTURE DIRECTIONS
       None.

SEE ALSO
       semctl(),  semget(), semop(), sem_close(), sem_post(), sem_timedwait(), sem_trywait(), sem_unlink(), sem_wait(), the Base
       Definitions volume of IEEE Std 1003.1-2001, <semaphore.h>

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, Copy-
       right (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.open-
       group.org/unix/online.html .



IEEE/The Open Group                                           2003                                                  SEM_OPEN(3P)