SEMAPHORES(3)

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_trywait(sem_t * sem); int sem_post(sem_t * sem); int sem_getvalue(sem_t * sem, int * sval); int sem_destroy(sem_t * sem);

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.

CANCELLATION
!sem_wait! is a cancellation point.

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.

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!.

ERRORS
The !sem_init! function sets !errno! to the following codes on error:

    !EINVAL!
        |value| exceeds the maximal counter value !SEM_VALUE_MAX!

    !ENOSYS!
        |pshared| is not zero
The !sem_trywait! function sets !errno! to the following error code on error:

    !EAGAIN!
        the semaphore count is currently 0
The !sem_post! function sets !errno! to the following error code on error:

    !ERANGE!
        after incrementation, the semaphore value would exceed !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!
        some threads are currently blocked waiting on the semaphore.

AUTHOR
Xavier Leroy <Xavier.Leroy@inria.fr>

SEE ALSO
!pthread_mutex_init!(3), !pthread_cond_init!(3), !pthread_cancel!(3), !ipc!(5).