| 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. |