sem_wait(2)                                                     sem_wait(2)




 NAME    [Toc]    [Back]
      sem_wait, sem_trywait - lock a POSIX semaphore

 SYNOPSIS    [Toc]    [Back]
      #include <sys/semaphore.h>

      int sem_wait(sem_t *sem);

      int sem_trywait(sem_t *sem);

 DESCRIPTION    [Toc]    [Back]
      sem_wait() is used to lock a semaphore.  The calling thread will not
      return from its call to sem_wait() until one of the following events
      occur: it successfully obtains a lock on the semaphore; it is
      interrupted by a signal or an error condition occurs.

      sem_trywait() is used to lock a semaphore, if it is available.  The
      value of the semaphore sem is checked at some unspecified time during
      the call.  If the semaphore is available at the time its value is
      checked, the calling thread will atomically, with respect to the
      checking of the value, lock the semaphore.  The thread will now own a
      lock on the semaphore; the call will return successfully.  If the
      semaphore is unavailable at the time its value is checked, then the
      call returns -1 with errno set to EAGAIN.

      If the specified semaphore referred to by sem is a named semaphore,
      then this semaphore must have been opened by the calling process with
      sem_open().  The calling process must have both read and write
      permissions on the semaphore to perform these operations.  The
      semaphore will be locked upon successful return and will stay locked
      until it is explicitly released by a call to sem_post().

      To use this function, link in the realtime library by specifying -lrt
      on the compiler or linker command line.

 EXAMPLES    [Toc]    [Back]
      The following call to sem_wait() will lock the semaphore sem.

           sem_wait(sem);

      The following call to sem_trywait() will lock the semaphore sem, if it
      is available.

           sem_trywait(sem);

 RETURN VALUE    [Toc]    [Back]
      A successful call to sem_wait() will return 0 and the calling thread
      will then own a lock on the semaphore.  Otherwise, the call to
      sem_wait() will return -1 with errno set to the appropriate value of
      the error condition.




 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 sem_wait(2)                                                     sem_wait(2)




      A successful call to sem_trywait() will return 0, if the semaphore was
      available and the calling thread was able to lock the semaphore.
      Otherwise, the call to sem_trywait() will return -1 with errno set to
      the appropriate value of the error condition.

 ERRORS    [Toc]    [Back]
      sem_wait() and sem_trywait() fail and do not perform the requested
      operation if any of the following conditions are encountered:

           [EPERM]        The calling process does not have the privileges
                          necessary to lock the semaphore.

           [EAGAIN]       The semaphore was not available and hence could
                          not be locked by sem_trywait().  This error
                          condition only occurs in sem_trywait().

           [EINVAL]       The argument sem does not refer to a valid
                          semaphore.

           [EINTR]        The function was interrupted by a signal

 SEE ALSO    [Toc]    [Back]
      sem_post(2), <semaphore.h>.

 STANDARDS CONFORMANCE    [Toc]    [Back]
      sem_wait(),sem_trywait(): POSIX


 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003