creatsem(S)

creatsem -- creates an instance of a binary semaphore

Syntax

cc . . . -lx

int creatsem (sem_name, mode)
char *sem_name;
int mode;

Description

creatsem defines a binary semaphore named by sem_name to be used by waitsem(S) and sigsem(S) to manage mutually exclusive access to a resource, shared variable, or critical section of a program. creatsem returns a unique semaphore number, sem_num, which may then be used as the parameter in waitsem and sigsem calls. Semaphores are special files of 0 length. The filename space is used to provide unique identifiers for semaphores. mode sets the accessibility of the semaphore using the same format as file access bits. Access to a semaphore is granted only on the basis of the read access bit; the write and execute bits are ignored.

A semaphore can be operated on only by a synchronizing primitive, such as waitsem or sigsem, by creatsem which initializes it to some value, or by opensem which opens the semaphore for use by a process. Synchronizing primitives are guaranteed to be executed without interruption once started. These primitives are used by associating a semaphore with each resource (including critical code sections) to be protected.

The process controlling the semaphore should issue:

   sem_num = creatsem(semaphore, mode);

to create, initialize, and open the semaphore for that process. All other processes using the semaphore should issue:

   sem_num = opensem(semaphore);

to access the semaphore's identification value. Note that a process cannot open and use a semaphore that has not been initialized by a call to creatsem, nor should a process open a semaphore more than once in one period of execution. Both the creating and opening processes use waitsem and sigsem to use the semaphore sem_num.

Diagnostics

creatsem returns the value -1 if an error occurs. errno is set under these conditions:

[EEXIST]: The semaphore named by sem_name is already open for use by other processes.
[ENAVAIL]: The semaphore has not been initialized by a call to creatsem.
[ENOTNAM]: The file specified exists but is not a semaphore type.

Notes

After a calling creatsem, use waitsem to gain control of a given resource.

Compatibility

creatsem can only be used to define UNIX version 3.0 type semaphores, not UNIX System V type semaphores.

This feature is a XENIX specific enhancement and may not be present in all UNIX implementations.

Standards conformance

creatsem is an extension of AT&T System V provided by the Santa Cruz Operation.