--- IO-AIO/README	2005/07/20 21:55:38	1.7
+++ IO-AIO/README	2005/08/17 05:26:20	1.10
@@ -61,13 +61,21 @@
     error, unlike perl, which usually delivers "false") as it's sole
     argument when the given syscall has been executed asynchronously.
 
-    All functions that expect a filehandle will also accept a file
-    descriptor.
+    All functions expecting a filehandle keep a copy of the filehandle
+    internally until the request has finished.
 
-    The filenames you pass to these routines *must* be absolute. The reason
-    for this is that at the time the request is being executed, the current
-    working directory could have changed. Alternatively, you can make sure
-    that you never change the current working directory.
+    The pathnames you pass to these routines *must* be absolute and encoded
+    in byte form. The reason for the former is that at the time the request
+    is being executed, the current working directory could have changed.
+    Alternatively, you can make sure that you never change the current
+    working directory.
+
+    To encode pathnames to byte form, either make sure you either: a) always
+    pass in filenames you got from outside (command line, readdir etc.), b)
+    are ASCII or ISO 8859-1, c) use the Encode module and encode your
+    pathnames to the locale (or other) encoding in effect in the user
+    environment, d) use Glib::filename_from_unicode on unicode filenames or
+    e) use something else.
 
     aio_open $pathname, $flags, $mode, $callback
         Asynchronously open or create a file and call the callback with a
@@ -112,6 +120,10 @@
         the callback without the actual number of bytes read (or -1 on
         error, just like the syscall).
 
+        The $data scalar *MUST NOT* be modified in any way while the request
+        is outstanding. Modifying it can result in segfaults or WW3 (if the
+        necessary/optional hardware is installed).
+
         Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
         offset 0 within the scalar:
 
@@ -121,11 +133,6 @@
            };
 
     aio_readahead $fh,$offset,$length, $callback
-        Asynchronously reads the specified byte range into the page cache,
-        using the "readahead" syscall. If that syscall doesn't exist (likely
-        if your OS isn't Linux) the status will be -1 and $! is set to
-        "ENOSYS".
-
         "aio_readahead" populates the page cache with data from a file so
         that subsequent reads from that file will not block on disk I/O. The
         $offset argument specifies the starting point from which data is to
@@ -136,6 +143,10 @@
         read beyond the end of the file. The current file offset of the file
         is left unchanged.
 
+        If that syscall doesn't exist (likely if your OS isn't Linux) it
+        will be emulated by simply reading the data, which would have a
+        similar effect.
+
     aio_stat $fh_or_path, $callback
     aio_lstat $fh, $callback
         Works like perl's "stat" or "lstat" in void context. The callback
@@ -161,14 +172,20 @@
         Asynchronously unlink (delete) a file and call the callback with the
         result code.
 
+    aio_rmdir $pathname, $callback
+        Asynchronously rmdir (delete) a directory and call the callback with
+        the result code.
+
     aio_fsync $fh, $callback
         Asynchronously call fsync on the given filehandle and call the
         callback with the fsync result code.
 
     aio_fdatasync $fh, $callback
         Asynchronously call fdatasync on the given filehandle and call the
-        callback with the fdatasync result code. Might set $! to "ENOSYS" if
-        "fdatasync" is not available.
+        callback with the fdatasync result code.
+
+        If this call isn't available because your OS lacks it or it couldn't
+        be detected, it will be emulated by calling "fsync" instead.
 
   SUPPORT FUNCTIONS
     $fileno = IO::AIO::poll_fileno
@@ -259,6 +276,14 @@
 
         Under normal circumstances you don't need to call this function.
 
+  FORK BEHAVIOUR
+    Before the fork IO::AIO enters a quiescent state where no requests can
+    be added in other threads and no results will be processed. After the
+    fork the parent simply leaves the quiescent state and continues
+    request/result processing, while the child clears the request/result
+    queue and starts the same number of threads as were in use by the
+    parent.
+
 SEE ALSO
     Coro, Linux::AIO.