NAME

       timer_getoverrun, timer_gettime, timer_settime - per-process timers (REALTIME)

SYNOPSIS

       #include <time.h>

       int timer_getoverrun(timer_t timerid);
       int timer_gettime(timer_t timerid, struct itimerspec *value);
       int timer_settime(timer_t timerid, int flags,
              const struct itimerspec *restrict value,
              struct itimerspec *restrict ovalue);

DESCRIPTION

       The  timer_gettime()  function  shall  store the amount of time until the specified timer,
       timerid, expires and the reload value of the timer into the space pointed to by the  value
       argument.  The  it_value  member of this structure shall contain the amount of time before
       the timer expires, or zero if the timer  is  disarmed.  This  value  is  returned  as  the
       interval  until  timer  expiration,  even  if  the timer was armed with absolute time. The
       it_interval member of value shall contain the reload value last set by timer_settime().

       The timer_settime() function shall set the time until the next  expiration  of  the  timer
       specified  by  timerid from the it_value member of the value argument and arm the timer if
       the it_value member of value is non-zero. If the specified timer was  already  armed  when
       timer_settime()  is  called,  this  call shall reset the time until next expiration to the
       value specified. If the it_value member of value is zero, the timer shall be disarmed. The
       effect  of  disarming  or  resetting  a  timer  with  pending  expiration notifications is
       unspecified.

       If the flag TIMER_ABSTIME is not set in the argument flags, timer_settime()  shall  behave
       as  if  the time until next expiration is set to be equal to the interval specified by the
       it_value member of value. That is, the timer shall expire  in  it_value  nanoseconds  from
       when  the  call  is  made.  If  the  flag  TIMER_ABSTIME  is  set  in  the argument flags,
       timer_settime() shall behave as if the time until next expiration is set to  be  equal  to
       the difference between the absolute time specified by the it_value member of value and the
       current value of the clock associated with timerid.  That is, the timer shall expire  when
       the  clock  reaches  the value specified by the it_value member of value. If the specified
       time has already passed, the function shall succeed and the expiration notification  shall
       be made.

       The  reload  value  of  the  timer  shall be set to the value specified by the it_interval
       member of value. When a timer is  armed  with  a  non-zero  it_interval,  a  periodic  (or
       repetitive) timer is specified.

       Time  values  that  are  between  two  consecutive  non-negative  integer multiples of the
       resolution of the specified timer shall be rounded  up  to  the  larger  multiple  of  the
       resolution.  Quantization  error  shall  not  cause  the  timer to expire earlier than the
       rounded time value.

       If the argument ovalue is not NULL, the  timer_settime()  function  shall  store,  in  the
       location referenced by ovalue, a value representing the previous amount of time before the
       timer would have expired, or zero if the timer was disarmed, together  with  the  previous
       timer reload value. Timers shall not expire before their scheduled time.

       Only  a  single  signal  shall  be queued to the process for a given timer at any point in
       time. When a timer for which a signal is still pending expires, no signal shall be queued,
       and  a  timer  overrun  shall  occur.    When a timer expiration signal is delivered to or
       accepted by a process, if the implementation supports the Realtime Signals Extension,  the
       timer_getoverrun()  function  shall  return  the  timer  expiration  overrun count for the
       specified timer. The overrun count returned contains the number of extra timer expirations
       that occurred between the time the signal was generated (queued) and when it was delivered
       or  accepted,  up  to   but   not   including   an   implementation-defined   maximum   of
       {DELAYTIMER_MAX}.  If  the  number  of  such extra expirations is greater than or equal to
       {DELAYTIMER_MAX}, then the overrun count shall  be  set  to  {DELAYTIMER_MAX}.  The  value
       returned  by  timer_getoverrun() shall apply to the most recent expiration signal delivery
       or acceptance for the timer.  If no expiration signal has been delivered for the timer, or
       if the Realtime Signals Extension is not supported, the return value of timer_getoverrun()
       is unspecified.

RETURN VALUE

       If the timer_getoverrun() function succeeds, it shall return the timer expiration  overrun
       count as explained above.

       If  the  timer_gettime()  or  timer_settime()  functions  succeed,  a  value of 0 shall be
       returned.

       If an error occurs for any of these functions, the value -1 shall be returned,  and  errno
       set to indicate the error.

ERRORS

       The timer_getoverrun(), timer_gettime(), and timer_settime() functions shall fail if:

       EINVAL The  timerid  argument  does not correspond to an ID returned by timer_create() but
              not yet deleted by timer_delete().

       The timer_settime() function shall fail if:

       EINVAL A value structure specified a nanosecond value less than zero or  greater  than  or
              equal  to  1000  million, and the it_value member of that structure did not specify
              zero seconds and nanoseconds.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       None.

RATIONALE

       Practical clocks tick at a finite rate, with rates of  100  hertz  and  1000  hertz  being
       common.  The  inverse  of  this  tick  rate is the clock resolution, also called the clock
       granularity, which in either case is expressed as a time duration, being  10  milliseconds
       and  1  millisecond  respectively  for  these  common rates.  The granularity of practical
       clocks implies that if one reads a given clock twice in rapid succession, one may get  the
       same  time  value  twice;  and  that  timers  must  wait for the next clock tick after the
       theoretical expiration time, to ensure that a timer never returns too soon. Note also that
       the  granularity of the clock may be significantly coarser than the resolution of the data
       format used to set and get time and interval values. Also note that  some  implementations
       may  choose  to  adjust  time  and/or  interval  values  to exactly match the ticks of the
       underlying clock.

       This volume of  IEEE Std 1003.1-2001  defines  functions  that  allow  an  application  to
       determine   the  implementation-supported  resolution  for  the  clocks  and  requires  an
       implementation to document the resolution supported for timers  and  nanosleep()  if  they
       differ  from  the  supported clock resolution.  This is more of a procurement issue than a
       runtime application issue.

FUTURE DIRECTIONS

       None.

SEE ALSO

       clock_getres() , timer_create() , the Base  Definitions  volume  of  IEEE Std 1003.1-2001,
       <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 .