--- AnyEvent/lib/AnyEvent.pm	2009/07/03 21:44:14	1.224
+++ AnyEvent/lib/AnyEvent.pm	2009/07/08 01:11:12	1.228
@@ -178,9 +178,9 @@
 You can create an I/O watcher by calling the C<< AnyEvent->io >> method
 with the following mandatory key-value pairs as arguments:
 
-C<fh> is the Perl I<file handle> (I<not> file descriptor) to watch
-for events (AnyEvent might or might not keep a reference to this file
-handle). Note that only file handles pointing to things for which
+C<fh> is the Perl I<file handle> (I<not> file descriptor, see below) to
+watch for events (AnyEvent might or might not keep a reference to this
+file handle). Note that only file handles pointing to things for which
 non-blocking operation makes sense are allowed. This includes sockets,
 most character devices, pipes, fifos and so on, but not for example files
 or block devices.
@@ -211,6 +211,29 @@
       undef $w;
    });
 
+=head3 GETTING A FILE HANDLE FROM A FILE DESCRIPTOR
+
+It is not uncommon to only have a file descriptor, while AnyEvent requires
+a Perl file handle.
+
+There are basically two methods to convert a file descriptor into a file handle. If you own
+the file descriptor, you can open it with C<&=>, as in:
+
+   open my $fh, "<&=$fileno" or die "xxx: §!";
+
+This will "own" the file descriptor, meaning that when C<$fh> is
+destroyed, it will automatically close the C<$fileno>. Also, note that
+the open mode (read, write, read/write) must correspond with how the
+underlying file descriptor was opened.
+
+In many cases, taking over the file descriptor is now what you want, in
+which case the only alternative is to dup the file descriptor:
+
+   open my $fh, "<&$fileno" or die "xxx: $!";
+
+This has the advantage of not closing the file descriptor and the
+disadvantage of making a slow copy.
+
 =head2 TIME WATCHERS
 
 You can create a time watcher by calling the C<< AnyEvent->timer >>
@@ -970,7 +993,7 @@
 
 use Carp;
 
-our $VERSION = 4.452;
+our $VERSION = 4.8;
 our $MODEL;
 
 our $AUTOLOAD;
@@ -1473,6 +1496,25 @@
 The maximum number of child processes that C<AnyEvent::Util::fork_call>
 will create in parallel.
 
+=item C<PERL_ANYEVENT_MAX_OUTSTANDING_DNS>
+
+The default value for the C<max_outstanding> parameter for the default DNS
+resolver - this is the maximum number of parallel DNS requests that are
+sent to the DNS server.
+
+=item C<PERL_ANYEVENT_RESOLV_CONF>
+
+The file to use instead of F</etc/resolv.conf> (or OS-specific
+configuration) in the default resolver. When set to the empty string, no
+default config will be used.
+
+=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
+
+When neither C<ca_file> nor C<ca_path> was specified during
+L<AnyEvent::TLS> context creation, and either of these environment
+variables exist, they will be used to specify CA certificate locations
+instead of a system-dependent default.
+
 =back
 
 =head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE