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