diff options
Diffstat (limited to 'linuxthreads/man/sem_init.man')
| -rw-r--r-- | linuxthreads/man/sem_init.man | 132 |
1 files changed, 132 insertions, 0 deletions
diff --git a/linuxthreads/man/sem_init.man b/linuxthreads/man/sem_init.man new file mode 100644 index 0000000000..e3a1a63e36 --- /dev/null +++ b/linuxthreads/man/sem_init.man @@ -0,0 +1,132 @@ +.TH SEMAPHORES 3 LinuxThreads + +.XREF sem_wait +.XREF sem_trywait +.XREF sem_post +.XREF sem_getvalue +.XREF sem_destroy + +.SH NAME +sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy \- operations on semaphores + +.SH SYNOPSIS +#include <semaphore.h> + +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); + +.SH DESCRIPTION +This manual page documents POSIX 1003.1b semaphores, not to be +confused with SystemV semaphores as described in !ipc!(5), !semctl!(2) +and !semop!(2). + +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). 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|. + +!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! +actually does nothing except checking that no thread is waiting on the +semaphore. + +.SH CANCELLATION + +!sem_wait! is a cancellation point. + +.SH "ASYNC-SIGNAL SAFETY" + +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 therefore be +called from signal handlers. This is the only thread synchronization +function provided 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. + +.SH "RETURN VALUE" + +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!. + +.SH ERRORS + +The !sem_init! function sets !errno! to the following codes on error: +.RS +.TP +!EINVAL! +|value| exceeds the maximal counter value !SEM_VALUE_MAX! +.TP +!ENOSYS! +|pshared| is not zero +.RE + +The !sem_trywait! function sets !errno! to the following error code on error: +.RS +.TP +!EAGAIN! +the semaphore count is currently 0 +.RE + +The !sem_post! function sets !errno! to the following error code on error: +.RS +.TP +!ERANGE! +after incrementation, the semaphore value would exceed !SEM_VALUE_MAX! +(the semaphore count is left unchanged in this case) +.RE + +The !sem_destroy! function sets !errno! to the following error code on error: +.RS +.TP +!EBUSY! +some threads are currently blocked waiting on the semaphore. +.RE + +.SH AUTHOR +Xavier Leroy <Xavier.Leroy@inria.fr> + +.SH "SEE ALSO" +!pthread_mutex_init!(3), +!pthread_cond_init!(3), +!pthread_cancel!(3), +!ipc!(5). + |