--- IO-AIO/AIO.pm	2018/02/20 04:32:59	1.281
+++ IO-AIO/AIO.pm	2018/02/20 05:23:47	1.282
@@ -2222,7 +2222,7 @@
    my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
       or die "pipe2: $!\n";
 
-=item $fh = IO::AIO::eventfd ([$initval, [$flags]])
+=item $fh = IO::AIO::eventfd [$initval, [$flags]]
 
 This is a direct interface to the Linux L<eventfd(2)> system call. The
 (unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
@@ -2235,6 +2235,73 @@
 The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
 C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
 
+Example: create a new eventfd filehandle:
+
+   $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC
+      or die "eventfd: $!\n";
+
+=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
+
+This is a direct interface to the Linux L<timerfd_create(2)> system call. The
+(unhelpful) default for C<$flags> is C<0>.
+
+On success, the new timerfd filehandle is returned, otherwise returns
+C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
+
+Please refer to L<timerfd_create(2)> for more info on this call.
+
+The following C<$clockid> values are
+available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
+C<IO::AIO::CLOCK_CLOCK_BOOTTIME> (Linux 3.15)
+C<IO::AIO::CLOCK_CLOCK_REALTIME_ALARM> (Linux 3.11) and
+C<IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM> (Linux 3.11).
+
+The following C<$flags> values are available (Linux
+2.6.27): C<IO::AIO::TFD_NONBLOCK> and C<IO::AIO::TFD_CLOEXEC>.
+
+Example: create a new timerfd and set it to one-second repeated alarms,
+then wait for two alarms:
+
+   my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
+      or die "timerfd_create: $!\n";
+
+   defined IO::AIO::timerfd_settime $fh, 0, 1, 1
+      or die "timerfd_settime: $!\n";
+
+   for (1..2) {
+      8 == sysread $fh, my $buf, 8
+         or die "timerfd read failure\n";
+
+      printf "number of expirations (likely 1): %d\n",
+         unpack "Q", $buf;
+   }
+
+=item ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
+
+This is a direct interface to the Linux L<timerfd_settime(2)> system
+call. Please refer to its manpage for more info on this call.
+
+The new itimerspec is specified using two (possibly fractional) second
+values, C<$new_interval> and C<$new_value>).
+
+On success, the current interval and value are returned (as per
+C<timerfd_gettime>). On failure, the empty list is returned.
+
+The following C<$flags> values are
+available: C<IO::AIO::TFD_TIMER_ABSTIME> and
+C<IO::AIO::TFD_TIMER_CANCEL_ON_SET>.
+
+See C<IO::AIO::timerfd_create> for a full example.
+
+=item ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
+
+This is a direct interface to the Linux L<timerfd_gettime(2)> system
+call. Please refer to its manpage for more info on this call.
+
+On success, returns the current values of interval and value for the given
+timerfd (as potentially fractional second values). On failure, the empty
+list is returned.
+
 =back
 
 =cut
@@ -2309,6 +2376,15 @@
 
 =back
 
+=head2 LINUX-SPECIFIC CALLS
+
+When a call is documented as "linux-specific" then this means it
+originated on GNU/Linux. C<IO::AIO> will usually try to autodetect the
+availability and compatibility of such calls regardless of the platform
+it is compiled on, so platforms such as FreeBSD which often implement
+these calls will work. When in doubt, call them and see if they fail wth
+C<ENOSYS>.
+
 =head2 MEMORY USAGE
 
 Per-request usage: