Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Time::HiRes.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Time::HiRes 3pm"
61 .TH Time::HiRes 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Time::HiRes \- High resolution alarm, sleep, gettimeofday, interval timers
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 3
71 \& use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
72 \& clock_gettime clock_getres clock_nanosleep clock
73 \& stat lstat utime);
74 \&
75 \& usleep ($microseconds);
76 \& nanosleep ($nanoseconds);
77 \&
78 \& ualarm ($microseconds);
79 \& ualarm ($microseconds, $interval_microseconds);
80 \&
81 \& $t0 = [gettimeofday];
82 \& ($seconds, $microseconds) = gettimeofday;
83 \&
84 \& $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
85 \& $elapsed = tv_interval ( $t0, [gettimeofday]);
86 \& $elapsed = tv_interval ( $t0 );
87 \&
88 \& use Time::HiRes qw ( time alarm sleep );
89 \&
90 \& $now_fractions = time;
91 \& sleep ($floating_seconds);
92 \& alarm ($floating_seconds);
93 \& alarm ($floating_seconds, $floating_interval);
94 \&
95 \& use Time::HiRes qw( setitimer getitimer );
96 \&
97 \& setitimer ($which, $floating_seconds, $floating_interval );
98 \& getitimer ($which);
99 \&
100 \& use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
101 \& CLOCK_REALTIME ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF
102 \& ITIMER_REALPROF );
103 \&
104 \& $realtime = clock_gettime(CLOCK_REALTIME);
105 \& $resolution = clock_getres(CLOCK_REALTIME);
106 \&
107 \& clock_nanosleep(CLOCK_REALTIME, 1.5e9);
108 \& clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);
109 \&
110 \& my $ticktock = clock();
111 \&
112 \& use Time::HiRes qw( stat lstat );
113 \&
114 \& my @stat = stat("file");
115 \& my @stat = stat(FH);
116 \& my @stat = lstat("file");
117 \&
118 \& use Time::HiRes qw( utime );
119 \& utime $floating_seconds, $floating_seconds, file...;
120 .Ve
121 .SH DESCRIPTION
122 .IX Header "DESCRIPTION"
123 The \f(CW\*(C`Time::HiRes\*(C'\fR module implements a Perl interface to the
124 \&\f(CW\*(C`usleep\*(C'\fR, \f(CW\*(C`nanosleep\*(C'\fR, \f(CW\*(C`ualarm\*(C'\fR, \f(CW\*(C`gettimeofday\*(C'\fR, and
125 \&\f(CW\*(C`setitimer\*(C'\fR/\f(CW\*(C`getitimer\*(C'\fR system calls, in other words, high
126 resolution time and timers. See the "EXAMPLES" section below and the
127 test scripts for usage; see your system documentation for the
128 description of the underlying \f(CW\*(C`nanosleep\*(C'\fR or \f(CW\*(C`usleep\*(C'\fR, \f(CW\*(C`ualarm\*(C'\fR,
129 \&\f(CW\*(C`gettimeofday\*(C'\fR, and \f(CW\*(C`setitimer\*(C'\fR/\f(CW\*(C`getitimer\*(C'\fR calls.
130 .PP
131 If your system lacks \f(CWgettimeofday()\fR or an emulation of it you don\*(Aqt
132 get \f(CWgettimeofday()\fR or the one\-argument form of \f(CWtv_interval()\fR.
133 If your system lacks all of \f(CWnanosleep()\fR, \f(CWusleep()\fR,
134 \&\f(CWselect()\fR, and \f(CW\*(C`poll\*(C'\fR, you don\*(Aqt get \f(CWTime::HiRes::usleep()\fR,
135 \&\f(CWTime::HiRes::nanosleep()\fR, or \f(CWTime::HiRes::sleep()\fR.
136 If your system lacks both \f(CWualarm()\fR and \f(CWsetitimer()\fR you don\*(Aqt get
137 \&\f(CWTime::HiRes::ualarm()\fR or \f(CWTime::HiRes::alarm()\fR.
138 .PP
139 If you try to import an unimplemented function in the \f(CW\*(C`use\*(C'\fR statement
140 it will fail at compile time.
141 .PP
142 If your subsecond sleeping is implemented with \f(CWnanosleep()\fR instead
143 of \f(CWusleep()\fR, you can mix subsecond sleeping with signals since
144 \&\f(CWnanosleep()\fR does not use signals. This, however, is not portable,
145 and you should first check for the truth value of
146 \&\f(CW&Time::HiRes::d_nanosleep\fR to see whether you have nanosleep, and
147 then carefully read your \f(CWnanosleep()\fR C API documentation for any
148 peculiarities.
149 .PP
150 If you are using \f(CW\*(C`nanosleep\*(C'\fR for something else than mixing sleeping
151 with signals, give some thought to whether Perl is the tool you should
152 be using for work requiring nanosecond accuracies.
153 .PP
154 Remember that unless you are working on a \fIhard realtime\fR system,
155 any clocks and timers will be imprecise, especially so if you are working
156 in a pre\-emptive multiuser system. Understand the difference between
157 \&\fIwallclock time\fR and process time (in UNIX\-like systems the sum of
158 \&\fIuser\fR and \fIsystem\fR times). Any attempt to sleep for X seconds will
159 most probably end up sleeping \fBmore\fR than that, but don\*(Aqt be surprised
160 if you end up sleeping slightly \fBless\fR.
161 .PP
162 The following functions can be imported from this module.
163 No functions are exported by default.
164 .IP "gettimeofday ()" 4
165 .IX Item "gettimeofday ()"
166 In array context returns a two\-element array with the seconds and
167 microseconds since the epoch. In scalar context returns floating
168 seconds like \f(CWTime::HiRes::time()\fR (see below).
169 .ie n .IP "usleep ( $useconds )" 4
170 .el .IP "usleep ( \f(CW$useconds\fR )" 4
171 .IX Item "usleep ( $useconds )"
172 Sleeps for the number of microseconds (millionths of a second)
173 specified. Returns the number of microseconds actually slept.
174 Can sleep for more than one second, unlike the \f(CW\*(C`usleep\*(C'\fR system call.
175 Can also sleep for zero seconds, which often works like a \fIthread yield\fR.
176 See also \f(CWTime::HiRes::sleep()\fR, and
177 \&\f(CWclock_nanosleep()\fR.
178 .Sp
179 Do not expect \fBusleep()\fR to be exact down to one microsecond.
180 .ie n .IP "nanosleep ( $nanoseconds )" 4
181 .el .IP "nanosleep ( \f(CW$nanoseconds\fR )" 4
182 .IX Item "nanosleep ( $nanoseconds )"
183 Sleeps for the number of nanoseconds (1e9ths of a second) specified.
184 Returns the number of nanoseconds actually slept (accurate only to
185 microseconds, the nearest thousand of them). Can sleep for more than
186 one second. Can also sleep for zero seconds, which often works like
187 a \fIthread yield\fR. See also
188 \&\f(CWTime::HiRes::sleep()\fR,
189 \&\f(CWTime::HiRes::usleep()\fR, and
190 \&\f(CWclock_nanosleep()\fR.
191 .Sp
192 Do not expect \fBnanosleep()\fR to be exact down to one nanosecond.
193 Getting even accuracy of one thousand nanoseconds is good.
194 .ie n .IP "ualarm ( $useconds [, $interval_useconds ] )" 4
195 .el .IP "ualarm ( \f(CW$useconds\fR [, \f(CW$interval_useconds\fR ] )" 4
196 .IX Item "ualarm ( $useconds [, $interval_useconds ] )"
197 Issues a \f(CW\*(C`ualarm\*(C'\fR call; the \f(CW$interval_useconds\fR is optional and
198 will be zero if unspecified, resulting in \f(CW\*(C`alarm\*(C'\fR\-like behaviour.
199 .Sp
200 Returns the remaining time in the alarm in microseconds, or \f(CW\*(C`undef\*(C'\fR
201 if an error occurred.
202 .Sp
203 \&\fBualarm\fR\|(0) will cancel an outstanding \fBualarm()\fR.
204 .Sp
205 Note that the interaction between alarms and sleeps is unspecified.
206 .IP tv_interval 4
207 .IX Item "tv_interval"
208 tv_interval ( \f(CW$ref_to_gettimeofday\fR [, \f(CW$ref_to_later_gettimeofday\fR] )
209 .Sp
210 Returns the floating seconds between the two times, which should have
211 been returned by \f(CWgettimeofday()\fR. If the second argument is omitted,
212 then the current time is used.
213 .IP "time ()" 4
214 .IX Item "time ()"
215 Returns a floating seconds since the epoch. This function can be
216 imported, resulting in a nice drop\-in replacement for the \f(CW\*(C`time\*(C'\fR
217 provided with core Perl; see the "EXAMPLES" below.
218 .Sp
219 \&\fBNOTE 1\fR: This higher resolution timer can return values either less
220 or more than the core \f(CWtime()\fR, depending on whether your platform
221 rounds the higher resolution timer values up, down, or to the nearest second
222 to get the core \f(CWtime()\fR, but naturally the difference should be never
223 more than half a second. See also "clock_getres", if available
224 in your system.
225 .Sp
226 \&\fBNOTE 2\fR: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
227 the \f(CWtime()\fR seconds since epoch rolled over to 1_000_000_000, the
228 default floating point format of Perl and the seconds since epoch have
229 conspired to produce an apparent bug: if you print the value of
230 \&\f(CWTime::HiRes::time()\fR you seem to be getting only five decimals, not
231 six as promised (microseconds). Not to worry, the microseconds are
232 there (assuming your platform supports such granularity in the first
233 place). What is going on is that the default floating point format of
234 Perl only outputs 15 digits. In this case that means ten digits
235 before the decimal separator and five after. To see the microseconds
236 you can use either \f(CW\*(C`printf\*(C'\fR/\f(CW\*(C`sprintf\*(C'\fR with \f(CW"%.6f"\fR, or the
237 \&\f(CWgettimeofday()\fR function in list context, which will give you the
238 seconds and microseconds as two separate values.
239 .ie n .IP "sleep ( $floating_seconds )" 4
240 .el .IP "sleep ( \f(CW$floating_seconds\fR )" 4
241 .IX Item "sleep ( $floating_seconds )"
242 Sleeps for the specified amount of seconds. Returns the number of
243 seconds actually slept (a floating point value). This function can
244 be imported, resulting in a nice drop\-in replacement for the \f(CW\*(C`sleep\*(C'\fR
245 provided with perl, see the "EXAMPLES" below.
246 .Sp
247 Note that the interaction between alarms and sleeps is unspecified.
248 .ie n .IP "alarm ( $floating_seconds [, $interval_floating_seconds ] )" 4
249 .el .IP "alarm ( \f(CW$floating_seconds\fR [, \f(CW$interval_floating_seconds\fR ] )" 4
250 .IX Item "alarm ( $floating_seconds [, $interval_floating_seconds ] )"
251 The \f(CW\*(C`SIGALRM\*(C'\fR signal is sent after the specified number of seconds.
252 Implemented using \f(CWsetitimer()\fR if available, \f(CWualarm()\fR if not.
253 The \f(CW$interval_floating_seconds\fR argument is optional and will be
254 zero if unspecified, resulting in \f(CWalarm()\fR\-like behaviour. This
255 function can be imported, resulting in a nice drop\-in replacement for
256 the \f(CW\*(C`alarm\*(C'\fR provided with perl, see the "EXAMPLES" below.
257 .Sp
258 Returns the remaining time in the alarm in seconds, or \f(CW\*(C`undef\*(C'\fR
259 if an error occurred.
260 .Sp
261 \&\fBNOTE 1\fR: With some combinations of operating systems and Perl
262 releases \f(CW\*(C`SIGALRM\*(C'\fR restarts \f(CWselect()\fR, instead of interrupting it.
263 This means that an \f(CWalarm()\fR followed by a \f(CWselect()\fR may together
264 take the sum of the times specified for the \f(CWalarm()\fR and the
265 \&\f(CWselect()\fR, not just the time of the \f(CWalarm()\fR.
266 .Sp
267 Note that the interaction between alarms and sleeps is unspecified.
268 .ie n .IP "setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )" 4
269 .el .IP "setitimer ( \f(CW$which\fR, \f(CW$floating_seconds\fR [, \f(CW$interval_floating_seconds\fR ] )" 4
270 .IX Item "setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )"
271 Start up an interval timer: after a certain time, a signal ($which) arrives,
272 and more signals may keep arriving at certain intervals. To disable
273 an "itimer", use \f(CW$floating_seconds\fR of zero. If the
274 \&\f(CW$interval_floating_seconds\fR is set to zero (or unspecified), the
275 timer is disabled \fBafter\fR the next delivered signal.
276 .Sp
277 Use of interval timers may interfere with \f(CWalarm()\fR, \f(CWsleep()\fR,
278 and \f(CWusleep()\fR. In standard\-speak the "interaction is unspecified",
279 which means that \fIanything\fR may happen: it may work, it may not.
280 .Sp
281 In scalar context, the remaining time in the timer is returned.
282 .Sp
283 In list context, both the remaining time and the interval are returned.
284 .Sp
285 There are usually three or four interval timers (signals) available: the
286 \&\f(CW$which\fR can be \f(CW\*(C`ITIMER_REAL\*(C'\fR, \f(CW\*(C`ITIMER_VIRTUAL\*(C'\fR, \f(CW\*(C`ITIMER_PROF\*(C'\fR, or
287 \&\f(CW\*(C`ITIMER_REALPROF\*(C'\fR. Note that which ones are available depends: true
288 UNIX platforms usually have the first three, but only Solaris seems to
289 have \f(CW\*(C`ITIMER_REALPROF\*(C'\fR (which is used to profile multithreaded programs).
290 Win32 unfortunately does not have interval timers.
291 .Sp
292 \&\f(CW\*(C`ITIMER_REAL\*(C'\fR results in \f(CWalarm()\fR\-like behaviour. Time is counted in
293 \&\fIreal time\fR; that is, wallclock time. \f(CW\*(C`SIGALRM\*(C'\fR is delivered when
294 the timer expires.
295 .Sp
296 \&\f(CW\*(C`ITIMER_VIRTUAL\*(C'\fR counts time in (process) \fIvirtual time\fR; that is,
297 only when the process is running. In multiprocessor/user/CPU systems
298 this may be more or less than real or wallclock time. (This time is
299 also known as the \fIuser time\fR.) \f(CW\*(C`SIGVTALRM\*(C'\fR is delivered when the
300 timer expires.
301 .Sp
302 \&\f(CW\*(C`ITIMER_PROF\*(C'\fR counts time when either the process virtual time or when
303 the operating system is running on behalf of the process (such as I/O).
304 (This time is also known as the \fIsystem time\fR.) (The sum of user
305 time and system time is known as the \fICPU time\fR.) \f(CW\*(C`SIGPROF\*(C'\fR is
306 delivered when the timer expires. \f(CW\*(C`SIGPROF\*(C'\fR can interrupt system calls.
307 .Sp
308 The semantics of interval timers for multithreaded programs are
309 system\-specific, and some systems may support additional interval
310 timers. For example, it is unspecified which thread gets the signals.
311 See your \f(CW\*(C`\fR\f(CBsetitimer\fR\f(CW\|(2)\*(C'\fR documentation.
312 .ie n .IP "getitimer ( $which )" 4
313 .el .IP "getitimer ( \f(CW$which\fR )" 4
314 .IX Item "getitimer ( $which )"
315 Return the remaining time in the interval timer specified by \f(CW$which\fR.
316 .Sp
317 In scalar context, the remaining time is returned.
318 .Sp
319 In list context, both the remaining time and the interval are returned.
320 The interval is always what you put in using \f(CWsetitimer()\fR.
321 .ie n .IP "clock_gettime ( $which )" 4
322 .el .IP "clock_gettime ( \f(CW$which\fR )" 4
323 .IX Item "clock_gettime ( $which )"
324 Return as seconds the current value of the POSIX high resolution timer
325 specified by \f(CW$which\fR. All implementations that support POSIX high
326 resolution timers are supposed to support at least the \f(CW$which\fR value
327 of \f(CW\*(C`CLOCK_REALTIME\*(C'\fR, which is supposed to return results close to the
328 results of \f(CW\*(C`gettimeofday\*(C'\fR, or the number of seconds since 00:00:00:00
329 January 1, 1970 Greenwich Mean Time (GMT). Do not assume that
330 CLOCK_REALTIME is zero, it might be one, or something else.
331 Another potentially useful (but not available everywhere) value is
332 \&\f(CW\*(C`CLOCK_MONOTONIC\*(C'\fR, which guarantees a monotonically increasing time
333 value (unlike \fBtime()\fR or \fBgettimeofday()\fR, which can be adjusted).
334 See your system documentation for other possibly supported values.
335 .ie n .IP "clock_getres ( $which )" 4
336 .el .IP "clock_getres ( \f(CW$which\fR )" 4
337 .IX Item "clock_getres ( $which )"
338 Return as seconds the resolution of the POSIX high resolution timer
339 specified by \f(CW$which\fR. All implementations that support POSIX high
340 resolution timers are supposed to support at least the \f(CW$which\fR value
341 of \f(CW\*(C`CLOCK_REALTIME\*(C'\fR, see "clock_gettime".
342 .Sp
343 \&\fBNOTE\fR: the resolution returned may be highly optimistic. Even if
344 the resolution is high (a small number), all it means is that you\*(Aqll
345 be able to specify the arguments to \fBclock_gettime()\fR and \fBclock_nanosleep()\fR
346 with that resolution. The system might not actually be able to measure
347 events at that resolution, and the various overheads and the overall system
348 load are certain to affect any timings.
349 .ie n .IP "clock_nanosleep ( $which, $nanoseconds, $flags = 0)" 4
350 .el .IP "clock_nanosleep ( \f(CW$which\fR, \f(CW$nanoseconds\fR, \f(CW$flags\fR = 0)" 4
351 .IX Item "clock_nanosleep ( $which, $nanoseconds, $flags = 0)"
352 Sleeps for the number of nanoseconds (1e9ths of a second) specified.
353 Returns the number of nanoseconds actually slept. The \f(CW$which\fR is the
354 "clock id", as with \fBclock_gettime()\fR and \fBclock_getres()\fR. The flags
355 default to zero but \f(CW\*(C`TIMER_ABSTIME\*(C'\fR can specified (must be exported
356 explicitly) which means that \f(CW$nanoseconds\fR is not a time interval
357 (as is the default) but instead an absolute time. Can sleep for more
358 than one second. Can also sleep for zero seconds, which often works
359 like a \fIthread yield\fR. See also
360 \&\f(CWTime::HiRes::sleep()\fR,
361 \&\f(CWTime::HiRes::usleep()\fR, and
362 \&\f(CWTime::HiRes::nanosleep()\fR.
363 .Sp
364 Do not expect \fBclock_nanosleep()\fR to be exact down to one nanosecond.
365 Getting even accuracy of one thousand nanoseconds is good.
366 .IP \fBclock()\fR 4
367 .IX Item "clock()"
368 Return as seconds the \fIprocess time\fR (user + system time) spent by
369 the process since the first call to \fBclock()\fR (the definition is \fBnot\fR
370 "since the start of the process", though if you are lucky these times
371 may be quite close to each other, depending on the system). What this
372 means is that you probably need to store the result of your first call
373 to \fBclock()\fR, and subtract that value from the following results of \fBclock()\fR.
374 .Sp
375 The time returned also includes the process times of the terminated
376 child processes for which \fBwait()\fR has been executed. This value is
377 somewhat like the second value returned by the \fBtimes()\fR of core Perl,
378 but not necessarily identical. Note that due to backward
379 compatibility limitations the returned value may wrap around at about
380 2147 seconds or at about 36 minutes.
381 .IP stat 4
382 .IX Item "stat"
383 .PD 0
384 .IP "stat FH" 4
385 .IX Item "stat FH"
386 .IP "stat EXPR" 4
387 .IX Item "stat EXPR"
388 .IP lstat 4
389 .IX Item "lstat"
390 .IP "lstat FH" 4
391 .IX Item "lstat FH"
392 .IP "lstat EXPR" 4
393 .IX Item "lstat EXPR"
394 .PD
395 As "stat" in perlfunc or "lstat" in perlfunc
396 but with the access/modify/change file timestamps
397 in subsecond resolution, if the operating system and the filesystem
398 both support such timestamps. To override the standard \fBstat()\fR:
399 .Sp
400 .Vb 1
401 \& use Time::HiRes qw(stat);
402 .Ve
403 .Sp
404 Test for the value of &Time::HiRes::d_hires_stat to find out whether
405 the operating system supports subsecond file timestamps: a value
406 larger than zero means yes. There are unfortunately no easy
407 ways to find out whether the filesystem supports such timestamps.
408 UNIX filesystems often do; NTFS does; FAT doesn\*(Aqt (FAT timestamp
409 granularity is \fBtwo\fR seconds).
410 .Sp
411 A zero return value of &Time::HiRes::d_hires_stat means that
412 Time::HiRes::stat is a no\-op passthrough for \fBCORE::stat()\fR
413 (and likewise for lstat),
414 and therefore the timestamps will stay integers. The same
415 thing will happen if the filesystem does not do subsecond timestamps,
416 even if the &Time::HiRes::d_hires_stat is non\-zero.
417 .Sp
418 In any case do not expect nanosecond resolution, or even a microsecond
419 resolution. Also note that the modify/access timestamps might have
420 different resolutions, and that they need not be synchronized, e.g.
421 if the operations are
422 .Sp
423 .Vb 4
424 \& write
425 \& stat # t1
426 \& read
427 \& stat # t2
428 .Ve
429 .Sp
430 the access time stamp from t2 need not be greater\-than the modify
431 time stamp from t1: it may be equal or \fIless\fR.
432 .IP "utime LIST" 4
433 .IX Item "utime LIST"
434 As "utime" in perlfunc
435 but with the ability to set the access/modify file timestamps
436 in subsecond resolution, if the operating system and the filesystem,
437 and the mount options of the filesystem, all support such timestamps.
438 .Sp
439 To override the standard \fButime()\fR:
440 .Sp
441 .Vb 1
442 \& use Time::HiRes qw(utime);
443 .Ve
444 .Sp
445 Test for the value of &Time::HiRes::d_hires_utime to find out whether
446 the operating system supports setting subsecond file timestamps.
447 .Sp
448 As with \fBCORE::utime()\fR, passing undef as both the atime and mtime will
449 call the syscall with a NULL argument.
450 .Sp
451 The actual achievable subsecond resolution depends on the combination
452 of the operating system and the filesystem.
453 .Sp
454 Modifying the timestamps may not be possible at all: for example, the
455 \&\f(CW\*(C`noatime\*(C'\fR filesystem mount option may prohibit you from changing the
456 access time timestamp.
457 .Sp
458 Returns the number of files successfully changed.
459 .SH EXAMPLES
460 .IX Header "EXAMPLES"
461 .Vb 1
462 \& use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
463 \&
464 \& $microseconds = 750_000;
465 \& usleep($microseconds);
466 \&
467 \& # signal alarm in 2.5s & every .1s thereafter
468 \& ualarm(2_500_000, 100_000);
469 \& # cancel that ualarm
470 \& ualarm(0);
471 \&
472 \& # get seconds and microseconds since the epoch
473 \& ($s, $usec) = gettimeofday();
474 \&
475 \& # measure elapsed time
476 \& # (could also do by subtracting 2 gettimeofday return values)
477 \& $t0 = [gettimeofday];
478 \& # do bunch of stuff here
479 \& $t1 = [gettimeofday];
480 \& # do more stuff here
481 \& $t0_t1 = tv_interval $t0, $t1;
482 \&
483 \& $elapsed = tv_interval ($t0, [gettimeofday]);
484 \& $elapsed = tv_interval ($t0); # equivalent code
485 \&
486 \& #
487 \& # replacements for time, alarm and sleep that know about
488 \& # floating seconds
489 \& #
490 \& use Time::HiRes;
491 \& $now_fractions = Time::HiRes::time;
492 \& Time::HiRes::sleep (2.5);
493 \& Time::HiRes::alarm (10.6666666);
494 \&
495 \& use Time::HiRes qw ( time alarm sleep );
496 \& $now_fractions = time;
497 \& sleep (2.5);
498 \& alarm (10.6666666);
499 \&
500 \& # Arm an interval timer to go off first at 10 seconds and
501 \& # after that every 2.5 seconds, in process virtual time
502 \&
503 \& use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
504 \&
505 \& $SIG{VTALRM} = sub { print time, "\en" };
506 \& setitimer(ITIMER_VIRTUAL, 10, 2.5);
507 \&
508 \& use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
509 \& # Read the POSIX high resolution timer.
510 \& my $high = clock_gettime(CLOCK_REALTIME);
511 \& # But how accurate we can be, really?
512 \& my $reso = clock_getres(CLOCK_REALTIME);
513 \&
514 \& use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
515 \& clock_nanosleep(CLOCK_REALTIME, 1e6);
516 \& clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);
517 \&
518 \& use Time::HiRes qw( clock );
519 \& my $clock0 = clock();
520 \& ... # Do something.
521 \& my $clock1 = clock();
522 \& my $clockd = $clock1 \- $clock0;
523 \&
524 \& use Time::HiRes qw( stat );
525 \& my ($atime, $mtime, $ctime) = (stat("istics"))[8, 9, 10];
526 .Ve
527 .SH "C API"
528 .IX Header "C API"
529 In addition to the perl API described above, a C API is available for
530 extension writers. The following C functions are available in the
531 modglobal hash:
532 .PP
533 .Vb 4
534 \& name C prototype
535 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
536 \& Time::NVtime NV (*)()
537 \& Time::U2time void (*)(pTHX_ UV ret[2])
538 .Ve
539 .PP
540 Both functions return equivalent information (like \f(CW\*(C`gettimeofday\*(C'\fR)
541 but with different representations. The names \f(CW\*(C`NVtime\*(C'\fR and \f(CW\*(C`U2time\*(C'\fR
542 were selected mainly because they are operating system independent.
543 (\f(CW\*(C`gettimeofday\*(C'\fR is Unix\-centric, though some platforms like Win32 and
544 VMS have emulations for it.)
545 .PP
546 Here is an example of using \f(CW\*(C`NVtime\*(C'\fR from C:
547 .PP
548 .Vb 6
549 \& NV (*myNVtime)(); /* Returns \-1 on failure. */
550 \& SV **svp = hv_fetchs(PL_modglobal, "Time::NVtime", 0);
551 \& if (!svp) croak("Time::HiRes is required");
552 \& if (!SvIOK(*svp)) croak("Time::NVtime isn\*(Aqt a function pointer");
553 \& myNVtime = INT2PTR(NV(*)(), SvIV(*svp));
554 \& printf("The current time is: %" NVff "\en", (*myNVtime)());
555 .Ve
556 .SH DIAGNOSTICS
557 .IX Header "DIAGNOSTICS"
558 .SS "useconds or interval more than ..."
559 .IX Subsection "useconds or interval more than ..."
560 In \fBualarm()\fR you tried to use number of microseconds or interval (also
561 in microseconds) more than 1_000_000 and \fBsetitimer()\fR is not available
562 in your system to emulate that case.
563 .SS "negative time not invented yet"
564 .IX Subsection "negative time not invented yet"
565 You tried to use a negative time argument.
566 .SS "internal error: useconds < 0 (unsigned ... signed ...)"
567 .IX Subsection "internal error: useconds < 0 (unsigned ... signed ...)"
568 Something went horribly wrong\-\- the number of microseconds that cannot
569 become negative just became negative. Maybe your compiler is broken?
570 .SS "useconds or uinterval equal to or more than 1000000"
571 .IX Subsection "useconds or uinterval equal to or more than 1000000"
572 In some platforms it is not possible to get an alarm with subsecond
573 resolution and later than one second.
574 .SS "unimplemented in this platform"
575 .IX Subsection "unimplemented in this platform"
576 Some calls simply aren\*(Aqt available, real or emulated, on every platform.
577 .SH CAVEATS
578 .IX Header "CAVEATS"
579 Notice that the core \f(CWtime()\fR maybe rounding rather than truncating.
580 What this means is that the core \f(CWtime()\fR may be reporting the time
581 as one second later than \f(CWgettimeofday()\fR and \f(CWTime::HiRes::time()\fR.
582 .PP
583 Adjusting the system clock (either manually or by services like ntp)
584 may cause problems, especially for long running programs that assume
585 a monotonously increasing time (note that all platforms do not adjust
586 time as gracefully as UNIX ntp does). For example in Win32 (and derived
587 platforms like Cygwin and MinGW) the \fBTime::HiRes::time()\fR may temporarily
588 drift off from the system clock (and the original \fBtime()\fR) by up to 0.5
589 seconds. Time::HiRes will notice this eventually and recalibrate.
590 Note that since Time::HiRes 1.77 the clock_gettime(CLOCK_MONOTONIC)
591 might help in this (in case your system supports CLOCK_MONOTONIC).
592 .PP
593 Some systems have APIs but not implementations: for example QNX and Haiku
594 have the interval timer APIs but not the functionality.
595 .PP
596 In pre\-Sierra macOS (pre\-10.12, OS X) \fBclock_getres()\fR, \fBclock_gettime()\fR
597 and \fBclock_nanosleep()\fR are emulated using the Mach timers; as a side
598 effect of being emulated the CLOCK_REALTIME and CLOCK_MONOTONIC are
599 the same timer.
600 .PP
601 gnukfreebsd seems to have non\-functional \fBfutimens()\fR and \fButimensat()\fR
602 (at least as of 10.1): therefore the hires \fButime()\fR does not work.
603 .SH "SEE ALSO"
604 .IX Header "SEE ALSO"
605 Perl modules BSD::Resource, Time::TAI64.
606 .PP
607 Your system documentation for \f(CW\*(C`\fR\f(CBclock\fR\f(CW\|(3)\*(C'\fR, \f(CW\*(C`\fR\f(CBclock_gettime\fR\f(CW\|(2)\*(C'\fR,
608 \&\f(CW\*(C`\fR\f(CBclock_getres\fR\f(CW\|(3)\*(C'\fR, \f(CW\*(C`\fR\f(CBclock_nanosleep\fR\f(CW\|(3)\*(C'\fR, \f(CW\*(C`\fR\f(CBclock_settime\fR\f(CW\|(2)\*(C'\fR,
609 \&\f(CW\*(C`\fR\f(CBgetitimer\fR\f(CW\|(2)\*(C'\fR, \f(CW\*(C`\fR\f(CBgettimeofday\fR\f(CW\|(2)\*(C'\fR, \f(CW\*(C`\fR\f(CBsetitimer\fR\f(CW\|(2)\*(C'\fR, \f(CW\*(C`\fR\f(CBsleep\fR\f(CW\|(3)\*(C'\fR,
610 \&\f(CW\*(C`\fR\f(CBstat\fR\f(CW\|(2)\*(C'\fR, \f(CW\*(C`\fR\f(CBualarm\fR\f(CW\|(3)\*(C'\fR.
611 .SH AUTHORS
612 .IX Header "AUTHORS"
613 D. Wegscheid <[email protected]>
614 R. Schertler <[email protected]>
615 J. Hietaniemi <[email protected]>
616 G. Aas <[email protected]>
617 .SH "COPYRIGHT AND LICENSE"
618 .IX Header "COPYRIGHT AND LICENSE"
619 Copyright (c) 1996\-2002 Douglas E. Wegscheid. All rights reserved.
620 .PP
621 Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Jarkko Hietaniemi.
622 All rights reserved.
623 .PP
624 Copyright (C) 2011, 2012, 2013 Andrew Main (Zefram) <[email protected]>
625 .PP
626 This program is free software; you can redistribute it and/or modify
627 it under the same terms as Perl itself.