sem_open Subroutine

Purpose

Initializes and opens a named semaphore.

Library

Standard C Library (libc.a)

Syntax

#include <semaphore.h>

sem_t * sem_open (const char *name, int oflag, mode_t mode, unsigned value)

Description

The sem_open subroutine establishes a connection between a named semaphore and a process. Following a call to the sem_open subroutine with semaphore name name, the process may reference the semaphore using the address returned from the call. This semaphore may be used in subsequent calls to the sem_wait, sem_trywait, sem_post, and sem_close subroutines. 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 subroutines.

The name parameter points to a string naming a semaphore object. The name has no representation in the file system. The name parameter conforms to the construction rules for a pathname. It might begin with a slash character, and it must contain at least one character. Processes calling sem_open() with the same value of name refers to the same semaphore object, as long as that name has not been removed.

If a process makes multiple successful calls to the sem_open subroutine with the same value of the name parameter, the same semaphore address is returned for each such successful call, provided that there have been no calls to the sem_unlink subroutine for this semaphore.

Parameters

Item	Description
name	Points to a string naming a semaphore object.
oflag	Controls whether the semaphore is created or merely accessed by the call to the sem_open subroutine. The following flag bits may be set in the oflag parameter: O_CREAT This flag is used to create a semaphore if it does not already exist. If the O_CREAT flag is set and the semaphore already exists, the O_CREAT flag has no effect, except as noted under the description of the O_EXCL flag. Otherwise, the sem_open subroutine creates a named semaphore. The O_CREAT flag requires a third and a fourth parameter: 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 the effective group ID of the process. The permission bits of the semaphore are set to the value of the mode parameter except those set in the file mode creation mask of the process. When bits in mode other than file permission bits are set, they have no effect. When bits in mode other than file permission bits are set, they have no effect. After the semaphore named name has been created by the sem_open subroutine with the O_CREAT flag, other processes can connect to the semaphore by calling the sem_open subroutine with the same value of name. O_EXCL If the O_EXCL and O_CREAT flags are set, the sem_open subroutine 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 the sem_open subroutine with the O_EXCL and O_CREAT flags set. If O_EXCL is set and O_CREAT is not set, O_EXCL is ignored. If flags other than O_CREAT and O_EXCL are specified in the oflag parameter, they have no effect.
mode	Specifies the value of the file permission bits. Used with O_CREAT to create a message queue.
value	Specifies the initial value. Used with O_CREAT to create a message queue.

Return Values

Upon successful completion, the sem_open subroutine returns the address of the semaphore. Otherwise, it returns a value of SEM_FAILED and sets errno to indicate the error. The SEM_FAILED symbol is defined in the semaphore.h header file. No successful return from the sem_open subroutine returns the value SEM_FAILED.

Error Codes

If any of the following conditions occur, the sem_open subroutine returns SEM_FAILED and sets errno to the corresponding value:

Item	Description
EACCES	The named semaphore exists and the permissions specified by oflag are denied.
EEXIST	The O_CREAT and O_EXCL flags are set and the named semaphore already exists.
EFAULT	Invalid user address.
EINVAL	The sem_open subroutine is not supported for the given name, or the O_CREAT flag was specified in the oflag parameter and value was greater than SEM_VALUE_MAX.
EMFILE	Too many semaphore descriptors are currently in use by this process.
ENAMETOOLONG	The length of the name parameter exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
ENFILE	Too many semaphores are currently open in the system.
ENOENT	The O_CREAT flag is not set and the named semaphore does not exist.
ENOMEM	Insufficient memory for the required operation.
ENOTSUP	This function is not supported with processes that have been checkpoint-restart'ed.
ENOSPC	There is insufficient space for the creation of the new named semaphore.