sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy - operations on semaphores
#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);
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.
sem_wait and sem_timedwait are cancellation points.
These routines are not async-cancel safe.
All semaphore functions return 0 on success, or -1 on error in which case they write an error code in errno.
The sem_init function sets errno to the following codes on error:
pshared is not zero
The sem_timedwait function sets errno to the following error code on error:
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:
if the semaphore count is currently 0
The sem_post and sem_post_multiple functions set errno to the following error code on error:
The sem_destroy function sets errno to the following error code on error:
Xavier Leroy <Xavier.Leroy@inria.fr>
Modified by Ross Johnson for use with Pthreads-w32.
pthread_mutex_init(3) , pthread_cond_init(3) , pthread_cancel(3) .