Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 624 insertions, 0 deletions

diff --git a/upstream/mageia-cauldron/man3pm/Time::HiRes.3pm b/upstream/mageia-cauldron/man3pm/Time::HiRes.3pm
new file mode 100644
index 00000000..c98ad56b
--- /dev/null
+++ b/upstream/mageia-cauldron/man3pm/Time::HiRes.3pm
@@ -0,0 +1,624 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Time::HiRes 3pm"
+.TH Time::HiRes 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+Time::HiRes \- High resolution alarm, sleep, gettimeofday, interval timers
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 3
+\&  use Time::HiRes qw( usleep ualarm gettimeofday tv_interval nanosleep
+\&                      clock_gettime clock_getres clock_nanosleep clock
+\&                      stat lstat utime);
+\&
+\&  usleep ($microseconds);
+\&  nanosleep ($nanoseconds);
+\&
+\&  ualarm ($microseconds);
+\&  ualarm ($microseconds, $interval_microseconds);
+\&
+\&  $t0 = [gettimeofday];
+\&  ($seconds, $microseconds) = gettimeofday;
+\&
+\&  $elapsed = tv_interval ( $t0, [$seconds, $microseconds]);
+\&  $elapsed = tv_interval ( $t0, [gettimeofday]);
+\&  $elapsed = tv_interval ( $t0 );
+\&
+\&  use Time::HiRes qw ( time alarm sleep );
+\&
+\&  $now_fractions = time;
+\&  sleep ($floating_seconds);
+\&  alarm ($floating_seconds);
+\&  alarm ($floating_seconds, $floating_interval);
+\&
+\&  use Time::HiRes qw( setitimer getitimer );
+\&
+\&  setitimer ($which, $floating_seconds, $floating_interval );
+\&  getitimer ($which);
+\&
+\&  use Time::HiRes qw( clock_gettime clock_getres clock_nanosleep
+\&                      ITIMER_REAL ITIMER_VIRTUAL ITIMER_PROF
+\&                      ITIMER_REALPROF );
+\&
+\&  $realtime   = clock_gettime(CLOCK_REALTIME);
+\&  $resolution = clock_getres(CLOCK_REALTIME);
+\&
+\&  clock_nanosleep(CLOCK_REALTIME, 1.5e9);
+\&  clock_nanosleep(CLOCK_REALTIME, time()*1e9 + 10e9, TIMER_ABSTIME);
+\&
+\&  my $ticktock = clock();
+\&
+\&  use Time::HiRes qw( stat lstat );
+\&
+\&  my @stat = stat("file");
+\&  my @stat = stat(FH);
+\&  my @stat = lstat("file");
+\&
+\&  use Time::HiRes qw( utime );
+\&  utime $floating_seconds, $floating_seconds, file...;
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+The \f(CW\*(C`Time::HiRes\*(C'\fR module implements a Perl interface to the
+\&\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
+\&\f(CW\*(C`setitimer\*(C'\fR/\f(CW\*(C`getitimer\*(C'\fR system calls, in other words, high
+resolution time and timers. See the "EXAMPLES" section below and the
+test scripts for usage; see your system documentation for the
+description of the underlying \f(CW\*(C`nanosleep\*(C'\fR or \f(CW\*(C`usleep\*(C'\fR, \f(CW\*(C`ualarm\*(C'\fR,
+\&\f(CW\*(C`gettimeofday\*(C'\fR, and \f(CW\*(C`setitimer\*(C'\fR/\f(CW\*(C`getitimer\*(C'\fR calls.
+.PP
+If your system lacks \f(CWgettimeofday()\fR or an emulation of it you don't
+get \f(CWgettimeofday()\fR or the one-argument form of \f(CWtv_interval()\fR.
+If your system lacks all of \f(CWnanosleep()\fR, \f(CWusleep()\fR,
+\&\f(CWselect()\fR, and \f(CW\*(C`poll\*(C'\fR, you don't get \f(CWTime::HiRes::usleep()\fR,
+\&\f(CWTime::HiRes::nanosleep()\fR, or \f(CWTime::HiRes::sleep()\fR.
+If your system lacks both \f(CWualarm()\fR and \f(CWsetitimer()\fR you don't get
+\&\f(CWTime::HiRes::ualarm()\fR or \f(CWTime::HiRes::alarm()\fR.
+.PP
+If you try to import an unimplemented function in the \f(CW\*(C`use\*(C'\fR statement
+it will fail at compile time.
+.PP
+If your subsecond sleeping is implemented with \f(CWnanosleep()\fR instead
+of \f(CWusleep()\fR, you can mix subsecond sleeping with signals since
+\&\f(CWnanosleep()\fR does not use signals.  This, however, is not portable,
+and you should first check for the truth value of
+\&\f(CW&Time::HiRes::d_nanosleep\fR to see whether you have nanosleep, and
+then carefully read your \f(CWnanosleep()\fR C API documentation for any
+peculiarities.
+.PP
+If you are using \f(CW\*(C`nanosleep\*(C'\fR for something else than mixing sleeping
+with signals, give some thought to whether Perl is the tool you should
+be using for work requiring nanosecond accuracies.
+.PP
+Remember that unless you are working on a \fIhard realtime\fR system,
+any clocks and timers will be imprecise, especially so if you are working
+in a pre-emptive multiuser system.  Understand the difference between
+\&\fIwallclock time\fR and process time (in UNIX-like systems the sum of
+\&\fIuser\fR and \fIsystem\fR times).  Any attempt to sleep for X seconds will
+most probably end up sleeping \fBmore\fR than that, but don't be surprised
+if you end up sleeping slightly \fBless\fR.
+.PP
+The following functions can be imported from this module.
+No functions are exported by default.
+.IP "gettimeofday ()" 4
+.IX Item "gettimeofday ()"
+In array context returns a two-element array with the seconds and
+microseconds since the epoch.  In scalar context returns floating
+seconds like \f(CWTime::HiRes::time()\fR (see below).
+.ie n .IP "usleep ( $useconds )" 4
+.el .IP "usleep ( \f(CW$useconds\fR )" 4
+.IX Item "usleep ( $useconds )"
+Sleeps for the number of microseconds (millionths of a second)
+specified.  Returns the number of microseconds actually slept.
+Can sleep for more than one second, unlike the \f(CW\*(C`usleep\*(C'\fR system call.
+Can also sleep for zero seconds, which often works like a \fIthread yield\fR.
+See also \f(CWTime::HiRes::sleep()\fR, and
+\&\f(CWclock_nanosleep()\fR.
+.Sp
+Do not expect \fBusleep()\fR to be exact down to one microsecond.
+.ie n .IP "nanosleep ( $nanoseconds )" 4
+.el .IP "nanosleep ( \f(CW$nanoseconds\fR )" 4
+.IX Item "nanosleep ( $nanoseconds )"
+Sleeps for the number of nanoseconds (1e9ths of a second) specified.
+Returns the number of nanoseconds actually slept (accurate only to
+microseconds, the nearest thousand of them).  Can sleep for more than
+one second.  Can also sleep for zero seconds, which often works like
+a \fIthread yield\fR.  See also
+\&\f(CWTime::HiRes::sleep()\fR,
+\&\f(CWTime::HiRes::usleep()\fR, and
+\&\f(CWclock_nanosleep()\fR.
+.Sp
+Do not expect \fBnanosleep()\fR to be exact down to one nanosecond.
+Getting even accuracy of one thousand nanoseconds is good.
+.ie n .IP "ualarm ( $useconds [, $interval_useconds ] )" 4
+.el .IP "ualarm ( \f(CW$useconds\fR [, \f(CW$interval_useconds\fR ] )" 4
+.IX Item "ualarm ( $useconds [, $interval_useconds ] )"
+Issues a \f(CW\*(C`ualarm\*(C'\fR call; the \f(CW$interval_useconds\fR is optional and
+will be zero if unspecified, resulting in \f(CW\*(C`alarm\*(C'\fR\-like behaviour.
+.Sp
+Returns the remaining time in the alarm in microseconds, or \f(CW\*(C`undef\*(C'\fR
+if an error occurred.
+.Sp
+\&\fBualarm\fR\|(0) will cancel an outstanding \fBualarm()\fR.
+.Sp
+Note that the interaction between alarms and sleeps is unspecified.
+.IP tv_interval 4
+.IX Item "tv_interval"
+tv_interval ( \f(CW$ref_to_gettimeofday\fR [, \f(CW$ref_to_later_gettimeofday\fR] )
+.Sp
+Returns the floating seconds between the two times, which should have
+been returned by \f(CWgettimeofday()\fR. If the second argument is omitted,
+then the current time is used.
+.IP "time ()" 4
+.IX Item "time ()"
+Returns a floating seconds since the epoch. This function can be
+imported, resulting in a nice drop-in replacement for the \f(CW\*(C`time\*(C'\fR
+provided with core Perl; see the "EXAMPLES" below.
+.Sp
+\&\fBNOTE 1\fR: This higher resolution timer can return values either less
+or more than the core \f(CWtime()\fR, depending on whether your platform
+rounds the higher resolution timer values up, down, or to the nearest second
+to get the core \f(CWtime()\fR, but naturally the difference should be never
+more than half a second.  See also "clock_getres", if available
+in your system.
+.Sp
+\&\fBNOTE 2\fR: Since Sunday, September 9th, 2001 at 01:46:40 AM GMT, when
+the \f(CWtime()\fR seconds since epoch rolled over to 1_000_000_000, the
+default floating point format of Perl and the seconds since epoch have
+conspired to produce an apparent bug: if you print the value of
+\&\f(CWTime::HiRes::time()\fR you seem to be getting only five decimals, not
+six as promised (microseconds).  Not to worry, the microseconds are
+there (assuming your platform supports such granularity in the first
+place).  What is going on is that the default floating point format of
+Perl only outputs 15 digits.  In this case that means ten digits
+before the decimal separator and five after.  To see the microseconds
+you can use either \f(CW\*(C`printf\*(C'\fR/\f(CW\*(C`sprintf\*(C'\fR with \f(CW"%.6f"\fR, or the
+\&\f(CWgettimeofday()\fR function in list context, which will give you the
+seconds and microseconds as two separate values.
+.ie n .IP "sleep ( $floating_seconds )" 4
+.el .IP "sleep ( \f(CW$floating_seconds\fR )" 4
+.IX Item "sleep ( $floating_seconds )"
+Sleeps for the specified amount of seconds.  Returns the number of
+seconds actually slept (a floating point value).  This function can
+be imported, resulting in a nice drop-in replacement for the \f(CW\*(C`sleep\*(C'\fR
+provided with perl, see the "EXAMPLES" below.
+.Sp
+Note that the interaction between alarms and sleeps is unspecified.
+.ie n .IP "alarm ( $floating_seconds [, $interval_floating_seconds ] )" 4
+.el .IP "alarm ( \f(CW$floating_seconds\fR [, \f(CW$interval_floating_seconds\fR ] )" 4
+.IX Item "alarm ( $floating_seconds [, $interval_floating_seconds ] )"
+The \f(CW\*(C`SIGALRM\*(C'\fR signal is sent after the specified number of seconds.
+Implemented using \f(CWsetitimer()\fR if available, \f(CWualarm()\fR if not.
+The \f(CW$interval_floating_seconds\fR argument is optional and will be
+zero if unspecified, resulting in \f(CWalarm()\fR\-like behaviour.  This
+function can be imported, resulting in a nice drop-in replacement for
+the \f(CW\*(C`alarm\*(C'\fR provided with perl, see the "EXAMPLES" below.
+.Sp
+Returns the remaining time in the alarm in seconds, or \f(CW\*(C`undef\*(C'\fR
+if an error occurred.
+.Sp
+\&\fBNOTE 1\fR: With some combinations of operating systems and Perl
+releases \f(CW\*(C`SIGALRM\*(C'\fR restarts \f(CWselect()\fR, instead of interrupting it.
+This means that an \f(CWalarm()\fR followed by a \f(CWselect()\fR may together
+take the sum of the times specified for the \f(CWalarm()\fR and the
+\&\f(CWselect()\fR, not just the time of the \f(CWalarm()\fR.
+.Sp
+Note that the interaction between alarms and sleeps is unspecified.
+.ie n .IP "setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )" 4
+.el .IP "setitimer ( \f(CW$which\fR, \f(CW$floating_seconds\fR [, \f(CW$interval_floating_seconds\fR ] )" 4
+.IX Item "setitimer ( $which, $floating_seconds [, $interval_floating_seconds ] )"
+Start up an interval timer: after a certain time, a signal ($which) arrives,
+and more signals may keep arriving at certain intervals.  To disable
+an "itimer", use \f(CW$floating_seconds\fR of zero.  If the
+\&\f(CW$interval_floating_seconds\fR is set to zero (or unspecified), the
+timer is disabled \fBafter\fR the next delivered signal.
+.Sp
+Use of interval timers may interfere with \f(CWalarm()\fR, \f(CWsleep()\fR,
+and \f(CWusleep()\fR.  In standard-speak the "interaction is unspecified",
+which means that \fIanything\fR may happen: it may work, it may not.
+.Sp
+In scalar context, the remaining time in the timer is returned.
+.Sp
+In list context, both the remaining time and the interval are returned.
+.Sp
+There are usually three or four interval timers (signals) available: the
+\&\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
+\&\f(CW\*(C`ITIMER_REALPROF\*(C'\fR.  Note that which ones are available depends: true
+UNIX platforms usually have the first three, but only Solaris seems to
+have \f(CW\*(C`ITIMER_REALPROF\*(C'\fR (which is used to profile multithreaded programs).
+Win32 unfortunately does not have interval timers.
+.Sp
+\&\f(CW\*(C`ITIMER_REAL\*(C'\fR results in \f(CWalarm()\fR\-like behaviour.  Time is counted in
+\&\fIreal time\fR; that is, wallclock time.  \f(CW\*(C`SIGALRM\*(C'\fR is delivered when
+the timer expires.
+.Sp
+\&\f(CW\*(C`ITIMER_VIRTUAL\*(C'\fR counts time in (process) \fIvirtual time\fR; that is,
+only when the process is running.  In multiprocessor/user/CPU systems
+this may be more or less than real or wallclock time.  (This time is
+also known as the \fIuser time\fR.)  \f(CW\*(C`SIGVTALRM\*(C'\fR is delivered when the
+timer expires.
+.Sp
+\&\f(CW\*(C`ITIMER_PROF\*(C'\fR counts time when either the process virtual time or when
+the operating system is running on behalf of the process (such as I/O).
+(This time is also known as the \fIsystem time\fR.)  (The sum of user
+time and system time is known as the \fICPU time\fR.)  \f(CW\*(C`SIGPROF\*(C'\fR is
+delivered when the timer expires.  \f(CW\*(C`SIGPROF\*(C'\fR can interrupt system calls.
+.Sp
+The semantics of interval timers for multithreaded programs are
+system-specific, and some systems may support additional interval
+timers.  For example, it is unspecified which thread gets the signals.
+See your \f(CWsetitimer(2)\fR documentation.
+.ie n .IP "getitimer ( $which )" 4
+.el .IP "getitimer ( \f(CW$which\fR )" 4
+.IX Item "getitimer ( $which )"
+Return the remaining time in the interval timer specified by \f(CW$which\fR.
+.Sp
+In scalar context, the remaining time is returned.
+.Sp
+In list context, both the remaining time and the interval are returned.
+The interval is always what you put in using \f(CWsetitimer()\fR.
+.ie n .IP "clock_gettime ( $which )" 4
+.el .IP "clock_gettime ( \f(CW$which\fR )" 4
+.IX Item "clock_gettime ( $which )"
+Return as seconds the current value of the POSIX high resolution timer
+specified by \f(CW$which\fR.  All implementations that support POSIX high
+resolution timers are supposed to support at least the \f(CW$which\fR value
+of \f(CW\*(C`CLOCK_REALTIME\*(C'\fR, which is supposed to return results close to the
+results of \f(CW\*(C`gettimeofday\*(C'\fR, or the number of seconds since 00:00:00:00
+January 1, 1970 Greenwich Mean Time (GMT).  Do not assume that
+CLOCK_REALTIME is zero, it might be one, or something else.
+Another potentially useful (but not available everywhere) value is
+\&\f(CW\*(C`CLOCK_MONOTONIC\*(C'\fR, which guarantees a monotonically increasing time
+value (unlike \fBtime()\fR or \fBgettimeofday()\fR, which can be adjusted).
+See your system documentation for other possibly supported values.
+.ie n .IP "clock_getres ( $which )" 4
+.el .IP "clock_getres ( \f(CW$which\fR )" 4
+.IX Item "clock_getres ( $which )"
+Return as seconds the resolution of the POSIX high resolution timer
+specified by \f(CW$which\fR.  All implementations that support POSIX high
+resolution timers are supposed to support at least the \f(CW$which\fR value
+of \f(CW\*(C`CLOCK_REALTIME\*(C'\fR, see "clock_gettime".
+.Sp
+\&\fBNOTE\fR: the resolution returned may be highly optimistic.  Even if
+the resolution is high (a small number), all it means is that you'll
+be able to specify the arguments to \fBclock_gettime()\fR and \fBclock_nanosleep()\fR
+with that resolution.  The system might not actually be able to measure
+events at that resolution, and the various overheads and the overall system
+load are certain to affect any timings.
+.ie n .IP "clock_nanosleep ( $which, $nanoseconds, $flags = 0)" 4
+.el .IP "clock_nanosleep ( \f(CW$which\fR, \f(CW$nanoseconds\fR, \f(CW$flags\fR = 0)" 4
+.IX Item "clock_nanosleep ( $which, $nanoseconds, $flags = 0)"
+Sleeps for the number of nanoseconds (1e9ths of a second) specified.
+Returns the number of nanoseconds actually slept.  The \f(CW$which\fR is the
+"clock id", as with \fBclock_gettime()\fR and \fBclock_getres()\fR.  The flags
+default to zero but \f(CW\*(C`TIMER_ABSTIME\*(C'\fR can specified (must be exported
+explicitly) which means that \f(CW$nanoseconds\fR is not a time interval
+(as is the default) but instead an absolute time.  Can sleep for more
+than one second.  Can also sleep for zero seconds, which often works
+like a \fIthread yield\fR.  See also
+\&\f(CWTime::HiRes::sleep()\fR,
+\&\f(CWTime::HiRes::usleep()\fR, and
+\&\f(CWTime::HiRes::nanosleep()\fR.
+.Sp
+Do not expect \fBclock_nanosleep()\fR to be exact down to one nanosecond.
+Getting even accuracy of one thousand nanoseconds is good.
+.IP \fBclock()\fR 4
+.IX Item "clock()"
+Return as seconds the \fIprocess time\fR (user + system time) spent by
+the process since the first call to \fBclock()\fR (the definition is \fBnot\fR
+"since the start of the process", though if you are lucky these times
+may be quite close to each other, depending on the system).  What this
+means is that you probably need to store the result of your first call
+to \fBclock()\fR, and subtract that value from the following results of \fBclock()\fR.
+.Sp
+The time returned also includes the process times of the terminated
+child processes for which \fBwait()\fR has been executed.  This value is
+somewhat like the second value returned by the \fBtimes()\fR of core Perl,
+but not necessarily identical.  Note that due to backward
+compatibility limitations the returned value may wrap around at about
+2147 seconds or at about 36 minutes.
+.IP stat 4
+.IX Item "stat"
+.PD 0
+.IP "stat FH" 4
+.IX Item "stat FH"
+.IP "stat EXPR" 4
+.IX Item "stat EXPR"
+.IP lstat 4
+.IX Item "lstat"
+.IP "lstat FH" 4
+.IX Item "lstat FH"
+.IP "lstat EXPR" 4
+.IX Item "lstat EXPR"
+.PD
+As "stat" in perlfunc or "lstat" in perlfunc
+but with the access/modify/change file timestamps
+in subsecond resolution, if the operating system and the filesystem
+both support such timestamps.  To override the standard \fBstat()\fR:
+.Sp
+.Vb 1
+\&    use Time::HiRes qw(stat);
+.Ve
+.Sp
+Test for the value of &Time::HiRes::d_hires_stat to find out whether
+the operating system supports subsecond file timestamps: a value
+larger than zero means yes. There are unfortunately no easy
+ways to find out whether the filesystem supports such timestamps.
+UNIX filesystems often do; NTFS does; FAT doesn't (FAT timestamp
+granularity is \fBtwo\fR seconds).
+.Sp
+A zero return value of &Time::HiRes::d_hires_stat means that
+Time::HiRes::stat is a no-op passthrough for \fBCORE::stat()\fR
+(and likewise for lstat),
+and therefore the timestamps will stay integers.  The same
+thing will happen if the filesystem does not do subsecond timestamps,
+even if the &Time::HiRes::d_hires_stat is non-zero.
+.Sp
+In any case do not expect nanosecond resolution, or even a microsecond
+resolution.  Also note that the modify/access timestamps might have
+different resolutions, and that they need not be synchronized, e.g.
+if the operations are
+.Sp
+.Vb 4
+\&    write
+\&    stat # t1
+\&    read
+\&    stat # t2
+.Ve
+.Sp
+the access time stamp from t2 need not be greater-than the modify
+time stamp from t1: it may be equal or \fIless\fR.
+.IP "utime LIST" 4
+.IX Item "utime LIST"
+As "utime" in perlfunc
+but with the ability to set the access/modify file timestamps
+in subsecond resolution, if the operating system and the filesystem,
+and the mount options of the filesystem, all support such timestamps.
+.Sp
+To override the standard \fButime()\fR:
+.Sp
+.Vb 1
+\&    use Time::HiRes qw(utime);
+.Ve
+.Sp
+Test for the value of &Time::HiRes::d_hires_utime to find out whether
+the operating system supports setting subsecond file timestamps.
+.Sp
+As with \fBCORE::utime()\fR, passing undef as both the atime and mtime will
+call the syscall with a NULL argument.
+.Sp
+The actual achievable subsecond resolution depends on the combination
+of the operating system and the filesystem.
+.Sp
+Modifying the timestamps may not be possible at all: for example, the
+\&\f(CW\*(C`noatime\*(C'\fR filesystem mount option may prohibit you from changing the
+access time timestamp.
+.Sp
+Returns the number of files successfully changed.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+.Vb 1
+\&  use Time::HiRes qw(usleep ualarm gettimeofday tv_interval);
+\&
+\&  $microseconds = 750_000;
+\&  usleep($microseconds);
+\&
+\&  # signal alarm in 2.5s & every .1s thereafter
+\&  ualarm(2_500_000, 100_000);
+\&  # cancel that ualarm
+\&  ualarm(0);
+\&
+\&  # get seconds and microseconds since the epoch
+\&  ($s, $usec) = gettimeofday();
+\&
+\&  # measure elapsed time
+\&  # (could also do by subtracting 2 gettimeofday return values)
+\&  $t0 = [gettimeofday];
+\&  # do bunch of stuff here
+\&  $t1 = [gettimeofday];
+\&  # do more stuff here
+\&  $t0_t1 = tv_interval $t0, $t1;
+\&
+\&  $elapsed = tv_interval ($t0, [gettimeofday]);
+\&  $elapsed = tv_interval ($t0); # equivalent code
+\&
+\&  #
+\&  # replacements for time, alarm and sleep that know about
+\&  # floating seconds
+\&  #
+\&  use Time::HiRes;
+\&  $now_fractions = Time::HiRes::time;
+\&  Time::HiRes::sleep (2.5);
+\&  Time::HiRes::alarm (10.6666666);
+\&
+\&  use Time::HiRes qw ( time alarm sleep );
+\&  $now_fractions = time;
+\&  sleep (2.5);
+\&  alarm (10.6666666);
+\&
+\&  # Arm an interval timer to go off first at 10 seconds and
+\&  # after that every 2.5 seconds, in process virtual time
+\&
+\&  use Time::HiRes qw ( setitimer ITIMER_VIRTUAL time );
+\&
+\&  $SIG{VTALRM} = sub { print time, "\en" };
+\&  setitimer(ITIMER_VIRTUAL, 10, 2.5);
+\&
+\&  use Time::HiRes qw( clock_gettime clock_getres CLOCK_REALTIME );
+\&  # Read the POSIX high resolution timer.
+\&  my $high = clock_gettime(CLOCK_REALTIME);
+\&  # But how accurate we can be, really?
+\&  my $reso = clock_getres(CLOCK_REALTIME);
+\&
+\&  use Time::HiRes qw( clock_nanosleep TIMER_ABSTIME );
+\&  clock_nanosleep(CLOCK_REALTIME, 1e6);
+\&  clock_nanosleep(CLOCK_REALTIME, 2e9, TIMER_ABSTIME);
+\&
+\&  use Time::HiRes qw( clock );
+\&  my $clock0 = clock();
+\&  ... # Do something.
+\&  my $clock1 = clock();
+\&  my $clockd = $clock1 \- $clock0;
+\&
+\&  use Time::HiRes qw( stat );
+\&  my ($atime, $mtime, $ctime) = (stat("istics"))[8, 9, 10];
+.Ve
+.SH "C API"
+.IX Header "C API"
+In addition to the perl API described above, a C API is available for
+extension writers.  The following C functions are available in the
+modglobal hash:
+.PP
+.Vb 4
+\&  name             C prototype
+\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\&  Time::NVtime     NV (*)()
+\&  Time::U2time     void (*)(pTHX_ UV ret[2])
+.Ve
+.PP
+Both functions return equivalent information (like \f(CW\*(C`gettimeofday\*(C'\fR)
+but with different representations.  The names \f(CW\*(C`NVtime\*(C'\fR and \f(CW\*(C`U2time\*(C'\fR
+were selected mainly because they are operating system independent.
+(\f(CW\*(C`gettimeofday\*(C'\fR is Unix-centric, though some platforms like Win32 and
+VMS have emulations for it.)
+.PP
+Here is an example of using \f(CW\*(C`NVtime\*(C'\fR from C:
+.PP
+.Vb 6
+\&  NV (*myNVtime)(); /* Returns \-1 on failure. */
+\&  SV **svp = hv_fetchs(PL_modglobal, "Time::NVtime", 0);
+\&  if (!svp)         croak("Time::HiRes is required");
+\&  if (!SvIOK(*svp)) croak("Time::NVtime isn\*(Aqt a function pointer");
+\&  myNVtime = INT2PTR(NV(*)(), SvIV(*svp));
+\&  printf("The current time is: %" NVff "\en", (*myNVtime)());
+.Ve
+.SH DIAGNOSTICS
+.IX Header "DIAGNOSTICS"
+.SS "useconds or interval more than ..."
+.IX Subsection "useconds or interval more than ..."
+In \fBualarm()\fR you tried to use number of microseconds or interval (also
+in microseconds) more than 1_000_000 and \fBsetitimer()\fR is not available
+in your system to emulate that case.
+.SS "negative time not invented yet"
+.IX Subsection "negative time not invented yet"
+You tried to use a negative time argument.
+.SS "internal error: useconds < 0 (unsigned ... signed ...)"
+.IX Subsection "internal error: useconds < 0 (unsigned ... signed ...)"
+Something went horribly wrong\-\- the number of microseconds that cannot
+become negative just became negative.  Maybe your compiler is broken?
+.SS "useconds or uinterval equal to or more than 1000000"
+.IX Subsection "useconds or uinterval equal to or more than 1000000"
+In some platforms it is not possible to get an alarm with subsecond
+resolution and later than one second.
+.SS "unimplemented in this platform"
+.IX Subsection "unimplemented in this platform"
+Some calls simply aren't available, real or emulated, on every platform.
+.SH CAVEATS
+.IX Header "CAVEATS"
+Notice that the core \f(CWtime()\fR maybe rounding rather than truncating.
+What this means is that the core \f(CWtime()\fR may be reporting the time
+as one second later than \f(CWgettimeofday()\fR and \f(CWTime::HiRes::time()\fR.
+.PP
+Adjusting the system clock (either manually or by services like ntp)
+may cause problems, especially for long running programs that assume
+a monotonously increasing time (note that all platforms do not adjust
+time as gracefully as UNIX ntp does).  For example in Win32 (and derived
+platforms like Cygwin and MinGW) the \fBTime::HiRes::time()\fR may temporarily
+drift off from the system clock (and the original \fBtime()\fR)  by up to 0.5
+seconds. Time::HiRes will notice this eventually and recalibrate.
+Note that since Time::HiRes 1.77 the clock_gettime(CLOCK_MONOTONIC)
+might help in this (in case your system supports CLOCK_MONOTONIC).
+.PP
+Some systems have APIs but not implementations: for example QNX and Haiku
+have the interval timer APIs but not the functionality.
+.PP
+In pre-Sierra macOS (pre\-10.12, OS X) \fBclock_getres()\fR, \fBclock_gettime()\fR
+and \fBclock_nanosleep()\fR are emulated using the Mach timers; as a side
+effect of being emulated the CLOCK_REALTIME and CLOCK_MONOTONIC are
+the same timer.
+.PP
+gnukfreebsd seems to have non-functional \fBfutimens()\fR and \fButimensat()\fR
+(at least as of 10.1): therefore the hires \fButime()\fR does not work.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Perl modules BSD::Resource, Time::TAI64.
+.PP
+Your system documentation for \f(CWclock(3)\fR, \f(CWclock_gettime(2)\fR,
+\&\f(CWclock_getres(3)\fR, \f(CWclock_nanosleep(3)\fR, \f(CWclock_settime(2)\fR,
+\&\f(CWgetitimer(2)\fR, \f(CWgettimeofday(2)\fR, \f(CWsetitimer(2)\fR, \f(CWsleep(3)\fR,
+\&\f(CWstat(2)\fR, \f(CWualarm(3)\fR.
+.SH AUTHORS
+.IX Header "AUTHORS"
+D. Wegscheid <wegscd@whirlpool.com>
+R. Schertler <roderick@argon.org>
+J. Hietaniemi <jhi@iki.fi>
+G. Aas <gisle@aas.no>
+.SH "COPYRIGHT AND LICENSE"
+.IX Header "COPYRIGHT AND LICENSE"
+Copyright (c) 1996\-2002 Douglas E. Wegscheid.  All rights reserved.
+.PP
+Copyright (c) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Jarkko Hietaniemi.
+All rights reserved.
+.PP
+Copyright (C) 2011, 2012, 2013 Andrew Main (Zefram) <zefram@fysh.org>
+.PP
+This program is free software; you can redistribute it and/or modify
+it under the same terms as Perl itself.