]>
Commit | Line | Data |
---|---|---|
d268951f MK |
1 | .\" Copyright (c) 2009 Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
d268951f 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_SETTIME 2 2017-09-15 Linux "Linux Programmer's Manual" |
d268951f MK |
27 | .SH NAME |
28 | timer_settime, timer_gettime \- arm/disarm and fetch | |
29 | state of POSIX per-process timer | |
30 | .SH SYNOPSIS | |
31 | .nf | |
32 | .B #include <time.h> | |
dbfe9c70 | 33 | .PP |
d268951f MK |
34 | .BI "int timer_settime(timer_t " timerid ", int " flags , |
35 | .BI " const struct itimerspec *" new_value , | |
a5c24f8c | 36 | .BI " struct itimerspec *" old_value ); |
d268951f MK |
37 | .BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value ); |
38 | .fi | |
dbfe9c70 | 39 | .PP |
702cbe15 | 40 | Link with \fI\-lrt\fP. |
68e4db0a | 41 | .PP |
d268951f MK |
42 | .in -4n |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
68e4db0a | 46 | .PP |
d268951f MK |
47 | .BR timer_settime (), |
48 | .BR timer_gettime (): | |
98dbe7af | 49 | _POSIX_C_SOURCE\ >=\ 199309L |
d268951f MK |
50 | .SH DESCRIPTION |
51 | .BR timer_settime () | |
52 | arms or disarms the timer identified by | |
53 | .IR timerid . | |
54 | The | |
55 | .I new_value | |
e7b742f3 | 56 | argument is pointer to an |
d268951f MK |
57 | .I itimerspec |
58 | structure that specifies the new initial value and | |
59 | the new interval for the timer. | |
60 | The | |
61 | .I itimerspec | |
62 | structure is defined as follows: | |
efeece04 | 63 | .PP |
d268951f | 64 | .in +4n |
b8302363 | 65 | .EX |
d268951f MK |
66 | struct timespec { |
67 | time_t tv_sec; /* Seconds */ | |
68 | long tv_nsec; /* Nanoseconds */ | |
69 | }; | |
70 | ||
71 | struct itimerspec { | |
72 | struct timespec it_interval; /* Timer interval */ | |
73 | struct timespec it_value; /* Initial expiration */ | |
74 | }; | |
b8302363 | 75 | .EE |
d268951f | 76 | .in |
efeece04 | 77 | .PP |
d268951f MK |
78 | Each of the substructures of the |
79 | .I itimerspec | |
80 | structure is a | |
81 | .I timespec | |
82 | structure that allows a time value to be specified | |
83 | in seconds and nanoseconds. | |
84 | These time values are measured according to the clock | |
85 | that was specified when the timer was created by | |
911182a1 | 86 | .BR timer_create (2). |
efeece04 | 87 | .PP |
d268951f MK |
88 | If |
89 | .I new_value->it_value | |
ffa1b462 | 90 | specifies a nonzero value (i.e., either subfield is nonzero), then |
d268951f MK |
91 | .BR timer_settime () |
92 | arms (starts) the timer, | |
93 | setting it to initially expire at the given time. | |
94 | (If the timer was already armed, | |
95 | then the previous settings are overwritten.) | |
96 | If | |
97 | .I new_value->it_value | |
98 | specifies a zero value | |
99 | (i.e., both subfields are zero), | |
100 | then the timer is disarmed. | |
efeece04 | 101 | .PP |
d268951f MK |
102 | The |
103 | .I new_value->it_interval | |
104 | field specifies the period of the timer, in seconds and nanoseconds. | |
c7094399 | 105 | If this field is nonzero, then each time that an armed timer expires, |
d268951f MK |
106 | the timer is reloaded from the value specified in |
107 | .IR new_value->it_interval . | |
108 | If | |
109 | .I new_value->it_interval | |
142a2052 | 110 | specifies a zero value, |
d268951f MK |
111 | then the timer expires just once, at the time specified by |
112 | .IR it_value . | |
efeece04 | 113 | .PP |
d268951f MK |
114 | By default, the initial expiration time specified in |
115 | .I new_value->it_value | |
116 | is interpreted relative to the current time on the timer's | |
117 | clock at the time of the call. | |
118 | This can be modified by specifying | |
119 | .B TIMER_ABSTIME | |
120 | in | |
121 | .IR flags , | |
122 | in which case | |
123 | .I new_value->it_value | |
124 | is interpreted as an absolute value as measured on the timer's clock; | |
125 | that is, the timer will expire when the clock value reaches the | |
126 | value specified by | |
127 | .IR new_value->it_value . | |
128 | If the specified absolute time has already passed, | |
129 | then the timer expires immediately, | |
130 | and the overrun count (see | |
131 | .BR timer_getoverrun (2)) | |
132 | will be set correctly. | |
133 | .\" By experiment: the overrun count is set correctly, for CLOCK_REALTIME. | |
efeece04 | 134 | .PP |
d268951f MK |
135 | If the value of the |
136 | .B CLOCK_REALTIME | |
137 | clock is adjusted while an absolute timer based on that clock is armed, | |
138 | then the expiration of the timer will be appropriately adjusted. | |
139 | Adjustments to the | |
140 | .B CLOCK_REALTIME | |
141 | clock have no effect on relative timers based on that clock. | |
142 | .\" Similar remarks might apply with respect to process and thread CPU time | |
143 | .\" clocks, but these clocks are not currently (2.6.28) settable on Linux. | |
efeece04 | 144 | .PP |
d268951f MK |
145 | If |
146 | .I old_value | |
e7b742f3 MK |
147 | is not NULL, then it points to a buffer |
148 | that is used to return the previous interval of the timer (in | |
d268951f MK |
149 | .IR old_value->it_interval ) |
150 | and the amount of time until the timer | |
151 | would previously have next expired (in | |
152 | .IR old_value->it_value ). | |
efeece04 | 153 | .PP |
d268951f | 154 | .BR timer_gettime () |