sem_open()

initialize and open a named semaphore 

Realtime Function


SYNOPSIS

#include <semaphore.h>

sem_t *sem_open(const char *name, int oflag, ...);


DESCRIPTION

The sem_open() function creates a connection between a named semaphore and a process. One the connection has been created for the semaphore name specified by the name argument with a call to sem_open(), the process can use the address returned by the call to reference that semaphore. You can use the semaphore in subsequent calls to the sem_wait(), sem_trywait(), sem_post(), and sem_close() functions. This process can continue to use the semaphore until a call to sem_close() _exit(), or one of the exec functions closes it.

The oflag argument controls whether the semaphore is created or merely accessed by the call to sem_open(). It can have the following flag bits set:

O_CREAT 

Creates a semaphore if it does not already exist. If you set O_CREAT when a semaphore does not already exist, it has no effect except as indicated by the O_EXECL flag. If the semaphore does not already exist, sem_open() creates it. The O_CREAT flag requires two additional arguments: mode of type mode_t, and value of type unsigned int. The value argument specifies the initial value assigned to the newly created semaphore and must be less than or equal to SEM_VALUE_MAX. The effective user ID of the process is assigned as the user ID of the newly created semaphore, while the effective group ID of the process is assigned as the semaphore's group ID. Similarly, the value of the mode argument is used to set the permission bits of the newly created semaphore. Bits set in the file mode creation mask of the process are not set for the semaphore. Once sem_open() has created the semaphore named name with the O_CREAT flag, other processes can connect to the semaphore by calling the sem_open() function with the same name argument.

O_EXCL 

If oflag has both the O_EXCL and O_CREAT flags sets, sem_open() fails the specified semaphore already exists. The check for whether semaphore exists and creating the semaphore if it does not exist are atomic with respect to other processes executing sem_open() with O_EXCL and O_CREAT set.

When a process successfully calls the sem_open() multiple times with the same name argument, each successful call returns the same semaphore address. The only exception to this is if the sem_unlink() function has been called for this semaphore in the meantime.

Referring to copies of sem in other semaphore function calls is not recommended. While the current implementation of the semaphore functions supports the use of copies, there is no guarantee that future implementations will have this support.

Semaphores created with sem_init() should only be destroyed with the sem_destroy() function and semaphores created with sem_open() should only be closed with the sem_close() function.


PARAMETERS

name 

Points to a string naming a semaphore object. This must be valid semaphore name. Valid semaphore names are path name beginning with a slash (/).

oflag 

Controls whether the semaphore is created or merely accessed.


RETURN VALUES

When sem_open() is successful, it returns the address of the semaphore. Otherwise, it returns SEM_FAILED (defined in the header <semaphore.h>) and sets errno to one of the following values:

EACCES 

The semaphore name already exists and the permissions given by the oflag argument are denied, or the semaphore does not exist and permission to create it is denied.

EEXIST 

The O_CREAT and O_EXCL flags are set in oflag 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 string is greater than PATH_MAX, or a path name component is longer than NAME_MAX while _POSIX_NO_TRUNC is in effect.

ENFILE 

Too many semaphores are currently open in the system.

ENOENT 

O_CREAT is not set in oflag and the named semaphore does not exist.

ENOSPC 

There is insufficient space to create the new named semaphore.


EXAMPLES

None.


CONFORMANCE

UNIX 03. Derived from the POSIX Realtime Extension (1003.1b-1993/1003.1i-1995)


MULTITHREAD SAFETY LEVEL

MT-Safe.


PORTING ISSUES

None.


AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition


SEE ALSO

Functions:
sem_close(), sem_post(), sem_trywait(), sem_unlink(), sem_wait(), semctl(), semget(), semop()

Miscellaneous:
semaphores


PTC MKS Toolkit 10.4 Documentation Build 39.