expanded flock() docs

[p5sagit/p5-mst-13.2.git] / pod / perldata.pod

diff --git a/pod/perldata.pod b/pod/perldata.pod
index 7842039..407a252 100644 (file)
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -72,7 +72,7 @@ however, which don't have an initial special character.  You can't have
 a filehandle named "log", for instance.  Hint: you could say
 C<open(LOG,'logfile')> rather than C<open(log,'logfile')>.  Using uppercase
 filehandles also improves readability and protects you from conflict
-with future reserved words.)  Case I<IS> significant--"FOO", "Foo" and
+with future reserved words.)  Case I<IS> significant--"FOO", "Foo", and
 "foo" are all different names.  Names that start with a letter or
 underscore may also contain digits and underscores.
 
@@ -135,7 +135,7 @@ Scalar variables may contain various kinds of singular data, such as
 numbers, strings, and references.  In general, conversion from one form to
 another is transparent.  (A scalar may not contain multiple values, but
 may contain a reference to an array or hash containing multiple values.)
-Because of the automatic conversion of scalars, operations and functions
+Because of the automatic conversion of scalars, operations, and functions
 that return scalars don't need to care (and, in fact, can't care) whether
 the context is looking for a string or a number.
 
@@ -513,7 +513,7 @@ Note that just because a hash is initialized in that order doesn't
 mean that it comes out in that order.  See L<perlfunc/sort> for examples
 of how to arrange for an output ordering.
 
-=head2 Typeglobs
+=head2 Typeglobs and Filehandles
 
 Perl uses an internal type called a I<typeglob> to hold an entire
 symbol table entry.  The type prefix of a typeglob is a C<*>, because
@@ -522,7 +522,29 @@ pass arrays and hashes by reference into a function, but now that
 we have real references, this is seldom needed.  It also used to be the
 preferred way to pass filehandles into a function, but now
 that we have the *foo{THING} notation it isn't often needed for that,
-either.
+either.  It is still needed to pass new filehandles into functions
+(*HANDLE{IO} only works if HANDLE has already been used).
+
+If you need to use a typeglob to save away a filehandle, do it this way:
+
+    $fh = *STDOUT;
+
+or perhaps as a real reference, like this:
+
+    $fh = \*STDOUT;
+
+This is also a way to create a local filehandle.  For example:
+
+    sub newopen {
+       my $path = shift;
+       local *FH;  # not my!
+       open (FH, $path) || return undef;
+       return \*FH;
+    }
+    $fh = newopen('/etc/passwd');
+
+Another way to create local filehandles is with IO::Handle and its ilk,
+see the bottom of L<perlfunc/open()>.
 
 See L<perlref>, L<perlsub>, and L<perlmod/"Symbol Tables"> for more
 discussion on typeglobs.