SEMAPHORES(3)						     Library Functions Manual						     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 pro-
       cesses  (  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 asynchro-
       nous 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 func-
       tion 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).

								   LinuxThreads 						     SEMAPHORES(3)