--- IO-AIO/AIO.pm	2018/07/24 04:58:59	1.287
+++ IO-AIO/AIO.pm	2018/11/29 19:53:46	1.297
@@ -173,7 +173,7 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = 4.42;
+   our $VERSION = 4.6;
 
    our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
@@ -543,9 +543,10 @@
 
 =item aio_lstat $fh, $callback->($status)
 
-Works like perl's C<stat> or C<lstat> in void context. The callback will
-be called after the stat and the results will be available using C<stat _>
-or C<-s _> etc...
+Works almost exactly like perl's C<stat> or C<lstat> in void context. The
+callback will be called after the stat and the results will be available
+using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
+and C<-T>).
 
 The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
 for an explanation.
@@ -563,6 +564,9 @@
 C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
 C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
 
+To access higher resolution stat timestamps, see L<SUBSECOND STAT TIME
+ACCESS>.
+
 Example: Print the length of F</etc/passwd>:
 
    aio_stat "/etc/passwd", sub {
@@ -621,9 +625,10 @@
 and $mtime being undef). Fractional times are supported if the underlying
 syscalls support them.
 
-When called with a pathname, uses utimes(2) if available, otherwise
-utime(2). If called on a file descriptor, uses futimes(2) if available,
-otherwise returns ENOSYS, so this is not portable.
+When called with a pathname, uses utimensat(2) or utimes(2) if available,
+otherwise utime(2). If called on a file descriptor, uses futimens(2)
+or futimes(2) if available, otherwise returns ENOSYS, so this is not
+portable.
 
 Examples:
 
@@ -1382,11 +1387,14 @@
 
 =item aio_mlockall $flags, $callback->($status)
 
-Calls the C<mlockall> function with the given C<$flags> (a combination of
-C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
+Calls the C<mlockall> function with the given C<$flags> (a
+combination of C<IO::AIO::MCL_CURRENT>, C<IO::AIO::MCL_FUTURE> and
+C<IO::AIO::MCL_ONFAULT>).
 
 On systems that do not implement C<mlockall>, this function returns C<-1>
-and sets errno to C<ENOSYS>.
+and sets errno to C<ENOSYS>. Similarly, flag combinations not supported
+by the system result in a return value of C<-1> with errno being set to
+C<EINVAL>.
 
 Note that the corresponding C<munlockall> is synchronous and is
 documented under L<MISCELLANEOUS FUNCTIONS>.
@@ -1781,6 +1789,7 @@
 
 =back
 
+
 =head2 SUPPORT FUNCTIONS
 
 =head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
@@ -1855,6 +1864,16 @@
    IO::AIO::poll_wait, IO::AIO::poll_cb
       while IO::AIO::nreqs;
 
+This function can be useful at program aborts, to make sure outstanding
+I/O has been done (C<IO::AIO> uses an C<END> block which already calls
+this function on normal exits), or when you are merely using C<IO::AIO>
+for its more advanced functions, rather than for async I/O, e.g.:
+
+   my ($dirs, $nondirs);
+   IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
+   IO::AIO::flush;
+   # $dirs, $nondirs are now set
+
 =item IO::AIO::max_poll_reqs $nreqs
 
 =item IO::AIO::max_poll_time $seconds
@@ -1890,6 +1909,7 @@
 
 =back
 
+
 =head3 CONTROLLING THE NUMBER OF THREADS
 
 =over
@@ -1986,6 +2006,7 @@
 
 =back
 
+
 =head3 STATISTICAL INFORMATION
 
 =over
@@ -2012,6 +2033,101 @@
 
 =back
 
+
+=head3 SUBSECOND STAT TIME ACCESS
+
+Both C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> functions can
+generally find access/modification and change times with subsecond time
+accuracy of the system supports it, but perl's built-in functions only
+return the integer part.
+
+The following functions return the timestamps of the most recent
+stat with subsecond precision on most systems and work both after
+C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> calls. Their return
+value is only meaningful after a successful C<stat>/C<lstat> call, or
+during/after a successful C<aio_stat>/C<aio_lstat> callback.
+
+This is similar to the L<Time::HiRes> C<stat> functions, but can return
+full resolution without rounding and work with standard perl C<stat>,
+alleviating the need to call the special C<Time::HiRes> functions, which
+do not act like their perl counterparts.
+
+On operating systems or file systems where subsecond time resolution is
+not supported or could not be detected, a fractional part of C<0> is
+returned, so it is always safe to call these functions.
+
+=over 4
+
+=item $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
+
+Return the access, modication, change or birth time, respectively,
+including fractional part. Due to the limited precision of floating point,
+the accuracy on most platforms is only a bit better than milliseconds
+for times around now - see the I<nsec> function family, below, for full
+accuracy.
+
+File birth time is only available when the OS and perl support it (on
+FreeBSD and NetBSD at the time of this writing, although support is
+adaptive, so if your OS/perl gains support, IO::AIO can take avdantage of
+it). On systems where it isn't available, C<0> is currently returned, but
+this might change to C<undef> in a future version.
+
+=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
+
+Returns access, modification, change and birth time all in one go, and
+maybe more times in the future version.
+
+=item $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
+
+Return the fractional access, modifcation, change or birth time, in nanoseconds,
+as an integer in the range C<0> to C<999999999>.
+
+Note that no accessors are provided for access, modification and
+change times - you need to get those from C<stat _> if required (C<int
+IO::AIO::st_atime> and so on will I<not> generally give you the correct
+value).
+
+=item $seconds = IO::AIO::st_btimesec
+
+The (integral) seconds part of the file birth time, if available.
+
+=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
+
+Like the functions above, but returns all four times in one go (and maybe
+more in future versions).
+
+=item $counter = IO::AIO::st_gen
+
+Returns the generation counter (in practice this is just a random number)
+of the file. This is only available on platforms which have this member in
+their C<struct stat> (most BSDs at the time of this writing) and generally
+only to the root usert. If unsupported, C<0> is returned, but this might
+change to C<undef> in a future version.
+
+=back
+
+Example: print the high resolution modification time of F</etc>, using
+C<stat>, and C<IO::AIO::aio_stat>.
+
+   if (stat "/etc") {
+      printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
+   }
+
+   IO::AIO::aio_stat "/etc", sub {
+      $_[0]
+         and return;
+
+      printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
+   };
+
+   IO::AIO::flush;
+
+Output of the awbove on my system, showing reduced and full accuracy:
+
+   stat(/etc) mtime: 1534043702.020808
+   aio_stat(/etc) mtime: 1534043702.020807792
+
+
 =head3 MISCELLANEOUS FUNCTIONS
 
 IO::AIO implements some functions that are useful when you want to use