SEMAPHORES

NAME
SYNOPSIS
DESCRIPTION
CANCELLATION
ASYNC-SIGNAL SAFETY
RETURN VALUE
ERRORS
AUTHOR
SEE ALSO

NAME

sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy − operations on semaphores

SYNOPSIS

#include <semaphore.h>

int sem_init(sem_t *sem, int pshared, unsigned int value);

int sem_wait(sem_t * sem);

int sem_trywait(sem_t * sem);

int sem_post(sem_t * sem);

int sem_getvalue(sem_t * sem, int * sval);

int sem_destroy(sem_t * sem);

DESCRIPTION

This manual page documents POSIX 1003.1b semaphores, not to be confused with SystemV semaphores as described in ipc(5), semctl(2) and semop(2).

Semaphores are counters for resources shared between threads. The basic operations on semaphores are: increment the counter atomically, and wait until the counter is non-null and decrement it atomically.

sem_init initializes the semaphore object pointed to by sem. The count associated with the semaphore is set initially to value. The pshared argument indicates whether the semaphore is local to the current process ( pshared is zero) or is to be shared between several processes ( pshared is not zero). LinuxThreads currently does not support process-shared semaphores, thus sem_init always returns with error ENOSYS if pshared is not zero.

sem_wait suspends the calling thread until the semaphore pointed to by sem has non-zero count. It then atomically decreases the semaphore count.

sem_trywait is a non-blocking variant of sem_wait. If the semaphore pointed to by sem has non-zero count, the count is atomically decreased and sem_trywait immediately returns 0. If the semaphore count is zero, sem_trywait immediately returns with error EAGAIN.

sem_post atomically increases the count of the semaphore pointed to by sem. This function never blocks and can safely be used in asynchronous signal handlers.

sem_getvalue stores in the location pointed to by sval the current count of the semaphore sem.

sem_destroy destroys a semaphore object, freeing the resources it might hold. No threads should be waiting on the semaphore at the time sem_destroy is called. In the LinuxThreads implementation, no resources are associated with semaphore objects, thus sem_destroy actually does nothing except checking that no thread is waiting on the semaphore.

CANCELLATION

sem_wait is a cancellation point.

ASYNC-SIGNAL SAFETY

On processors supporting atomic compare-and-swap (Intel 486, Pentium and later, Alpha, PowerPC, MIPS II, Motorola 68k), the sem_post function is async-signal safe and can therefore be called from signal handlers. This is the only thread synchronization function provided by POSIX threads that is async-signal safe.

On the Intel 386 and the Sparc, the current LinuxThreads implementation of sem_post is not async-signal safe by lack of the required atomic operations.

RETURN VALUE

The sem_wait and sem_getvalue functions always return 0. All other semaphore functions return 0 on success and -1 on error, in addition to writing an error code in errno.

ERRORS

The sem_init function sets errno to the following codes on error:

EINVAL

value exceeds the maximal counter value SEM_VALUE_MAX

ENOSYS

pshared is not zero

The sem_trywait function sets errno to the following error code on error:

EAGAIN

the semaphore count is currently 0

The sem_post function sets errno to the following error code on error:

ERANGE

after incrementation, the semaphore value would exceed SEM_VALUE_MAX (the semaphore count is left unchanged in this case)

The sem_destroy function sets errno to the following error code on error:

EBUSY

some threads are currently blocked waiting on the semaphore.

AUTHOR

Xavier Leroy <Xavier.Leroy@inria.fr>

SEE ALSO

pthread_mutex_init(3), pthread_cond_init(3), pthread_cancel(3), ipc(5).