sem_open()

Create/access a named semaphore

Synopsis:

#include <semaphore.h>

sem_t * sem_open( const char * sem_name,
                  int oflags,
                  ... );

Description:

The sem_open() function creates or opens a named semaphore. Named semaphores are slower than the unnamed semaphores created with sem_init().

The semaphore descriptor returned by sem_open() can be used with sem_wait(), sem_trywait(), sem_post(), and remains usable until sem_close() is called.

The sem_name argument must start with a / character, such as /myprog.sem1. Semaphores appear under /dev/sem, which would make this example appear in the filesystem as /dev/sem/myprog.sem1. Semaphore names must be less than (NAME_MAX - 8) characters.

Semaphore names shouldn't contain / characters except as the first character to maintain POSIX portability. QNX allows extra / characters in semaphore names.

The oflags argument is only used for semaphore creation.

Don't set oflags to O_RDONLY, O_RDWR, or O_WRONLY. A semaphore's behavior is undefined with these flags. The QNX libraries silently ignore these options, but it may reduce your code's portability.

When creating a new semaphore, oflags can be set to O_CREAT or (O_CREAT|O_EXCL):

O_CREAT

Create a new named semaphore. Two additional parameters are necessary when creating a new named semaphore, mode_t mode and unsigned int value; mode indicates the semaphore's mode (just like file modes), and value is the initial value of the semaphore. A value > 0 (positive) indicates an unlocked semaphore, and a value of 0 (zero) indicates a locked semaphore.

For portability, mode should set the read, write, and execute bits to the same value. An easy way of doing this is to use the constants from <sys/stat.h>:

S_IRWXG for group access
S_IRWXO for other's access
S_IRWXU for your own access

O_EXCL

When creating a new named semaphore, O_EXCL causes sem_open() to fail if a semaphore with sem_name already exists. Without O_EXCL, a sem_open() attaches to an existing semaphore or creates a new one if sem_name doesn't exist.

Don't mix named semaphore operations (such as sem_open() and sem_close()) with unnamed semaphore operations (such as sem_init() and sem_destroy()) on the same semaphore.

Semaphores persist as long as the system is up.

Returns:

A pointer to the created or accessed semaphore, or -1 for failure (errno is set).

Errors:

EACCES: Either the named semaphore exists and you don't have permission to access it, or you're trying to create a new semaphore and you don't have permission.
EEXIST: You specified O_CREAT and O_EXCL in oflags, but the semaphore already exists.
EINVAL: The sem_name argument is invalid or, when creating a semaphore, value is greater than SEM_VALUE_MAX.
EINTR: The call was interrupted by a signal.
ELOOP: Too many levels of symbolic links or prefixes.
EMFILE: The process is using too many files or semaphores.
ENFILE: The system ran out of resources and couldn't open the semaphore.
ENAMETOOLONG: The sem_name argument is longer than (NAME_MAX - 8).
ENOENT: The sem_name argument doesn't exist, and you didn't specify O_CREAT in oflags.
ENOSPC: There's insufficient space to create a new named semaphore.
ENOSYS: The sem_open() function isn't implemented for the filesystem specified in sem_name.

Classification:

POSIX 1003.1

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes

Caveats:

The mqueue manager must be running for applications to use named semaphores.