sem_open(3C)sem_open(3C)NAMEsem_open - open a posix named semaphore
C SYNOPSIS
#include <semaphore.h>
sem_t *sem_open (const char *name, int oflag, ... /* mode_t mode, int
value */);
DESCRIPTIONsem_open opens a semaphore named by the character string at address name.
The oflag parameter is used when creating a semaphore, supporting the
following bit flags:
O_CREAT
If the semaphore already exists, this flag has no effect, except as
noted under O_EXCL below. Otherwise, the semaphore is created. The
initial value of the semaphore may be specified by value, where
value is any non-negative number less than {SEM_VALUE_MAX} [see
sysconf(3C)].
Named semaphores are represented by files in the file namespace
(commands like ls will display named semaphores as regular files).
Because of this relationship, named semaphores inherit their access
semantics from files. The owner ID of the semaphore is set to the
effective user IDs of the process, the group ID of the semaphore is
set to the effective group IDs of the process or to the group ID of
the directory in which the semaphore is being created. This is
determined as follows:
If the underlying filesystem was mounted with the BSD file
creation semantics flag [see fstab(4)] or the S_ISGID bit is
set [see chmod(2)] on the parent directory, then the group ID
of the new file is set to the group ID of the parent directory,
otherwise it is set to the effective group ID of the calling
process.
If the group ID of the semaphore does not match the effective
group ID, or one of the supplementary groups IDs, the S_ISGID
bit is cleared. The access permission bits of the file mode
are set to the value of mode, modified as follows:
All bits set in the file mode creation mask of the process
are cleared [see umask(2)].
The ``save text image after execution bit'' of the mode is
cleared [see chmod(2)].
O_EXCL If O_EXCL and O_CREAT are set, sem_open will fail if the named
semaphore exists. The check for the existence of the semaphore
and the creation of the name in the file namespace is atomic with
respect to other processes executing sem_open naming the same
Page 1
sem_open(3C)sem_open(3C)
semaphore in the same directory with O_EXCL and O_CREAT set.
If a named semaphore is opened multiple times by the same process (or
threads within the process) before sem_unlink is called, the same
semaphore descriptor is returned from each call to sem_open.
Named semaphores persist until the semaphore is unlinked and all other
references are dropped [see sem_unlink(2) and sem_close(2)].
If name is a symbolic link and O_CREAT and O_EXCL are set, the link is
not followed.
There is a system enforced limit on the number of open named semaphores
per process {_POSIX_SEM_NSEMS_MAX}.
If the character string pointed to by name is prefixed with /dev, then
unpredictable results may occur. Devices are opened using the open(2)
function.
POSIX semaphores are compatible across all MIPS ABIs: o32, n32 and 64.
Once a named semaphore is opened, the process may execute the following
semaphore operations: sem_post, sem_wait, sem_trywait, sem_getvalue,
sem_unlink, sem_close.
sem_open will fail if one or more of the following are true:
[EACCES] The semaphore, named by name, does not exist and write
permission is denied by the parent directory of the
semaphore to be created.
[EACCES] O_CREAT is specified and write permission is denied.
[EACCES] A component of the name prefix denies search permission.
[EACCES] oflag permission is denied for an existing semaphore.
[EAGAIN] The semaphore exists, O_CREAT is specified, mandatory
file/record locking is set, and there are outstanding
record locks on the file naming the semaphore [see
chmod(2)].
[EDQUOT] O_CREAT is specified, the semaphore does not exist, and
the directory in which the entry for the new semaphore is
being placed cannot be extended either because the user's
quota of disk blocks on the file system containing the
directory has been exhausted or the user's quota of inodes
on the file system on which the file is being created has
been exhausted.
Page 2
sem_open(3C)sem_open(3C)
[EEXIST] O_CREAT and O_EXCL are set, and the semaphore already
exists.
[EFAULT] name points outside the allocated address space of the
process.
[EINTR] A signal was caught during the sem_open system call.
[EINVAL] oflags specified O_CREAT and value was greater than
{SEM_VALUE_MAX}.
[EISDIR] The semaphore name points to a directory.
[ELOOP] Too many symbolic links were encountered in translating
name.
[EMFILE] The process has too many open semaphore or file
descriptors [see getrlimit(2)].
[ENAMETOOLONG] The length of the name argument exceeds {PATH_MAX}, or the
length of a name component exceeds {NAME_MAX} while
{_POSIX_NO_TRUNC} is in effect.
[ENFILE] The system file table is full.
[ENOENT] O_CREAT is not set and the semaphore does not exist.
[ENOENT] O_CREAT is set and a component of the name prefix does not
exist or is the null pathname.
[ENOSPC] The system resources for semaphore allocation have been
depleted.
[ENOTDIR] A component of the name prefix is not a directory.
[ETIMEDOUT] The semaphore is located on a remote system which is not
available [see intro(2)].
[EROFS] The named semaphore resides on a read-only file system,
O_CREAT is set in oflag, and the semaphore does not exist.
SEE ALSOsem_getvalue(3C), sem_post(3C), sem_wait(3C), sem_trywait(3C),
sem_open(3C), sem_close(3C), sem_unlink(3C), sysconf(3C)DIAGNOSTICS
Upon successful completion, the address of the semaphore is returned.
Otherwise, a value of -1 is returned and errno is set to indicate the
error.
Page 3
