sem_open(3R)

NAME

sem_open − initialize/open a named semaphore

SYNOPSIS

cc [ flag ... ] file ... −lposix4 [ library ... ]

#include <semaphore.h>

sem_t ∗sem_open(const char ∗name, int oflag,

/∗ unsigned long mode, unsigned int value ∗/ ... );

DESCRIPTION

The sem_open() function establishes a connection to a semaphore, name, returning the address of the semaphore to the calling process (or LWP or thread) for subsequent calls to sem_wait(3R), sem_trywait(3R), sem_post(3R), and sem_close(3R). The semaphore remains usable by this process until the semaphore is closed.

The name argument points to a string naming a semaphore object. The name argument should conform to the construction rules for a pathname. If a process makes multiple successful calls to sem_open() with the same value for name, the same semaphore address will be returned for each such successful call, provided that there have been no calls to sem_unlink(3R) for this semaphore. The first character of name must be a slash (/) character and the remaining characters of name cannot include any slash characters. For maximum portability, name should include no more than 14 characters, but this limit is not enforced.

The oflag argument determines whether the semaphore is created or merely accessed by the call to sem_open(). The three valid values for oflag are 0, O_CREAT, or the bitwise inclusive OR of O_CREAT and O_EXCL. Setting the oflag bits to O_CREAT will create the semaphore if it does not already exist. Setting both O_CREAT and O_EXCL will fail if the semaphore already exists. The check for the existence of the semaphore and the creation of the semaphore if it does not exist is atomic with respect to other processes executing sem_open(). After the semaphore named name has been created by sem_open() with the O_CREAT flag, other processes can connect to this semaphore by calling sem_open() with the same value of name, and nobits set in oflag.

Using the O_CREAT flag requires a third and a fourth argument: mode and value. The semaphore is created with an initial count of value. value must be less than or equal to SEM_VALUE_MAX. The semaphore’s user ID acquires the effective user ID of the process; the semaphore’s group ID is set to a system default group ID or to the effective group ID of the process. The semaphore’s permission bits is set to the value of mode, modified by clearing all bits set in the file creation mask of the process (see umask(2)).

RETURN VALUES

If successful, sem_open() returns the address of the semaphore, otherwise it returns −1 and sets errno to indicate the error condition.

ERRORS

EACCES The named semaphore exists and the O_RDWR permissions 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() function was interrupted by a signal.

EINVAL The name argument is not a valid name, or O_CREAT was set in oflag and value is greater than SEM_VALUE_MAX.

EMFILE The number of open semaphore descriptors in this process exceeds SEM_NSEMS_MAX.

The number of open file descriptors in this process exceeds OPEN_MAX.

ENAMETOOLONG
The string-length of name exceeds PATH_MAX, or a pathname component is longer than NAME_MAX while _POSIX_NO_TRUNC is in effect.

ENFILE The system file table is full.

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.

ENOSYS The sem_open() function is not supported.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

Museum

Related Articles