Debian Codegraph @

upstream/debian-trixie/man2/getitimer.2

raw
1 .\" Copyright 7/93 by Darren Senn <[email protected]>
2 .\" and Copyright (C) 2016, Michael Kerrisk <[email protected]>
3 .\" Based on a similar page Copyright 1992 by Rick Faith
4 .\"
5 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
6 .\" May be freely distributed and modified
7 .\" %%%LICENSE_END
8 .\"
9 .\" Modified Tue Oct 22 00:22:35 EDT 1996 by Eric S. Raymond <[email protected]>
10 .\" 2005-04-06 mtk, Matthias Lang <[email protected]>
11 .\" Noted MAX_SEC_IN_JIFFIES ceiling
12 .\"
13 .TH getitimer 2 2024-05-02 "Linux man-pages 6.9.1"
14 .SH NAME
15 getitimer, setitimer \- get or set value of an interval timer
16 .SH LIBRARY
17 Standard C library
18 .RI ( libc ", " \-lc )
19 .SH SYNOPSIS
20 .nf
21 .B #include <sys/time.h>
22 .P
23 .BI "int getitimer(int " which ", struct itimerval *" curr_value );
24 .BI "int setitimer(int " which ", const struct itimerval *restrict " new_value ,
25 .BI " struct itimerval *_Nullable restrict " old_value );
26 .fi
27 .SH DESCRIPTION
28 These system calls provide access to interval timers, that is,
29 timers that initially expire at some point in the future,
30 and (optionally) at regular intervals after that.
31 When a timer expires, a signal is generated for the calling process,
32 and the timer is reset to the specified interval
33 (if the interval is nonzero).
34 .P
35 Three types of timers\[em]specified via the
36 .I which
37 argument\[em]are provided,
38 each of which counts against a different clock and
39 generates a different signal on timer expiration:
40 .TP
41 .B ITIMER_REAL
42 This timer counts down in real (i.e., wall clock) time.
43 At each expiration, a
44 .B SIGALRM
45 signal is generated.
46 .TP
47 .B ITIMER_VIRTUAL
48 This timer counts down against the user-mode CPU time consumed by the process.
49 (The measurement includes CPU time consumed by all threads in the process.)
50 At each expiration, a
51 .B SIGVTALRM
52 signal is generated.
53 .TP
54 .B ITIMER_PROF
55 This timer counts down against the total (i.e., both user and system)
56 CPU time consumed by the process.
57 (The measurement includes CPU time consumed by all threads in the process.)
58 At each expiration, a
59 .B SIGPROF
60 signal is generated.
61 .IP
62 In conjunction with
63 .BR ITIMER_VIRTUAL ,
64 this timer can be used to profile user and system CPU time
65 consumed by the process.
66 .P
67 A process has only one of each of the three types of timers.
68 .P
69 Timer values are defined by the following structures:
70 .P
71 .in +4n
72 .EX
73 struct itimerval {
74 struct timeval it_interval; /* Interval for periodic timer */
75 struct timeval it_value; /* Time until next expiration */
76 };
77 \&
78 struct timeval {
79 time_t tv_sec; /* seconds */
80 suseconds_t tv_usec; /* microseconds */
81 };
82 .EE
83 .in
84 .\"
85 .SS getitimer()
86 The function
87 .BR getitimer ()
88 places the current value of the timer specified by
89 .I which
90 in the buffer pointed to by
91 .IR curr_value .
92 .P
93 The
94 .I it_value
95 substructure is populated with the amount of time remaining until
96 the next expiration of the specified timer.
97 This value changes as the timer counts down, and will be reset to
98 .I it_interval
99 when the timer expires.
100 If both fields of
101 .I it_value
102 are zero, then this timer is currently disarmed (inactive).
103 .P
104 The
105 .I it_interval
106 substructure is populated with the timer interval.
107 If both fields of
108 .I it_interval
109 are zero, then this is a single-shot timer (i.e., it expires just once).
110 .SS setitimer()
111 The function
112 .BR setitimer ()
113 arms or disarms the timer specified by
114 .IR which ,
115 by setting the timer to the value specified by
116 .IR new_value .
117 If
118 .I old_value
119 is non-NULL,
120 the buffer it points to is used to return the previous value of the timer
121 (i.e., the same information that is returned by
122 .BR getitimer ()).
123 .P
124 If either field in
125 .I new_value.it_value
126 is nonzero,
127 then the timer is armed to initially expire at the specified time.
128 If both fields in
129 .I new_value.it_value
130 are zero, then the timer is disarmed.
131 .P
132 The
133 .I new_value.it_interval
134 field specifies the new interval for the timer;
135 if both of its subfields are zero, the timer is single-shot.
136 .SH RETURN VALUE
137 On success, zero is returned.
138 On error, \-1 is returned, and
139 .I errno
140 is set to indicate the error.
141 .SH ERRORS
142 .TP
143 .B EFAULT
144 .IR new_value ,
145 .IR old_value ,
146 or
147 .I curr_value
148 is not valid a pointer.
149 .TP
150 .B EINVAL
151 .I which
152 is not one of
153 .BR ITIMER_REAL ,
154 .BR ITIMER_VIRTUAL ,
155 or
156 .BR ITIMER_PROF ;
157 or (since Linux 2.6.22) one of the
158 .I tv_usec
159 fields in the structure pointed to by
160 .I new_value
161 contains a value outside the range [0, 999999].
162 .SH VERSIONS
163 The standards are silent on the meaning of the call:
164 .P
165 .in +4n
166 .EX
167 setitimer(which, NULL, &old_value);
168 .EE
169 .in
170 .P
171 Many systems (Solaris, the BSDs, and perhaps others)
172 treat this as equivalent to:
173 .P
174 .in +4n
175 .EX
176 getitimer(which, &old_value);
177 .EE
178 .in
179 .P
180 In Linux, this is treated as being equivalent to a call in which the
181 .I new_value
182 fields are zero; that is, the timer is disabled.
183 .IR "Don't use this Linux misfeature" :
184 it is nonportable and unnecessary.
185 .SH STANDARDS
186 POSIX.1-2008.
187 .SH HISTORY
188 POSIX.1-2001, SVr4, 4.4BSD (this call first appeared in 4.2BSD).
189 POSIX.1-2008 marks
190 .BR getitimer ()
191 and
192 .BR setitimer ()
193 obsolete, recommending the use of the POSIX timers API
194 .RB ( timer_gettime (2),
195 .BR timer_settime (2),
196 etc.) instead.
197 .SH NOTES
198 Timers will never expire before the requested time,
199 but may expire some (short) time afterward, which depends
200 on the system timer resolution and on the system load; see
201 .BR time (7).
202 (But see BUGS below.)
203 If the timer expires while the process is active (always true for
204 .BR ITIMER_VIRTUAL ),
205 the signal will be delivered immediately when generated.
206 .P
207 A child created via
208 .BR fork (2)
209 does not inherit its parent's interval timers.
210 Interval timers are preserved across an
211 .BR execve (2).
212 .P
213 POSIX.1 leaves the
214 interaction between
215 .BR setitimer ()
216 and the three interfaces
217 .BR alarm (2),
218 .BR sleep (3),
219 and
220 .BR usleep (3)
221 unspecified.
222 .SH BUGS
223 The generation and delivery of a signal are distinct, and
224 only one instance of each of the signals listed above may be pending
225 for a process.
226 Under very heavy loading, an
227 .B ITIMER_REAL
228 timer may expire before the signal from a previous expiration
229 has been delivered.
230 The second signal in such an event will be lost.
231 .P
232 Before Linux 2.6.16, timer values are represented in jiffies.
233 If a request is made set a timer with a value whose jiffies
234 representation exceeds
235 .B MAX_SEC_IN_JIFFIES
236 (defined in
237 .IR include/linux/jiffies.h ),
238 then the timer is silently truncated to this ceiling value.
239 On Linux/i386 (where, since Linux 2.6.13,
240 the default jiffy is 0.004 seconds),
241 this means that the ceiling value for a timer is
242 approximately 99.42 days.
243 Since Linux 2.6.16,
244 the kernel uses a different internal representation for times,
245 and this ceiling is removed.
246 .P
247 On certain systems (including i386),
248 Linux kernels before Linux 2.6.12 have a bug which will produce
249 premature timer expirations of up to one jiffy under some circumstances.
250 This bug is fixed in Linux 2.6.12.
251 .\" 4 Jul 2005: It looks like this bug may remain in Linux 2.4.x.
252 .\" http://lkml.org/lkml/2005/7/1/165
253 .P
254 POSIX.1-2001 says that
255 .BR setitimer ()
256 should fail if a
257 .I tv_usec
258 value is specified that is outside of the range [0, 999999].
259 However, up to and including Linux 2.6.21,
260 Linux does not give an error, but instead silently
261 adjusts the corresponding seconds value for the timer.
262 From Linux 2.6.22 onward,
263 this nonconformance has been repaired:
264 an improper
265 .I tv_usec
266 value results in an
267 .B EINVAL
268 error.
269 .\" Bugzilla report 25 Apr 2006:
270 .\" http://bugzilla.kernel.org/show_bug.cgi?id=6443
271 .\" "setitimer() should reject noncanonical arguments"
272 .SH SEE ALSO
273 .BR gettimeofday (2),
274 .BR sigaction (2),
275 .BR signal (2),
276 .BR timer_create (2),
277 .BR timerfd_create (2),
278 .BR time (7)