Debian Codegraph @

upstream/debian-unstable/man3/Time::HiRes.3perl

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