--- IO-AIO/README	2012/04/10 05:01:33	1.52
+++ IO-AIO/README	2012/10/11 03:20:52	1.53
@@ -148,8 +148,8 @@
 
 FUNCTIONS
   QUICK OVERVIEW
-    This section simply lists the prototypes of the most important functions
-    for quick reference. See the following sections for function-by-function
+    This section simply lists the prototypes most of the functions for quick
+    reference. See the following sections for function-by-function
     documentation.
 
        aio_wd $pathname, $callback->($wd)
@@ -167,6 +167,8 @@
        aio_chown $fh_or_path, $uid, $gid, $callback->($status)
        aio_chmod $fh_or_path, $mode, $callback->($status)
        aio_truncate $fh_or_path, $offset, $callback->($status)
+       aio_allocate $fh, $mode, $offset, $len, $callback->($status)
+       aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
        aio_unlink $pathname, $callback->($status)
        aio_mknod $pathname, $mode, $dev, $callback->($status)
        aio_link $srcpath, $dstpath, $callback->($status)
@@ -218,6 +220,8 @@
 
        IO::AIO::sendfile $ofh, $ifh, $offset, $count
        IO::AIO::fadvise $fh, $offset, $len, $advice
+       IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
+       IO::AIO::munmap $scalar
        IO::AIO::madvise $scalar, $offset, $length, $advice
        IO::AIO::mprotect $scalar, $offset, $length, $protect
        IO::AIO::munlock $scalar, $offset = 0, $length = undef
@@ -295,7 +299,8 @@
 
     aio_open $pathname, $flags, $mode, $callback->($fh)
         Asynchronously open or create a file and call the callback with a
-        newly created filehandle for the file.
+        newly created filehandle for the file (or "undef" in case of an
+        error).
 
         The pathname passed to "aio_open" must be absolute. See API NOTES,
         above, for an explanation.
@@ -527,6 +532,88 @@
               fsid    => 1810
            }
 
+        Here is a (likely partial) list of fsid values used by Linux - it is
+        safe to hardcode these when the $^O is "linux":
+
+           0x0000adf5 adfs
+           0x0000adff affs
+           0x5346414f afs
+           0x09041934 anon-inode filesystem
+           0x00000187 autofs
+           0x42465331 befs
+           0x1badface bfs
+           0x42494e4d binfmt_misc
+           0x9123683e btrfs
+           0x0027e0eb cgroupfs
+           0xff534d42 cifs
+           0x73757245 coda
+           0x012ff7b7 coh
+           0x28cd3d45 cramfs
+           0x453dcd28 cramfs-wend (wrong endianness)
+           0x64626720 debugfs
+           0x00001373 devfs
+           0x00001cd1 devpts
+           0x0000f15f ecryptfs
+           0x00414a53 efs
+           0x0000137d ext
+           0x0000ef53 ext2/ext3
+           0x0000ef51 ext2
+           0x00004006 fat
+           0x65735546 fuseblk
+           0x65735543 fusectl
+           0x0bad1dea futexfs
+           0x01161970 gfs2
+           0x47504653 gpfs
+           0x00004244 hfs
+           0xf995e849 hpfs
+           0x958458f6 hugetlbfs
+           0x2bad1dea inotifyfs
+           0x00009660 isofs
+           0x000072b6 jffs2
+           0x3153464a jfs
+           0x6b414653 k-afs
+           0x0bd00bd0 lustre
+           0x0000137f minix
+           0x0000138f minix 30 char names
+           0x00002468 minix v2
+           0x00002478 minix v2 30 char names
+           0x00004d5a minix v3
+           0x19800202 mqueue
+           0x00004d44 msdos
+           0x0000564c novell
+           0x00006969 nfs
+           0x6e667364 nfsd
+           0x00003434 nilfs
+           0x5346544e ntfs
+           0x00009fa1 openprom
+           0x7461636F ocfs2
+           0x00009fa0 proc
+           0x6165676c pstorefs
+           0x0000002f qnx4
+           0x858458f6 ramfs
+           0x52654973 reiserfs
+           0x00007275 romfs
+           0x67596969 rpc_pipefs
+           0x73636673 securityfs
+           0xf97cff8c selinux
+           0x0000517b smb
+           0x534f434b sockfs
+           0x73717368 squashfs
+           0x62656572 sysfs
+           0x012ff7b6 sysv2
+           0x012ff7b5 sysv4
+           0x01021994 tmpfs
+           0x15013346 udf
+           0x00011954 ufs
+           0x54190100 ufs byteswapped
+           0x00009fa2 usbdevfs
+           0x01021997 v9fs
+           0xa501fcf5 vxfs
+           0xabba1974 xenfs
+           0x012ff7b4 xenix
+           0x58465342 xfs
+           0x012fd16d xia
+
     aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
         Works like perl's "utime" function (including the special case of
         $atime and $mtime being undef). Fractional times are supported if
@@ -558,6 +645,20 @@
     aio_truncate $fh_or_path, $offset, $callback->($status)
         Works like truncate(2) or ftruncate(2).
 
+    aio_allocate $fh, $mode, $offset, $len, $callback->($status)
+        Allocates or freed disk space according to the $mode argument. See
+        the linux "fallocate" docuemntation for details.
+
+        $mode can currently be 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to
+        allocate space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
+        IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
+
+        The file system block size used by "fallocate" is presumably the
+        "f_bsize" returned by "statvfs".
+
+        If "fallocate" isn't available or cannot be emulated (currently no
+        emulation will be attempted), passes -1 and sets $! to "ENOSYS".
+
     aio_chmod $fh_or_path, $mode, $callback->($status)
         Works like perl's "chmod" function.
 
@@ -887,10 +988,10 @@
            aio_mlockall IO::AIO::MCL_FUTURE;
 
     aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
-        Queries the extents of the given file (by calling the Linux FIEMAP
+        Queries the extents of the given file (by calling the Linux "FIEMAP"
         ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
-        details). If the "ioctl" is not available on your OS, then this
-        rquiest will fail with "ENOSYS".
+        details). If the ioctl is not available on your OS, then this
+        request will fail with "ENOSYS".
 
         $start is the starting offset to query extents for, $length is the
         size of the range to query - if it is "undef", then the whole file
@@ -902,9 +1003,10 @@
         query the data portion.
 
         $count is the maximum number of extent records to return. If it is
-        "undef", then IO::AIO queries all extents of the file. As a very
+        "undef", then IO::AIO queries all extents of the range. As a very
         special case, if it is 0, then the callback receives the number of
-        extents instead of the extents themselves.
+        extents instead of the extents themselves (which is unreliable, see
+        below).
 
         If an error occurs, the callback receives no arguments. The special
         "errno" value "IO::AIO::EBADR" is available to test for flag errors.
@@ -916,7 +1018,7 @@
            [$logical, $physical, $length, $flags]
 
         Flags is any combination of the following flag values (typically
-        either 0 or "IO::AIO::FIEMAP_EXTENT_LAST"):
+        either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
 
         "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
         "IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
@@ -927,6 +1029,12 @@
         "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
         or "IO::AIO::FIEMAP_EXTENT_SHARED".
 
+        At the time of this writing (Linux 3.2), this requets is unreliable
+        unless $count is "undef", as the kernel has all sorts of bugs
+        preventing it to return all extents of a range for files with large
+        number of extents. The code works around all these issues if $count
+        is undef.
+
     aio_group $callback->(...)
         This is a very special aio request: Instead of doing something, it
         is a container for other aio requests, which is useful if you want
@@ -1476,7 +1584,8 @@
 
     IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
         Memory-maps a file (or anonymous memory range) and attaches it to
-        the given $scalar, which will act like a string scalar.
+        the given $scalar, which will act like a string scalar. Returns true
+        on success, and false otherwise.
 
         The only operations allowed on the scalar are "substr"/"vec" that
         don't change the string length, and most read-only operations such
@@ -1542,6 +1651,9 @@
         $w_off are "undef", then "NULL" is passed for these, otherwise they
         should be the file offset.
 
+        $r_fh and $w_fh should not refer to the same file, as splice might
+        silently corrupt the data in this case.
+
         The following symbol flag values are available:
         "IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
         "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".