Table of Contents

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_timedwait(sem_t * sem, const struct timespec *abstime);

int sem_trywait(sem_t * sem);

int sem_post(sem_t * sem);

int sem_post_multiple(sem_t * sem, int number);

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

int sem_destroy(sem_t * sem);

Description

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).

Pthreads-w32 currently does not support process-shared semaphores, thus sem_init always returns with error EPERM if pshared is not zero.

sem_wait atomically decrements sem's count if it is greater than 0 and returns immediately or it suspends the calling thread until it can resume following a call to sem_post or sem_post_multiple.

sem_timedwait atomically decrements sem's count if it is greater than 0 and returns immediately, or it suspends the calling thread. If abstime time arrives before the thread can resume following a call to sem_post or sem_post_multiple, then sem_timedwait returns with a return code of -1 after having set errno to ETIMEDOUT. If the call can return without suspending then abstime is not checked.

sem_trywait atomically decrements sem's count if it is greater than 0 and returns immediately, or it returns immediately with a return code of -1 after having set errno to EAGAIN. sem_trywait never blocks.

sem_post either releases one thread if there are any waiting on sem, or it atomically increments sem's count.

sem_post_multiple either releases multiple threads if there are any waiting on sem and/or it atomically increases sem's count. If there are currently n waiters, where n the largest number less than or equal to number, then n waiters are released and sem's count is incremented by number minus n.

sem_getvalue stores in the location pointed to by sval the current count of the semaphore sem. In the Pthreads-w32 implementation: if the value returned in sval is greater than or equal to 0 it was the sem's count at some point during the call to sem_getvalue. If the value returned in sval is less than 0 then it's absolute value represents the number of threads waiting on sem at some point during the call to sem_getvalue. POSIX does not require an implementation of sem_getvalue to return a value in sval that is less than 0, but if it does then it's absolute value must represent the number of waiters.

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.

Cancellation

sem_wait and sem_timedwait are cancellation points.

Async-signal Safety

These routines are not async-cancel safe.

Return Value

All semaphore functions return 0 on success, or -1 on error in which case they write 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 _POSIX_SEM_VALUE_MAX
ENOSYS
pshared is not zero

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

ETIMEDOUT
if abstime arrives before the waiting thread can resume following a call to sem_post or sem_post_multiple.

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

EAGAIN
if the semaphore count is currently 0

The sem_post and sem_post_multiple functions set errno to the following error code on error:

ERANGE
if after incrementing, the semaphore count would exceed _POSIX_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
if some threads are currently blocked waiting on the semaphore.

Author

Xavier Leroy <Xavier.Leroy@inria.fr>

Modified by Ross Johnson for use with Pthreads-w32.

See Also

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


Table of Contents