1TIMER_GETOVERRUN(P)        POSIX Programmer's Manual       TIMER_GETOVERRUN(P)
2
3
4

NAME

6       timer_getoverrun,  timer_gettime,  timer_settime  -  per-process timers
7       (REALTIME)
8

SYNOPSIS

10       #include <time.h>
11
12       int timer_getoverrun(timer_t timerid);
13       int timer_gettime(timer_t timerid, struct itimerspec *value);
14       int timer_settime(timer_t timerid, int flags,
15              const struct itimerspec *restrict value,
16              struct itimerspec *restrict ovalue);
17
18

DESCRIPTION

20       The timer_gettime() function shall store the amount of time  until  the
21       specified  timer,  timerid,  expires  and the reload value of the timer
22       into the space pointed to by the value argument. The it_value member of
23       this  structure  shall  contain  the  amount  of  time before the timer
24       expires, or zero if the timer is disarmed. This value  is  returned  as
25       the  interval  until timer expiration, even if the timer was armed with
26       absolute time. The it_interval member of value shall contain the reload
27       value last set by timer_settime().
28
29       The  timer_settime() function shall set the time until the next expira‐
30       tion of the timer specified by timerid from the it_value member of  the
31       value  argument  and  arm  the timer if the it_value member of value is
32       non-zero. If the specified timer was already armed when timer_settime()
33       is  called, this call shall reset the time until next expiration to the
34       value specified. If the it_value member of value  is  zero,  the  timer
35       shall  be  disarmed.  The effect of disarming or resetting a timer with
36       pending expiration notifications is unspecified.
37
38       If the flag TIMER_ABSTIME is not set in the argument flags,  timer_set‐
39       time()  shall  behave as if the time until next expiration is set to be
40       equal to the interval specified by the it_value member of  value.  That
41       is,  the  timer shall expire in it_value nanoseconds from when the call
42       is made. If the flag  TIMER_ABSTIME  is  set  in  the  argument  flags,
43       timer_settime()  shall  behave  as if the time until next expiration is
44       set to be equal to the difference between the absolute  time  specified
45       by  the  it_value  member  of  value and the current value of the clock
46       associated with timerid.  That is, the  timer  shall  expire  when  the
47       clock  reaches  the value specified by the it_value member of value. If
48       the specified time has already passed, the function shall  succeed  and
49       the expiration notification shall be made.
50
51       The  reload  value  of the timer shall be set to the value specified by
52       the it_interval member of value. When a timer is armed with a  non-zero
53       it_interval, a periodic (or repetitive) timer is specified.
54
55       Time  values that are between two consecutive non-negative integer mul‐
56       tiples of the resolution of the specified timer shall be rounded up  to
57       the  larger  multiple  of  the resolution. Quantization error shall not
58       cause the timer to expire earlier than the rounded time value.
59
60       If the argument ovalue is not NULL, the timer_settime() function  shall
61       store,  in  the location referenced by ovalue, a value representing the
62       previous amount of time before the timer would have expired, or zero if
63       the  timer was disarmed, together with the previous timer reload value.
64       Timers shall not expire before their scheduled time.
65
66       Only a single signal shall be queued to the process for a  given  timer
67       at  any point in time. When a timer for which a signal is still pending
68       expires, no signal shall be queued, and a timer  overrun  shall  occur.
69        When  a  timer  expiration  signal  is  delivered  to or accepted by a
70       process, if the implementation supports the Realtime Signals Extension,
71       the timer_getoverrun() function shall return the timer expiration over‐
72       run count for the specified timer. The overrun count returned  contains
73       the  number  of  extra timer expirations that occurred between the time
74       the signal  was  generated  (queued)  and  when  it  was  delivered  or
75       accepted,  up to but not including an implementation-defined maximum of
76       {DELAYTIMER_MAX}. If the number of such extra  expirations  is  greater
77       than  or equal to {DELAYTIMER_MAX}, then the overrun count shall be set
78       to {DELAYTIMER_MAX}. The value  returned  by  timer_getoverrun()  shall
79       apply  to  the most recent expiration signal delivery or acceptance for
80       the timer.  If no expiration signal has been delivered for  the  timer,
81       or if the Realtime Signals Extension is not supported, the return value
82       of timer_getoverrun() is unspecified.
83

RETURN VALUE

85       If the timer_getoverrun() function succeeds, it shall return the  timer
86       expiration overrun count as explained above.
87
88       If the timer_gettime() or timer_settime() functions succeed, a value of
89       0 shall be returned.
90
91       If an error occurs for any of these functions, the value  -1  shall  be
92       returned, and errno set to indicate the error.
93

ERRORS

95       The  timer_getoverrun(), timer_gettime(), and timer_settime() functions
96       shall fail if:
97
98       EINVAL The timerid argument does not correspond to an  ID  returned  by
99              timer_create() but not yet deleted by timer_delete().
100
101
102       The timer_settime() function shall fail if:
103
104       EINVAL A value structure specified a nanosecond value less than zero or
105              greater than or equal to 1000 million, and the  it_value  member
106              of that structure did not specify zero seconds and nanoseconds.
107
108
109       The following sections are informative.
110

EXAMPLES

112       None.
113

APPLICATION USAGE

115       None.
116

RATIONALE

118       Practical  clocks  tick  at  a finite rate, with rates of 100 hertz and
119       1000 hertz being common. The inverse of this tick  rate  is  the  clock
120       resolution,  also called the clock granularity, which in either case is
121       expressed as a time duration, being 10 milliseconds and  1  millisecond
122       respectively  for  these  common  rates.   The granularity of practical
123       clocks implies that if one reads a given clock twice in  rapid  succes‐
124       sion,  one may get the same time value twice; and that timers must wait
125       for the next clock tick  after  the  theoretical  expiration  time,  to
126       ensure  that  a timer never returns too soon. Note also that the granu‐
127       larity of the clock may be significantly coarser than the resolution of
128       the data format used to set and get time and interval values. Also note
129       that some implementations may choose to  adjust  time  and/or  interval
130       values to exactly match the ticks of the underlying clock.
131
132       This  volume  of  IEEE Std 1003.1-2001  defines functions that allow an
133       application to determine the  implementation-supported  resolution  for
134       the  clocks  and  requires an implementation to document the resolution
135       supported for timers and nanosleep() if they differ from the  supported
136       clock  resolution.   This is more of a procurement issue than a runtime
137       application issue.
138

FUTURE DIRECTIONS

140       None.
141

SEE ALSO

143       clock_getres() ,  timer_create()  ,  the  Base  Definitions  volume  of
144       IEEE Std 1003.1-2001, <time.h>
145
147       Portions  of  this text are reprinted and reproduced in electronic form
148       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
149       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
150       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
151       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
152       event of any discrepancy between this version and the original IEEE and
153       The  Open Group Standard, the original IEEE and The Open Group Standard
154       is the referee document. The original Standard can be  obtained  online
155       at http://www.opengroup.org/unix/online.html .
156
157
158
159IEEE/The Open Group                  2003                  TIMER_GETOVERRUN(P)
Impressum