]>
Commit | Line | Data |
---|---|---|
c6f51a12 MK |
1 | .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
c6f51a12 MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
4784c377 | 25 | .\" |
d08919a3 | 26 | .TH TIMER_GETOVERRUN 2 2009-02-20 Linux "Linux Programmer's Manual" |
c6f51a12 MK |
27 | .SH NAME |
28 | timer_getoverrun \- get overrun count for a POSIX per-process timer | |
29 | .SH SYNOPSIS | |
30 | .nf | |
31 | .B #include <time.h> | |
32 | ||
33 | .BI "int timer_getoverrun(timer_t " timerid ); | |
34 | .fi | |
35 | ||
702cbe15 | 36 | Link with \fI\-lrt\fP. |
c6f51a12 MK |
37 | .sp |
38 | .in -4n | |
39 | Feature Test Macro Requirements for glibc (see | |
40 | .BR feature_test_macros (7)): | |
41 | .in | |
42 | .sp | |
43 | .BR timer_getoverrun (): | |
98dbe7af | 44 | _POSIX_C_SOURCE\ >=\ 199309L |
c6f51a12 MK |
45 | .SH DESCRIPTION |
46 | .BR timer_getoverrun () | |
47 | returns the "overrun count" for the timer referred to by | |
48 | .IR timerid . | |
49 | An application can use the overrun count to accurately calculate the number | |
50 | of timer expirations that would have occurred over a given time interval. | |
51 | Timer overruns can occur both when receiving expiration notifications | |
52 | via signals | |
53 | .RB ( SIGEV_SIGNAL ), | |
54 | and via threads | |
55 | .RB ( SIGEV_THREAD ). | |
56 | ||
57 | When expiration notifications are delivered via a signal, | |
58 | overruns can occur as follows. | |
59 | Regardless of whether or not a real-time signal is used for | |
60 | timer notifications, | |
61 | the system queues at most one signal per timer. | |
62 | (This is the behavior specified by POSIX.1-2001. | |
63 | The alternative, queuing one signal for each timer expiration, | |
64 | could easily result in overflowing the allowed limits for | |
65 | queued signals on the system.) | |
66 | Because of system scheduling delays, | |
67 | or because the signal may be temporarily blocked, | |
68 | there can be a delay between the time when the notification | |
69 | signal is generated and the time when it | |
70 | is delivered (e.g., caught by a signal handler) or accepted (e.g., using | |
71 | .BR sigwaitinfo (2)). | |
72 | In this interval, further timer expirations may occur. | |
73 | The timer overrun count is the number of additional | |
74 | timer expirations that occurred between the time when the signal | |
75 | was generated and when it was delivered or accepted. | |
76 | ||
77 | Timer overruns can also occur when expiration notifications | |
78 | are delivered via invocation of a thread, | |
79 | since there may be an arbitrary delay between an expiration of the timer | |
80 | and the invocation of the notification thread, | |
81 | and in that delay interval, additional timer expirations may occur | |
82 | .SH RETURN VALUE | |
83 | On success, | |
84 | .BR timer_getoverrun () | |
85 | returns the overrun count of the specified timer; | |
86 | this count may be 0 if no overruns have occurred. | |
87 | On failure, \-1 is returned, and | |
88 | .I errno | |
89 | is set to indicate the error. | |
90 | .SH ERRORS | |
91 | .TP | |
92 | .B EINVAL | |
93 | .I timerid | |
94 | is not a valid timer ID. | |
95 | .SH VERSIONS | |
96 | This system call is available since Linux 2.6. | |
97 | .SH CONFORMING TO | |
82b6d797 | 98 | POSIX.1-2001. |
c6f51a12 MK |
99 | .SH NOTES |
100 | When timer notifications are delivered via signals | |
101 | .RB ( SIGEV_SIGNAL ), | |
102 | on Linux it is also possible to obtain the overrun count via the | |
103 | .I si_overrun | |
104 | field of the | |
105 | .I siginfo_t | |
106 | structure (see | |
107 | .BR sigaction (2)). | |
108 | This allows an application to avoid the overhead of making | |
109 | a system call to obtain the overrun count, | |
d603cc27 | 110 | but is a nonportable extension to POSIX.1-2001. |
c6f51a12 MK |
111 | |
112 | POSIX.1-2001 only discusses timer overruns in the context of | |
113 | timer notifications using signals. | |
114 | .\" FIXME . Austin bug filed, 11 Feb 09 | |
115 | .SH BUGS | |
116 | POSIX.1-2001 specifies that if the timer overrun count | |
117 | is equal to or greater than an implementation-defined maximum, | |
118 | .BR DELAYTIMER_MAX , | |
119 | then | |
120 | .BR timer_getoverrun () | |
121 | should return | |
122 | .BR DELAYTIMER_MAX . | |
123 | However, Linux does not implement this feature: instead, | |
124 | if the timer overrun value exceeds the maximum representable integer, | |
125 | the counter cycles, starting once more from low values. | |
126 | .\" Bug filed: http://bugzilla.kernel.org/show_bug.cgi?id=12665 | |
127 | .\" http://thread.gmane.org/gmane.linux.kernel/113276/ | |
d34ba634 MK |
128 | .SH EXAMPLE |
129 | See | |
130 | .BR timer_create (2). | |
c6f51a12 MK |
131 | .SH SEE ALSO |
132 | .BR clock_gettime (2), | |
133 | .BR sigaction (2), | |
134 | .BR signalfd (2), | |
135 | .BR sigwaitinfo (2), | |
136 | .BR timer_create (2), | |
137 | .BR timer_delete (2), | |
138 | .BR timer_settime (2), | |
139 | .BR signal (7), | |
140 | .BR time (7) |