From 7523c7c4d75652f67cd31cb123e1268790394c8b Mon Sep 17 00:00:00 2001 From: rpj Date: Fri, 6 May 2005 07:27:10 +0000 Subject: '' --- manual/sem_init.html | 202 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 202 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..5509859 --- /dev/null +++ b/manual/sem_init.html @@ -0,0 +1,202 @@ + + + + + SEMAPHORES(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

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

+ + + -- cgit v1.2.3