sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy -
operations on semaphores
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);
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 pro-
cess ( 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
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
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.
sem_wait is a cancellation point.
On processors supporting atomic compare-and-swap (Intel 486, Pentium
and later, Alpha, PowerPC, MIPS II, Motorola 68k), the sem_post func-
tion is async-signal safe and can therefore be called from signal han-
dlers. 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
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.
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
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
The sem_destroy function sets errno to the following error code on
EBUSY some threads are currently blocked waiting on the
Xavier Leroy <Xavier.Leroy@inria.fr>
pthread_mutex_init(3), pthread_cond_init(3), pthread_cancel(3), ipc(5).