1 files changed, 49 insertions, 0 deletions
diff --git a/lib/FileHandle.pm b/lib/FileHandle.pm
index c45f446667..9408717a7c 100644
--- a/lib/FileHandle.pm
+++ b/lib/FileHandle.pm
@@ -2,6 +2,55 @@ package FileHandle;
 
 # Note that some additional FileHandle methods are defined in POSIX.pm.
 
+=head1 NAME 
+
+FileHandle - supply object methods for filehandles
+
+cacheout - keep more files open than the system permits
+
+=head1 SYNOPSIS
+
+    use FileHandle;
+    autoflush STDOUT 1;
+
+    cacheout($path);
+    print $path @data;
+
+=head1 DESCRIPTION
+
+See L<perlvar> for complete descriptions of each of the following supported C<FileHandle> 
+methods:
+
+    print
+    autoflush
+    output_field_separator
+    output_record_separator
+    input_record_separator
+    input_line_number
+    format_page_number
+    format_lines_per_page
+    format_lines_left
+    format_name
+    format_top_name
+    format_line_break_characters
+    format_formfeed
+
+The cacheout() function will make sure that there's a filehandle
+open for writing available as the pathname you give it.  It automatically
+closes and re-opens files if you exceed your system file descriptor maximum.
+
+=head1 BUGS
+
+F<sys/param.h> lies with its C<NOFILE> define on some systems,
+so you may have to set $cacheout::maxopen yourself.
+
+Due to backwards compatibility, all filehandles resemble objects
+of class C<FileHandle>, or actually classes derived from that class.
+They actually aren't.  Which means you can't derive your own 
+class from C<FileHandle> and inherit those methods.
+
+=cut
+
 require 5.000;
 use English;
 use Exporter;