sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy - operations on sema-
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 sema-
phores as described in ipc(5), semctl(2) and semop(2).
Semaphores are counters for resources shared between threads. The basic operations on sem-
aphores 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 sema-
phore is local to the current process ( pshared is zero) or is to be shared between sev-
eral 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_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 actu-
ally 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 function is async-signal safe and can there-
fore be called from signal handlers. This is the only thread synchronization function pro-
vided 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.
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 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.
Xavier Leroy <Xavier.Leroy@inria.fr>
pthread_mutex_init(3), pthread_cond_init(3), pthread_cancel(3), ipc(5).