1HiRes(3)              User Contributed Perl Documentation             HiRes(3)
2
3
4

NAME

6       Time::HiRes - High resolution alarm, sleep, gettimeofday, interval
7       timers
8

SYNOPSIS

10         use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
11                             clock_gettime clock_getres clock_nanosleep clock
12                             stat lstat utime);
13
14         usleep ($microseconds);
15         nanosleep ($nanoseconds);
16
17         ualarm ($microseconds);
18         ualarm ($microseconds, $interval_microseconds);
19
20         $t0 = [gettimeofday];
21         ($seconds, $microseconds) = gettimeofday;
22
23         $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
24         $elapsed = tv_interval ( $t0, [gettimeofday]);
25         $elapsed = tv_interval ( $t0 );
26
27         use Time::HiRes qw ( time alarm sleep );
28
29         $now_fractions = time;
30         sleep ($floating_seconds);
31         alarm ($floating_seconds);
32         alarm ($floating_seconds, $floating_interval);
33
34         use Time::HiRes qw( setitimer getitimer );
35
36         setitimer ($which, $floating_seconds, $floating_interval );
37         getitimer ($which);
38
39         use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
40                             ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF
41                             ITIMER_REALPROF );
42
43         $realtime   = clock_gettime(CLOCK_REALTIME);
44         $resolution = clock_getres(CLOCK_REALTIME);
45
46         clock_nanosleep(CLOCK_REALTIME, 1.5e9);
47         clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);
48
49         my $ticktock = clock();
50
51         use Time::HiRes qw( stat lstat );
52
53         my @stat = stat("file");
54         my @stat = stat(FH);
55         my @stat = lstat("file");
56
57         use Time::HiRes qw( utime );
58         utime $floating_seconds, $floating_seconds, file...;
59

DESCRIPTION

61       The "Time::HiRes" module implements a Perl interface to the "usleep",
62       "nanosleep", "ualarm", "gettimeofday", and "setitimer"/"getitimer"
63       system calls, in other words, high resolution time and timers. See the
64       "EXAMPLES" section below and the test scripts for usage; see your
65       system documentation for the description of the underlying "nanosleep"
66       or "usleep", "ualarm", "gettimeofday", and "setitimer"/"getitimer"
67       calls.
68
69       If your system lacks "gettimeofday()" or an emulation of it you don't
70       get "gettimeofday()" or the one-argument form of "tv_interval()".  If
71       your system lacks all of "nanosleep()", "usleep()", "select()", and
72       "poll", you don't get "Time::HiRes::usleep()",
73       "Time::HiRes::nanosleep()", or "Time::HiRes::sleep()".  If your system
74       lacks both "ualarm()" and "setitimer()" you don't get
75       "Time::HiRes::ualarm()" or "Time::HiRes::alarm()".
76
77       If you try to import an unimplemented function in the "use" statement
78       it will fail at compile time.
79
80       If your subsecond sleeping is implemented with "nanosleep()" instead of
81       "usleep()", you can mix subsecond sleeping with signals since
82       "nanosleep()" does not use signals.  This, however, is not portable,
83       and you should first check for the truth value of
84       &Time::HiRes::d_nanosleep to see whether you have nanosleep, and then
85       carefully read your "nanosleep()" C API documentation for any
86       peculiarities.
87
88       If you are using "nanosleep" for something else than mixing sleeping
89       with signals, give some thought to whether Perl is the tool you should
90       be using for work requiring nanosecond accuracies.
91
92       Remember that unless you are working on a hard realtime system, any
93       clocks and timers will be imprecise, especially so if you are working
94       in a pre-emptive multiuser system.  Understand the difference between
95       wallclock time and process time (in UNIX-like systems the sum of user
96       and system times).  Any attempt to sleep for X seconds will most
97       probably end up sleeping more than that, but don't be surprised if you
98       end up sleeping slightly less.
99
100       The following functions can be imported from this module.  No functions
101       are exported by default.
102
103       gettimeofday ()
104           In array context returns a two-element array with the seconds and
105           microseconds since the epoch.  In scalar context returns floating
106           seconds like "Time::HiRes::time()" (see below).
107
108       usleep ( $useconds )
109           Sleeps for the number of microseconds (millionths of a second)
110           specified.  Returns the number of microseconds actually slept.  Can
111           sleep for more than one second, unlike the "usleep" system call.
112           Can also sleep for zero seconds, which often works like a thread
113           yield.  See also "Time::HiRes::usleep()", "Time::HiRes::sleep()",
114           and "Time::HiRes::clock_nanosleep()".
115
116           Do not expect usleep() to be exact down to one microsecond.
117
118       nanosleep ( $nanoseconds )
119           Sleeps for the number of nanoseconds (1e9ths of a second)
120           specified.  Returns the number of nanoseconds actually slept
121           (accurate only to microseconds, the nearest thousand of them).  Can
122           sleep for more than one second.  Can also sleep for zero seconds,
123           which often works like a thread yield.  See also
124           "Time::HiRes::sleep()", "Time::HiRes::usleep()", and
125           "Time::HiRes::clock_nanosleep()".
126
127           Do not expect nanosleep() to be exact down to one nanosecond.
128           Getting even accuracy of one thousand nanoseconds is good.
129
130       ualarm ( $useconds [, $interval_useconds ] )
131           Issues a "ualarm" call; the $interval_useconds is optional and will
132           be zero if unspecified, resulting in "alarm"-like behaviour.
133
134           Returns the remaining time in the alarm in microseconds, or "undef"
135           if an error occurred.
136
137           ualarm(0) will cancel an outstanding ualarm().
138
139           Note that the interaction between alarms and sleeps is unspecified.
140
141       tv_interval
142           tv_interval ( $ref_to_gettimeofday [, $ref_to_later_gettimeofday] )
143
144           Returns the floating seconds between the two times, which should
145           have been returned by "gettimeofday()". If the second argument is
146           omitted, then the current time is used.
147
148       time ()
149           Returns a floating seconds since the epoch. This function can be
150           imported, resulting in a nice drop-in replacement for the "time"
151           provided with core Perl; see the "EXAMPLES" below.
152
153           NOTE 1: This higher resolution timer can return values either less
154           or more than the core "time()", depending on whether your platform
155           rounds the higher resolution timer values up, down, or to the
156           nearest second to get the core "time()", but naturally the
157           difference should be never more than half a second.  See also
158           "clock_getres", if available in your system.
159
160           NOTE 2: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
161           the "time()" seconds since epoch rolled over to 1_000_000_000, the
162           default floating point format of Perl and the seconds since epoch
163           have conspired to produce an apparent bug: if you print the value
164           of "Time::HiRes::time()" you seem to be getting only five decimals,
165           not six as promised (microseconds).  Not to worry, the microseconds
166           are there (assuming your platform supports such granularity in the
167           first place).  What is going on is that the default floating point
168           format of Perl only outputs 15 digits.  In this case that means ten
169           digits before the decimal separator and five after.  To see the
170           microseconds you can use either "printf"/"sprintf" with "%.6f", or
171           the "gettimeofday()" function in list context, which will give you
172           the seconds and microseconds as two separate values.
173
174       sleep ( $floating_seconds )
175           Sleeps for the specified amount of seconds.  Returns the number of
176           seconds actually slept (a floating point value).  This function can
177           be imported, resulting in a nice drop-in replacement for the
178           "sleep" provided with perl, see the "EXAMPLES" below.
179
180           Note that the interaction between alarms and sleeps is unspecified.
181
182       alarm ( $floating_seconds [, $interval_floating_seconds ] )
183           The "SIGALRM" signal is sent after the specified number of seconds.
184           Implemented using "setitimer()" if available, "ualarm()" if not.
185           The $interval_floating_seconds argument is optional and will be
186           zero if unspecified, resulting in "alarm()"-like behaviour.  This
187           function can be imported, resulting in a nice drop-in replacement
188           for the "alarm" provided with perl, see the "EXAMPLES" below.
189
190           Returns the remaining time in the alarm in seconds, or "undef" if
191           an error occurred.
192
193           NOTE 1: With some combinations of operating systems and Perl
194           releases "SIGALRM" restarts "select()", instead of interrupting it.
195           This means that an "alarm()" followed by a "select()" may together
196           take the sum of the times specified for the "alarm()" and the
197           "select()", not just the time of the "alarm()".
198
199           Note that the interaction between alarms and sleeps is unspecified.
200
201       setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )
202           Start up an interval timer: after a certain time, a signal ($which)
203           arrives, and more signals may keep arriving at certain intervals.
204           To disable an "itimer", use $floating_seconds of zero.  If the
205           $interval_floating_seconds is set to zero (or unspecified), the
206           timer is disabled after the next delivered signal.
207
208           Use of interval timers may interfere with "alarm()", "sleep()", and
209           "usleep()".  In standard-speak the "interaction is unspecified",
210           which means that anything may happen: it may work, it may not.
211
212           In scalar context, the remaining time in the timer is returned.
213
214           In list context, both the remaining time and the interval are
215           returned.
216
217           There are usually three or four interval timers (signals)
218           available: the $which can be "ITIMER_REAL", "ITIMER_VIRTUAL",
219           "ITIMER_PROF", or "ITIMER_REALPROF".  Note that which ones are
220           available depends: true UNIX platforms usually have the first
221           three, but only Solaris seems to have "ITIMER_REALPROF" (which is
222           used to profile multithreaded programs).  Win32 unfortunately does
223           not have interval timers.
224
225           "ITIMER_REAL" results in "alarm()"-like behaviour.  Time is counted
226           in real time; that is, wallclock time.  "SIGALRM" is delivered when
227           the timer expires.
228
229           "ITIMER_VIRTUAL" counts time in (process) virtual time; that is,
230           only when the process is running.  In multiprocessor/user/CPU
231           systems this may be more or less than real or wallclock time.
232           (This time is also known as the user time.)  "SIGVTALRM" is
233           delivered when the timer expires.
234
235           "ITIMER_PROF" counts time when either the process virtual time or
236           when the operating system is running on behalf of the process (such
237           as I/O).  (This time is also known as the system time.)  (The sum
238           of user time and system time is known as the CPU time.)  "SIGPROF"
239           is delivered when the timer expires.  "SIGPROF" can interrupt
240           system calls.
241
242           The semantics of interval timers for multithreaded programs are
243           system-specific, and some systems may support additional interval
244           timers.  For example, it is unspecified which thread gets the
245           signals.  See your "setitimer()" documentation.
246
247       getitimer ( $which )
248           Return the remaining time in the interval timer specified by
249           $which.
250
251           In scalar context, the remaining time is returned.
252
253           In list context, both the remaining time and the interval are
254           returned.  The interval is always what you put in using
255           "setitimer()".
256
257       clock_gettime ( $which )
258           Return as seconds the current value of the POSIX high resolution
259           timer specified by $which.  All implementations that support POSIX
260           high resolution timers are supposed to support at least the $which
261           value of "CLOCK_REALTIME", which is supposed to return results
262           close to the results of "gettimeofday", or the number of seconds
263           since 00:00:00:00 January 1, 1970 Greenwich Mean Time (GMT).  Do
264           not assume that CLOCK_REALTIME is zero, it might be one, or
265           something else.  Another potentially useful (but not available
266           everywhere) value is "CLOCK_MONOTONIC", which guarantees a
267           monotonically increasing time value (unlike time() or
268           gettimeofday(), which can be adjusted).  See your system
269           documentation for other possibly supported values.
270
271       clock_getres ( $which )
272           Return as seconds the resolution of the POSIX high resolution timer
273           specified by $which.  All implementations that support POSIX high
274           resolution timers are supposed to support at least the $which value
275           of "CLOCK_REALTIME", see "clock_gettime".
276
277           NOTE: the resolution returned may be highly optimistic.  Even if
278           the resolution is high (a small number), all it means is that
279           you'll be able to specify the arguments to clock_gettime() and
280           clock_nanosleep() with that resolution.  The system might not
281           actually be able to measure events at that resolution, and the
282           various overheads and the overall system load are certain to affect
283           any timings.
284
285       clock_nanosleep ( $which, $nanoseconds, $flags = 0)
286           Sleeps for the number of nanoseconds (1e9ths of a second)
287           specified.  Returns the number of nanoseconds actually slept.  The
288           $which is the "clock id", as with clock_gettime() and
289           clock_getres().  The flags default to zero but "TIMER_ABSTIME" can
290           specified (must be exported explicitly) which means that
291           $nanoseconds is not a time interval (as is the default) but instead
292           an absolute time.  Can sleep for more than one second.  Can also
293           sleep for zero seconds, which often works like a thread yield.  See
294           also "Time::HiRes::sleep()", "Time::HiRes::usleep()", and
295           "Time::HiRes::nanosleep()".
296
297           Do not expect clock_nanosleep() to be exact down to one nanosecond.
298           Getting even accuracy of one thousand nanoseconds is good.
299
300       clock()
301           Return as seconds the process time (user + system time) spent by
302           the process since the first call to clock() (the definition is not
303           "since the start of the process", though if you are lucky these
304           times may be quite close to each other, depending on the system).
305           What this means is that you probably need to store the result of
306           your first call to clock(), and subtract that value from the
307           following results of clock().
308
309           The time returned also includes the process times of the terminated
310           child processes for which wait() has been executed.  This value is
311           somewhat like the second value returned by the times() of core
312           Perl, but not necessarily identical.  Note that due to backward
313           compatibility limitations the returned value may wrap around at
314           about 2147 seconds or at about 36 minutes.
315
316       stat
317       stat FH
318       stat EXPR
319       lstat
320       lstat FH
321       lstat EXPR
322           As "stat" in perlfunc or "lstat" in perlfunc but with the
323           access/modify/change file timestamps in subsecond resolution, if
324           the operating system and the filesystem both support such
325           timestamps.  To override the standard stat():
326
327               use Time::HiRes qw(stat);
328
329           Test for the value of &Time::HiRes::d_hires_stat to find out
330           whether the operating system supports subsecond file timestamps: a
331           value larger than zero means yes. There are unfortunately no easy
332           ways to find out whether the filesystem supports such timestamps.
333           UNIX filesystems often do; NTFS does; FAT doesn't (FAT timestamp
334           granularity is two seconds).
335
336           A zero return value of &Time::HiRes::d_hires_stat means that
337           Time::HiRes::stat is a no-op passthrough for CORE::stat() (and
338           likewise for lstat), and therefore the timestamps will stay
339           integers.  The same thing will happen if the filesystem does not do
340           subsecond timestamps, even if the &Time::HiRes::d_hires_stat is
341           non-zero.
342
343           In any case do not expect nanosecond resolution, or even a
344           microsecond resolution.  Also note that the modify/access
345           timestamps might have different resolutions, and that they need not
346           be synchronized, e.g.  if the operations are
347
348               write
349               stat # t1
350               read
351               stat # t2
352
353           the access time stamp from t2 need not be greater-than the modify
354           time stamp from t1: it may be equal or less.
355
356       utime LIST
357           As "utime" in perlfunc but with the ability to set the
358           access/modify file timestamps in subsecond resolution, if the
359           operating system and the filesystem, and the mount options of the
360           filesystem, all support such timestamps.
361
362           To override the standard utime():
363
364               use Time::HiRes qw(utime);
365
366           Test for the value of &Time::HiRes::d_hires_utime to find out
367           whether the operating system supports setting subsecond file
368           timestamps.
369
370           As with CORE::utime(), passing undef as both the atime and mtime
371           will call the syscall with a NULL argument.
372
373           The actual achievable subsecond resolution depends on the
374           combination of the operating system and the filesystem.
375
376           Modifying the timestamps may not be possible at all: for example,
377           the "noatime" filesystem mount option may prohibit you from
378           changing the access time timestamp.
379
380           Returns the number of files successfully changed.
381

EXAMPLES

383         use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
384
385         $microseconds = 750_000;
386         usleep($microseconds);
387
388         # signal alarm in 2.5s & every .1s thereafter
389         ualarm(2_500_000, 100_000);
390         # cancel that ualarm
391         ualarm(0);
392
393         # get seconds and microseconds since the epoch
394         ($s, $usec) = gettimeofday();
395
396         # measure elapsed time
397         # (could also do by subtracting 2 gettimeofday return values)
398         $t0 = [gettimeofday];
399         # do bunch of stuff here
400         $t1 = [gettimeofday];
401         # do more stuff here
402         $t0_t1 = tv_interval $t0, $t1;
403
404         $elapsed = tv_interval ($t0, [gettimeofday]);
405         $elapsed = tv_interval ($t0); # equivalent code
406
407         #
408         # replacements for time, alarm and sleep that know about
409         # floating seconds
410         #
411         use Time::HiRes;
412         $now_fractions = Time::HiRes::time;
413         Time::HiRes::sleep (2.5);
414         Time::HiRes::alarm (10.6666666);
415
416         use Time::HiRes qw ( time alarm sleep );
417         $now_fractions = time;
418         sleep (2.5);
419         alarm (10.6666666);
420
421         # Arm an interval timer to go off first at 10 seconds and
422         # after that every 2.5 seconds, in process virtual time
423
424         use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
425
426         $SIG{VTALRM} = sub { print time, "\n" };
427         setitimer(ITIMER_VIRTUAL, 10, 2.5);
428
429         use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
430         # Read the POSIX high resolution timer.
431         my $high = clock_gettime(CLOCK_REALTIME);
432         # But how accurate we can be, really?
433         my $reso = clock_getres(CLOCK_REALTIME);
434
435         use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
436         clock_nanosleep(CLOCK_REALTIME, 1e6);
437         clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);
438
439         use Time::HiRes qw( clock );
440         my $clock0 = clock();
441         ... # Do something.
442         my $clock1 = clock();
443         my $clockd = $clock1 - $clock0;
444
445         use Time::HiRes qw( stat );
446         my ($atime, $mtime, $ctime) = (stat("istics"))[8, 9, 10];
447

C API

449       In addition to the perl API described above, a C API is available for
450       extension writers.  The following C functions are available in the
451       modglobal hash:
452
453         name             C prototype
454         ---------------  ----------------------
455         Time::NVtime     NV (*)()
456         Time::U2time     void (*)(pTHX_ UV ret[2])
457
458       Both functions return equivalent information (like "gettimeofday") but
459       with different representations.  The names "NVtime" and "U2time" were
460       selected mainly because they are operating system independent.
461       ("gettimeofday" is Unix-centric, though some platforms like Win32 and
462       VMS have emulations for it.)
463
464       Here is an example of using "NVtime" from C:
465
466         NV (*myNVtime)(); /* Returns -1 on failure. */
467         SV **svp = hv_fetchs(PL_modglobal, "Time::NVtime", 0);
468         if (!svp)         croak("Time::HiRes is required");
469         if (!SvIOK(*svp)) croak("Time::NVtime isn't a function pointer");
470         myNVtime = INT2PTR(NV(*)(), SvIV(*svp));
471         printf("The current time is: %" NVff "\n", (*myNVtime)());
472

DIAGNOSTICS

474   useconds or interval more than ...
475       In ualarm() you tried to use number of microseconds or interval (also
476       in microseconds) more than 1_000_000 and setitimer() is not available
477       in your system to emulate that case.
478
479   negative time not invented yet
480       You tried to use a negative time argument.
481
482   internal error: useconds < 0 (unsigned ... signed ...)
483       Something went horribly wrong-- the number of microseconds that cannot
484       become negative just became negative.  Maybe your compiler is broken?
485
486   useconds or uinterval equal to or more than 1000000
487       In some platforms it is not possible to get an alarm with subsecond
488       resolution and later than one second.
489
490   unimplemented in this platform
491       Some calls simply aren't available, real or emulated, on every
492       platform.
493

CAVEATS

495       Notice that the core "time()" maybe rounding rather than truncating.
496       What this means is that the core "time()" may be reporting the time as
497       one second later than "gettimeofday()" and "Time::HiRes::time()".
498
499       Adjusting the system clock (either manually or by services like ntp)
500       may cause problems, especially for long running programs that assume a
501       monotonously increasing time (note that all platforms do not adjust
502       time as gracefully as UNIX ntp does).  For example in Win32 (and
503       derived platforms like Cygwin and MinGW) the Time::HiRes::time() may
504       temporarily drift off from the system clock (and the original time())
505       by up to 0.5 seconds. Time::HiRes will notice this eventually and
506       recalibrate.  Note that since Time::HiRes 1.77 the
507       clock_gettime(CLOCK_MONOTONIC) might help in this (in case your system
508       supports CLOCK_MONOTONIC).
509
510       Some systems have APIs but not implementations: for example QNX and
511       Haiku have the interval timer APIs but not the functionality.
512
513       In pre-Sierra macOS (pre-10.12, OS X) clock_getres(), clock_gettime()
514       and clock_nanosleep() are emulated using the Mach timers; as a side
515       effect of being emulated the CLOCK_REALTIME and CLOCK_MONOTONIC are the
516       same timer.
517
518       gnukfreebsd seems to have non-functional futimens() and utimensat() (at
519       least as of 10.1): therefore the hires utime() does not work.
520

SEE ALSO

522       Perl modules BSD::Resource, Time::TAI64.
523
524       Your system documentation for "clock", "clock_gettime", "clock_getres",
525       "clock_nanosleep", "clock_settime", "getitimer", "gettimeofday",
526       "setitimer", "sleep", "stat", "ualarm".
527

AUTHORS

529       D. Wegscheid <wegscd@whirlpool.com> R. Schertler <roderick@argon.org>
530       J. Hietaniemi <jhi@iki.fi> G. Aas <gisle@aas.no>
531
533       Copyright (c) 1996-2002 Douglas E. Wegscheid.  All rights reserved.
534
535       Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Jarkko
536       Hietaniemi.  All rights reserved.
537
538       Copyright (C) 2011, 2012, 2013 Andrew Main (Zefram) <zefram@fysh.org>
539
540       This program is free software; you can redistribute it and/or modify it
541       under the same terms as Perl itself.
542
543
544
545perl v5.30.1                      2020-01-30                          HiRes(3)
Impressum