GNU Info

(libc.info)POSIX Semaphores

---

Next: Thread-Specific Data Prev: Condition Variables Up: POSIX Threads

---

Enter node , (file) or (file)node

POSIX Semaphores
================

   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.

   Semaphores have a maximum value past which they cannot be
incremented.  The macro `SEM_VALUE_MAX' is defined to be this maximum
value.  In the GNU C library, `SEM_VALUE_MAX' is equal to `INT_MAX'
(Note: Range of Type), but it may be much smaller on other systems.

   The pthreads library implements POSIX 1003.1b semaphores.  These
should not be confused with System V semaphores (`ipc', `semctl' and
`semop').

   All the semaphore functions and macros are defined in `semaphore.h'.

 - Function: int sem_init (sem_t *SEM, int PSHARED, unsigned int VALUE)
     `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).

     On success `sem_init' returns 0.  On failure it returns -1 and sets
     ERRNO to one of the following values:

    `EINVAL'
          VALUE exceeds the maximal counter value `SEM_VALUE_MAX'

    `ENOSYS'
          PSHARED is not zero.  LinuxThreads currently does not support
          process-shared semaphores.  (This will eventually change.)

 - Function: int sem_destroy (sem_t * SEM)
     `sem_destroy' destroys a semaphore object, freeing the resources it
     might hold.  If any threads are waiting on the semaphore when
     `sem_destroy' is called, it fails and sets ERRNO to `EBUSY'.

     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.  This
     will change when process-shared semaphores are implemented.

 - Function: int sem_wait (sem_t * SEM)
     `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_wait' is a cancellation point.  It always returns 0.

 - Function: int sem_trywait (sem_t * SEM)
     `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 -1
     and sets errno to `EAGAIN'.

 - Function: int sem_post (sem_t * SEM)
     `sem_post' atomically increases the count of the semaphore pointed
     to by SEM. This function never blocks.

     On processors supporting atomic compare-and-swap (Intel 486,
     Pentium and later, Alpha, PowerPC, MIPS II, Motorola 68k,
     Ultrasparc), the `sem_post' function is can safely 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 earlier Sparc chips, the current LinuxThreads
     implementation of `sem_post' is not async-signal safe, because the
     hardware does not support the required atomic operations.

     `sem_post' always succeeds and returns 0, unless the semaphore
     count would exceed `SEM_VALUE_MAX' after being incremented.  In
     that case `sem_post' returns -1 and sets ERRNO to `EINVAL'.  The
     semaphore count is left unchanged.

 - Function: int sem_getvalue (sem_t * SEM, int * SVAL)
     `sem_getvalue' stores in the location pointed to by SVAL the
     current count of the semaphore SEM.  It always returns 0.