133 lines
3.9 KiB
Groff
133 lines
3.9 KiB
Groff
.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).
|
|
|