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 semaphore by performing a sem_post() function,
       this wait shall be terminated when the specified timeout expires.

       The timeout shall expire when the  absolute  time  specified  by  abs_timeout  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 timeout shall be based on the system  clock  as
       returned  by the time() function. 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 semaphore 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 inversion, 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, <semaphore.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 .