SEMAPHORES(3) manual page

From 41f88a82b33cdb357c83b582381232733ed2d039 Mon Sep 17 00:00:00 2001 From: rpj Date: Thu, 5 May 2005 14:18:27 +0000 Subject: '' --- manual/sem_init.html | 200 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 manual/sem_init.html (limited to 'manual/sem_init.html') diff --git a/manual/sem_init.html b/manual/sem_init.html new file mode 100644 index 0000000..238754f --- /dev/null +++ b/manual/sem_init.html @@ -0,0 +1,200 @@ + + + + + SEMAPHORES(3) manual page + + + + + + + +

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.

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.

Name

Synopsis

Description

Cancellation

Async-signal Safety

Return Value

Errors

+Author

See Also