--- IO-AIO/AIO.pm	2007/06/01 05:51:21	1.106
+++ IO-AIO/AIO.pm	2007/09/20 17:05:22	1.114
@@ -64,12 +64,11 @@
 on a RAID volume or over NFS when you do a number of stat operations
 concurrently.
 
-While most of this works on all types of file descriptors (for example
-sockets), using these functions on file descriptors that support
-nonblocking operation (again, sockets, pipes etc.) is very inefficient or
-might not work (aio_read fails on sockets/pipes/fifos). Use an event loop
-for that (such as the L<Event|Event> module): IO::AIO will naturally fit
-into such an event loop itself.
+While most of this works on all types of file descriptors (for
+example sockets), using these functions on file descriptors that
+support nonblocking operation (again, sockets, pipes etc.) is very
+inefficient. Use an event loop for that (such as the L<Event|Event>
+module): IO::AIO will naturally fit into such an event loop itself.
 
 In this version, a number of threads are started that execute your
 requests and signal their completion. You don't need thread support
@@ -81,10 +80,10 @@
 aio_write, so the remaining functionality would have to be implemented
 using threads anyway.
 
-Although the module will work with in the presence of other (Perl-)
-threads, it is currently not reentrant in any way, so use appropriate
-locking yourself, always call C<poll_cb> from within the same thread, or
-never call C<poll_cb> (or other C<aio_> functions) recursively.
+Although the module will work in the presence of other (Perl-) threads,
+it is currently not reentrant in any way, so use appropriate locking
+yourself, always call C<poll_cb> from within the same thread, or never
+call C<poll_cb> (or other C<aio_> functions) recursively.
 
 =head2 EXAMPLE
 
@@ -198,7 +197,7 @@
                      aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
                      aio_readlink aio_fsync aio_fdatasync aio_readahead aio_rename aio_link
                      aio_move aio_copy aio_group aio_nop aio_mknod aio_load aio_rmtree aio_mkdir
-                     aio_chown aio_chmod aio_utime);
+                     aio_chown aio_chmod aio_utime aio_truncate);
    our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice aio_block));
    our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
                        min_parallel max_parallel max_idle
@@ -327,14 +326,23 @@
 
 =item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
 
-Reads or writes C<length> bytes from the specified C<fh> and C<offset>
-into the scalar given by C<data> and offset C<dataoffset> and calls the
+Reads or writes C<$length> bytes from the specified C<$fh> and C<$offset>
+into the scalar given by C<$data> and offset C<$dataoffset> and calls the
 callback without the actual number of bytes read (or -1 on error, just
 like the syscall).
 
+If C<$offset> is undefined, then the current file descriptor offset will
+be used (and updated), otherwise the file descriptor offset will not be
+changed by these calls.
+
+If C<$length> is undefined in C<aio_write>, use the remaining length of C<$data>.
+
+If C<$dataoffset> is less than zero, it will be counted from the end of
+C<$data>.
+
 The C<$data> scalar I<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).
+is outstanding. Modifying it can result in segfaults or World War III (if
+the necessary/optional hardware is installed).
 
 Example: Read 15 bytes at offset 7 into scalar C<$buffer>, starting at
 offset C<0> within the scalar:
@@ -419,7 +427,7 @@
 
 Examples:
 
-   # set atime and mtime to current time:
+   # set atime and mtime to current time (basically touch(1)):
    aio_utime "path", undef, undef;
    # set atime to current time and mtime to beginning of the epoch:
    aio_utime "path", time, undef; # undef==0
@@ -438,6 +446,11 @@
    aio_chown "path", 0, undef;
 
 
+=item aio_truncate $fh_or_path, $offset, $callback->($status)
+
+Works like truncate(2) or ftruncate(2).
+
+
 =item aio_chmod $fh_or_path, $mode, $callback->($status)
 
 Works like perl's C<chmod> function.
@@ -1196,7 +1209,7 @@
 use an C<aio_group> together with a feed callback.
 
 Sets the maximum number of outstanding requests to C<$nreqs>. If you
-to queue up more than this number of requests, the next call to the
+do queue up more than this number of requests, the next call to the
 C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
 function will block until the limit is no longer exceeded.
 
@@ -1285,7 +1298,7 @@
 scalars and other data passed into aio requests will also be locked and
 will consume memory till the request has entered the done state.
 
-This is now awfully much, so queuing lots of requests is not usually a
+This is not awfully much, so queuing lots of requests is not usually a
 problem.
 
 Per-thread usage: