]>
Commit | Line | Data |
---|---|---|
c6f51a12 MK |
1 | .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
4784c377 | 5 | .\" |
45186a5d | 6 | .TH TIMER_GETOVERRUN 2 2021-03-22 "Linux man-pages (unreleased)" |
c6f51a12 MK |
7 | .SH NAME |
8 | timer_getoverrun \- get overrun count for a POSIX per-process timer | |
67b27998 AC |
9 | .SH LIBRARY |
10 | Real-time library | |
8fc3b2cf | 11 | .RI ( librt ", " \-lrt ) |
c6f51a12 MK |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .B #include <time.h> | |
dbfe9c70 | 15 | .PP |
c6f51a12 MK |
16 | .BI "int timer_getoverrun(timer_t " timerid ); |
17 | .fi | |
dbfe9c70 | 18 | .PP |
d39ad78f | 19 | .RS -4 |
c6f51a12 MK |
20 | Feature Test Macro Requirements for glibc (see |
21 | .BR feature_test_macros (7)): | |
d39ad78f | 22 | .RE |
68e4db0a | 23 | .PP |
c6f51a12 | 24 | .BR timer_getoverrun (): |
1dd0d7b4 | 25 | .nf |
5c10d2c5 | 26 | _POSIX_C_SOURCE >= 199309L |
1dd0d7b4 | 27 | .fi |
c6f51a12 MK |
28 | .SH DESCRIPTION |
29 | .BR timer_getoverrun () | |
30 | returns the "overrun count" for the timer referred to by | |
31 | .IR timerid . | |
32 | An application can use the overrun count to accurately calculate the number | |
33 | of timer expirations that would have occurred over a given time interval. | |
34 | Timer overruns can occur both when receiving expiration notifications | |
35 | via signals | |
36 | .RB ( SIGEV_SIGNAL ), | |
37 | and via threads | |
38 | .RB ( SIGEV_THREAD ). | |
efeece04 | 39 | .PP |
c6f51a12 MK |
40 | When expiration notifications are delivered via a signal, |
41 | overruns can occur as follows. | |
42 | Regardless of whether or not a real-time signal is used for | |
43 | timer notifications, | |
44 | the system queues at most one signal per timer. | |
d8c2f63f | 45 | (This is the behavior specified by POSIX.1. |
c6f51a12 MK |
46 | The alternative, queuing one signal for each timer expiration, |
47 | could easily result in overflowing the allowed limits for | |
48 | queued signals on the system.) | |
49 | Because of system scheduling delays, | |
50 | or because the signal may be temporarily blocked, | |
51 | there can be a delay between the time when the notification | |
52 | signal is generated and the time when it | |
53 | is delivered (e.g., caught by a signal handler) or accepted (e.g., using | |
54 | .BR sigwaitinfo (2)). | |
55 | In this interval, further timer expirations may occur. | |
56 | The timer overrun count is the number of additional | |
57 | timer expirations that occurred between the time when the signal | |
58 | was generated and when it was delivered or accepted. | |
efeece04 | 59 | .PP |
c6f51a12 MK |
60 | Timer overruns can also occur when expiration notifications |
61 | are delivered via invocation of a thread, | |
62 | since there may be an arbitrary delay between an expiration of the timer | |
63 | and the invocation of the notification thread, | |
a6753832 | 64 | and in that delay interval, additional timer expirations may occur. |
c6f51a12 MK |
65 | .SH RETURN VALUE |
66 | On success, | |
67 | .BR timer_getoverrun () | |
68 | returns the overrun count of the specified timer; | |
69 | this count may be 0 if no overruns have occurred. | |
70 | On failure, \-1 is returned, and | |
71 | .I errno | |
72 | is set to indicate the error. | |
73 | .SH ERRORS | |
74 | .TP | |
75 | .B EINVAL | |
76 | .I timerid | |
77 | is not a valid timer ID. | |
78 | .SH VERSIONS | |
79 | This system call is available since Linux 2.6. | |
3113c7f3 | 80 | .SH STANDARDS |
d8c2f63f | 81 | POSIX.1-2001, POSIX.1-2008. |
c6f51a12 MK |
82 | .SH NOTES |
83 | When timer notifications are delivered via signals | |
84 | .RB ( SIGEV_SIGNAL ), | |
85 | on Linux it is also possible to obtain the overrun count via the | |
86 | .I si_overrun | |
87 | field of the | |
88 | .I siginfo_t | |
89 | structure (see | |
90 | .BR sigaction (2)). | |
91 | This allows an application to avoid the overhead of making | |
92 | a system call to obtain the overrun count, | |
d8c2f63f | 93 | but is a nonportable extension to POSIX.1. |
efeece04 | 94 | .PP |
d8c2f63f | 95 | POSIX.1 discusses timer overruns only in the context of |
c6f51a12 MK |
96 | timer notifications using signals. |
97 | .\" FIXME . Austin bug filed, 11 Feb 09 | |
cbf25811 | 98 | .\" https://www.austingroupbugs.net/view.php?id=95 |
c6f51a12 | 99 | .SH BUGS |
d8c2f63f | 100 | POSIX.1 specifies that if the timer overrun count |
c6f51a12 MK |
101 | is equal to or greater than an implementation-defined maximum, |
102 | .BR DELAYTIMER_MAX , | |
103 | then | |
104 | .BR timer_getoverrun () | |
105 | should return | |
106 | .BR DELAYTIMER_MAX . | |
0807d1b3 MK |
107 | However, before Linux 4.19, |
108 | .\" http://bugzilla.kernel.org/show_bug.cgi?id=12665 | |
c6f51a12 MK |
109 | if the timer overrun value exceeds the maximum representable integer, |
110 | the counter cycles, starting once more from low values. | |
0807d1b3 MK |
111 | Since Linux 4.19, |
112 | .\" commit 78c9c4dfbf8c04883941445a195276bb4bb92c76 | |
113 | .BR timer_getoverrun () | |
114 | returns | |
115 | .B DELAYTIMER_MAX | |
116 | (defined as | |
117 | .B INT_MAX | |
118 | in | |
119 | .IR <limits.h> ) | |
120 | in this case (and the overrun value is reset to 0). | |
a14af333 | 121 | .SH EXAMPLES |
d34ba634 MK |
122 | See |
123 | .BR timer_create (2). | |
c6f51a12 MK |
124 | .SH SEE ALSO |
125 | .BR clock_gettime (2), | |
126 | .BR sigaction (2), | |
127 | .BR signalfd (2), | |
128 | .BR sigwaitinfo (2), | |
129 | .BR timer_create (2), | |
130 | .BR timer_delete (2), | |
131 | .BR timer_settime (2), | |
132 | .BR signal (7), | |
133 | .BR time (7) |