]>
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 | .\" |
4b8c67d9 | 26 | .TH TIMER_GETOVERRUN 2 2017-09-15 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> | |
dbfe9c70 | 32 | .PP |
c6f51a12 MK |
33 | .BI "int timer_getoverrun(timer_t " timerid ); |
34 | .fi | |
dbfe9c70 | 35 | .PP |
702cbe15 | 36 | Link with \fI\-lrt\fP. |
68e4db0a | 37 | .PP |
c6f51a12 MK |
38 | .in -4n |
39 | Feature Test Macro Requirements for glibc (see | |
40 | .BR feature_test_macros (7)): | |
41 | .in | |
68e4db0a | 42 | .PP |
c6f51a12 | 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 ). | |
efeece04 | 56 | .PP |
c6f51a12 MK |
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. | |
d8c2f63f | 62 | (This is the behavior specified by POSIX.1. |
c6f51a12 MK |
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. | |
efeece04 | 76 | .PP |
c6f51a12 MK |
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, | |
a6753832 | 81 | and in that delay interval, additional timer expirations may occur. |
c6f51a12 MK |
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 | |
d8c2f63f | 98 | POSIX.1-2001, POSIX.1-2008. |
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, | |
d8c2f63f | 110 | but is a nonportable extension to POSIX.1. |
efeece04 | 111 | .PP |
d8c2f63f | 112 | POSIX.1 discusses timer overruns only in the context of |
c6f51a12 MK |
113 | timer notifications using signals. |
114 | .\" FIXME . Austin bug filed, 11 Feb 09 | |
cbf25811 | 115 | .\" https://www.austingroupbugs.net/view.php?id=95 |
c6f51a12 | 116 | .SH BUGS |
d8c2f63f | 117 | POSIX.1 specifies that if the timer overrun count |
c6f51a12 MK |
118 | is equal to or greater than an implementation-defined maximum, |
119 | .BR DELAYTIMER_MAX , | |
120 | then | |
121 | .BR timer_getoverrun () | |
122 | should return | |
123 | .BR DELAYTIMER_MAX . | |
124 | However, Linux does not implement this feature: instead, | |
125 | if the timer overrun value exceeds the maximum representable integer, | |
126 | the counter cycles, starting once more from low values. | |
127 | .\" Bug filed: http://bugzilla.kernel.org/show_bug.cgi?id=12665 | |
128 | .\" http://thread.gmane.org/gmane.linux.kernel/113276/ | |
d34ba634 MK |
129 | .SH EXAMPLE |
130 | See | |
131 | .BR timer_create (2). | |
c6f51a12 MK |
132 | .SH SEE ALSO |
133 | .BR clock_gettime (2), | |
134 | .BR sigaction (2), | |
135 | .BR signalfd (2), | |
136 | .BR sigwaitinfo (2), | |
137 | .BR timer_create (2), | |
138 | .BR timer_delete (2), | |
139 | .BR timer_settime (2), | |
140 | .BR signal (7), | |
141 | .BR time (7) |