--- AnyEvent/lib/AnyEvent.pm	2009/07/06 23:32:49	1.226
+++ 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 >>
@@ -1485,6 +1508,13 @@
 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