]>
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 | .\" |
b473be57 | 26 | .TH TIMER_SETTIME 2 2012-10-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> | |
33 | ||
34 | .BI "int timer_settime(timer_t " timerid ", int " flags , | |
35 | .BI " const struct itimerspec *" new_value , | |
36 | .BI " struct itimerspec * " old_value ); | |
37 | .BI "int timer_gettime(timer_t " timerid ", struct itimerspec *" curr_value ); | |
38 | .fi | |
39 | ||
702cbe15 | 40 | Link with \fI\-lrt\fP. |
d268951f MK |
41 | .sp |
42 | .in -4n | |
43 | Feature Test Macro Requirements for glibc (see | |
44 | .BR feature_test_macros (7)): | |
45 | .in | |
46 | .sp | |
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: | |
63 | ||
64 | .in +4n | |
65 | .nf | |
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 | }; | |
75 | .fi | |
76 | .in | |
77 | ||
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 | |
0b80cf56 | 86 | .BR timer_create (2) |
d268951f MK |
87 | |
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. | |
101 | ||
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 | |
110 | specifies a zero value | |
111 | then the timer expires just once, at the time specified by | |
112 | .IR it_value . | |
113 | ||
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. | |
134 | ||
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. | |
144 | ||
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 ). | |
153 | ||
154 | .BR timer_gettime () | |