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

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       timer_getoverrun, timer_gettime, timer_settime — per-process timers
13

SYNOPSIS

15       #include <time.h>
16
17       int timer_getoverrun(timer_t timerid);
18       int timer_gettime(timer_t timerid, struct itimerspec *value);
19       int timer_settime(timer_t timerid, int flags,
20           const struct itimerspec *restrict value,
21           struct itimerspec *restrict ovalue);
22

DESCRIPTION

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

RETURN VALUE

92       If  the timer_getoverrun() function succeeds, it shall return the timer
93       expiration overrun count as explained above.
94
95       If the timer_gettime() or timer_settime() functions succeed, a value of
96       0 shall be returned.
97
98       If  an  error  occurs for any of these functions, the value -1 shall be
99       returned, and errno set to indicate the error.
100

ERRORS

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       The timer_settime() function may fail if:
109
110       EINVAL The it_interval member of value is not zero and  the  timer  was
111              created   with   notification   by  creation  of  a  new  thread
112              (sigev_sigev_notify was SIGEV_THREAD) and a fixed stack  address
113              has   been   set   in   the   thread  attribute  pointed  to  by
114              sigev_notify_attributes.
115
116       The following sections are informative.
117

EXAMPLES

119       None.
120

APPLICATION USAGE

122       Using fixed stack addresses is problematic  when  timer  expiration  is
123       signaled  by  the  creation of a new thread. Since it cannot be assumed
124       that the thread created for one expiration is finished before the  next
125       expiration  of the timer, it could happen that two threads use the same
126       memory as a stack at the same time. This is invalid and produces  unde‐
127       fined results.
128

RATIONALE

130       Practical  clocks  tick  at  a finite rate, with rates of 100 hertz and
131       1000 hertz being common. The inverse of this tick  rate  is  the  clock
132       resolution,  also called the clock granularity, which in either case is
133       expressed as a time duration, being 10 milliseconds and  1  millisecond
134       respectively  for  these  common  rates.  The  granularity of practical
135       clocks implies that if one reads a given clock twice in  rapid  succes‐
136       sion,  one may get the same time value twice; and that timers must wait
137       for the next clock tick  after  the  theoretical  expiration  time,  to
138       ensure  that  a timer never returns too soon. Note also that the granu‐
139       larity of the clock may be significantly coarser than the resolution of
140       the data format used to set and get time and interval values. Also note
141       that some implementations may choose to  adjust  time  and/or  interval
142       values to exactly match the ticks of the underlying clock.
143
144       This volume of POSIX.1‐2017 defines functions that allow an application
145       to determine the implementation-supported resolution for the clocks and
146       requires  an  implementation  to  document the resolution supported for
147       timers and nanosleep() if they differ from the supported clock  resolu‐
148       tion.  This  is  more of a procurement issue than a runtime application
149       issue.
150
151       If an implementation detects that the value specified  by  the  timerid
152       argument  to  timer_getoverrun(),  timer_gettime(),  or timer_settime()
153       does not correspond to a timer ID returned by  timer_create()  but  not
154       yet  deleted  by  timer_delete(),  it  is recommended that the function
155       should fail and report an [EINVAL] error.
156

FUTURE DIRECTIONS

158       None.
159

SEE ALSO

161       clock_getres(), timer_create()
162
163       The Base Definitions volume of POSIX.1‐2017, <time.h>
164
166       Portions of this text are reprinted and reproduced in  electronic  form
167       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
168       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
169       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
170       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
171       event of any discrepancy between this version and the original IEEE and
172       The Open Group Standard, the original IEEE and The Open Group  Standard
173       is  the  referee document. The original Standard can be obtained online
174       at http://www.opengroup.org/unix/online.html .
175
176       Any typographical or formatting errors that appear  in  this  page  are
177       most likely to have been introduced during the conversion of the source
178       files to man page format. To report such errors,  see  https://www.ker
179       nel.org/doc/man-pages/reporting_bugs.html .
180
181
182
183IEEE/The Open Group                  2017                 TIMER_GETOVERRUN(3P)
Impressum