huschi.net

SEM_TIMEDWAIT(3P)          POSIX Programmer's Manual         SEM_TIMEDWAIT(3P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the  corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.
NAME
       sem_timedwait - lock a semaphore (ADVANCED REALTIME)
SYNOPSIS
       #include <semaphore.h>
       #include <time.h>
       int sem_timedwait(sem_t *restrict sem,
              const struct timespec *restrict abs_timeout);

DESCRIPTION
       The sem_timedwait() function shall lock the semaphore referenced by sem
       as  in  the  sem_wait()  function.  However, if the semaphore cannot be
       locked without waiting for another process or thread to unlock the sem-
       aphore  by  performing a sem_post() function, this wait shall be termi-
       nated when the specified timeout expires.
       The timeout shall expire when the absolute time specified by  abs_time-
       out  passes, as measured by the clock on which timeouts are based (that
       is, when the value of that clock equals or exceeds abs_timeout), or  if
       the  absolute  time specified by abs_timeout has already been passed at
       the time of the call.
       If the Timers option is supported, the timeout shall be  based  on  the
       CLOCK_REALTIME  clock. If the Timers option is not supported, the time-
       out shall be based on the system clock as returned by the time()  func-
       tion.  The  resolution  of  the  timeout shall be the resolution of the
       clock on which it is based. The timespec data  type  is  defined  as  a
       structure in the <time.h> header.
       Under  no  circumstance  shall  the function fail with a timeout if the
       semaphore can be locked immediately. The validity  of  the  abs_timeout
       need not be checked if the semaphore can be locked immediately.
RETURN VALUE
       The  sem_timedwait()  function shall return zero if the calling process
       successfully performed the semaphore lock operation  on  the  semaphore
       designated by sem. If the call was unsuccessful, the state of the sema-
       phore shall be unchanged, and the function shall return a value  of  -1
       and set errno to indicate the error.
ERRORS
       The sem_timedwait() function shall fail if:
       EINVAL The sem argument does not refer to a valid semaphore.
       EINVAL The  process  or  thread would have blocked, and the abs_timeout
              parameter specified a nanoseconds field value less than zero  or
              greater than or equal to 1000 million.
       ETIMEDOUT
              The  semaphore  could not be locked before the specified timeout
              expired.

       The sem_timedwait() function may fail if:
       EDEADLK
              A deadlock condition was detected.
       EINTR  A signal interrupted this function.

       The following sections are informative.
EXAMPLES
       None.
APPLICATION USAGE
       Applications using these functions may be subject  to  priority  inver-
       sion,    as    discussed    in   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, Section 3.285, Priority Inversion.
       The sem_timedwait() function is part of  the  Semaphores  and  Timeouts
       options and need not be provided on all implementations.
RATIONALE
       None.
FUTURE DIRECTIONS
       None.
SEE ALSO
       sem_post(),  sem_trywait(),  sem_wait(),  semctl(),  semget(), semop(),
       time(), the Base Definitions  volume  of  IEEE Std 1003.1-2001,  <sema-
       phore.h>, <time.h>
COPYRIGHT
       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                  2003                    SEM_TIMEDWAIT(3P)