SEMAPHORES(3)                                       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 ini-
       tially 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 sup-
       port  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_can-
       cel(3), ipc(5).

                           LinuxThreads                         1