1 SEM_TIMEDWAIT(3C)        Standard C Library Functions        SEM_TIMEDWAIT(3C)
   2 
   3 
   4 
   5 NAME
   6        sem_timedwait, sem_reltimedwait_np - lock a semaphore
   7 
   8 SYNOPSIS
   9        #include <semaphore.h>
  10        #include <time.h>
  11 
  12        int sem_timedwait(sem_t *restrict sem,
  13             const struct timespec *restrict abs_timeout);
  14 
  15 
  16        int sem_reltimedwait_np(sem_t *restrict sem,
  17             const struct timespec *restrict rel_timeout);
  18 
  19 
  20 DESCRIPTION
  21        The sem_timedwait() function locks the semaphore referenced by sem as
  22        in the sem_wait(3C) function. However, if the semaphore cannot be
  23        locked without waiting for another process or thread to unlock the
  24        semaphore by performing a sem_post(3C) function, this wait is
  25        terminated when the specified timeout expires.
  26 
  27 
  28        The sem_reltimedwait_np() function is identical to the sem_timedwait()
  29        function, except that the timeout is specified as a relative time
  30        interval.
  31 
  32 
  33        For sem_timedwait(), the timeout expires when the absolute time
  34        specified by abs_timeout passes, as measured by the CLOCK_REALTIME
  35        clock (that is, when the value of that clock equals or exceeds
  36        abs_timeout), or if the absolute time specified by abs_timeout has
  37        already been passed at the time of the call.
  38 
  39 
  40        For sem_reltimedwait_np(), the timeout expires when the time interval
  41        specified by rel_timeout passes, as measured by the CLOCK_REALTIME
  42        clock, or if the time interval specified by rel_timeout is negative at
  43        the time of the call.
  44 
  45 
  46        The resolution of the timeout is the resolution of the CLOCK_REALTIME
  47        clock. The timespec data type is defined as a structure in the <time.h>
  48        header.
  49 
  50 
  51        Under no circumstance does the function fail with a timeout if the
  52        semaphore can be locked immediately. The validity of the abs_timeout
  53        need not be checked if the semaphore can be locked immediately.
  54 
  55 RETURN VALUES
  56        The sem_timedwait() and sem_reltimedwait_np() functions return 0 if the
  57        calling process successfully performed the semaphore lock operation on
  58        the semaphore designated by sem. If the call was unsuccessful, the
  59        state of the semaphore is be unchanged and the function returns -1 and
  60        sets errno to indicate the error.
  61 
  62 ERRORS
  63        The sem_timedwait() and sem_reltimedwait_np() functions will fail if:
  64 
  65        EINVAL
  66                     The sem argument does not refer to a valid semaphore.
  67 
  68 
  69        EINVAL
  70                     The process or thread would have blocked, and the timeout
  71                     parameter specified a nanoseconds field value less than
  72                     zero or greater than or equal to 1,000 million.
  73 
  74 
  75        ETIMEDOUT
  76                     The semaphore could not be locked before the specified
  77                     timeout expired.
  78 
  79 
  80 
  81        The sem_timedwait() and sem_reltimedwait_np() functions may fail if:
  82 
  83        EDEADLK
  84                   A deadlock condition was detected.
  85 
  86 
  87        EINTR
  88                   A signal interrupted this function.
  89 
  90 
  91 ATTRIBUTES
  92        See attributes(5) for descriptions of the following attributes:
  93 
  94 
  95 
  96 
  97        +--------------------+-----------------+
  98        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
  99        +--------------------+-----------------+
 100        |Interface Stability | Committed       |
 101        +--------------------+-----------------+
 102        |MT-Level            | MT-Safe         |
 103        +--------------------+-----------------+
 104        |Standard            | See below.      |
 105        +--------------------+-----------------+
 106 
 107 
 108        For sem_timedwait(), see standards(5).
 109 
 110 SEE ALSO
 111        semctl(2), semget(2), semop(2), time(2), sem_post(3C), sem_trywait(3C),
 112        sem_wait(3C), attributes(5), standards(5)
 113 
 114 
 115 
 116                                February 5, 2008              SEM_TIMEDWAIT(3C)