From: Ed Avis Date: Tue, 16 Jul 2013 01:17:34 +0000 (+1000) Subject: [perl #117223] Remove IO::File example from perlfunc X-Git-Tag: upstream/5.20.0~2668 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=1578dcc9a6e07f8598ff065b64e15481aa6152d0;p=platform%2Fupstream%2Fperl.git [perl #117223] Remove IO::File example from perlfunc updated to apply to blead, minor spelling and word wrap fixes by Tony Cook. --- diff --git a/AUTHORS b/AUTHORS index 1037f96..1c3e9fe 100644 --- a/AUTHORS +++ b/AUTHORS @@ -345,6 +345,7 @@ Drew Stephens Duke Leto Duncan Findlay E. Choroba +Ed Avis Ed Mooring Ed Santiago Eddy Tan diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 18ecd40..129012c 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -3909,12 +3909,6 @@ FILEHANDLE is an expression, its value is the real filehandle. (This is considered a symbolic reference, so C should I be in effect.) -If EXPR is omitted, the global (package) scalar variable of the same -name as the FILEHANDLE contains the filename. (Note that lexical -variables--those declared with C or C--will not work for this -purpose; so if you're using C or C, specify EXPR in your -call to open.) - If three (or more) arguments are specified, the open mode (including optional encoding) in the second argument are distinct from the filename in the third. If MODE is C<< < >> or nothing, the file is opened for input. @@ -3997,6 +3991,33 @@ where you want to format a suitable error message (but there are modules that can help with that problem)) always check the return value from opening a file. +The filehandle will be closed when its reference count reaches zero. +If it is a lexically scoped variable declared with C, that usually +means the end of the enclosing scope. However, this automatic close +does not check for errors, so it is better to explicitly close +filehandles, especially those used for writing: + + close($handle) + || warn "close failed: $!"; + +An older style is to use a bareword as the filehandle, as + + open(FH, "<", "input.txt") + or die "cannot open < input.txt: $!"; + +Then you can use C as the filehandle, in C<< close FH >> and C<< + >> and so on. Note that it's a global variable, so this form is +not recommended in new code. + +As a shortcut a one-argument call takes the filename from the global +scalar variable of the same name as the filehandle: + + $ARTICLE = 100; + open(ARTICLE) or die "Can't find article $ARTICLE: $!\n"; + +Here C<$ARTICLE> must be a global (package) scalar variable - not one +declared with C or C. + As a special case the three-argument form with a read/write mode and the third argument being C: @@ -4021,10 +4042,6 @@ To (re)open C or C as an in-memory file, close it first: General examples: - $ARTICLE = 100; - open(ARTICLE) or die "Can't find article $ARTICLE: $!\n"; - while (
) {... - open(LOG, ">>/usr/spool/news/twitlog"); # (log is reserved) # if the open fails, output is discarded @@ -4269,34 +4286,6 @@ interpretation. For example: seek(HANDLE, 0, 0); print "File contains: ", ; -Using the constructor from the C package (or one of its -subclasses, such as C or C), you can generate anonymous -filehandles that have the scope of the variables used to hold them, then -automatically (but silently) close once their reference counts become -zero, typically at scope exit: - - use IO::File; - #... - sub read_myfile_munged { - my $ALL = shift; - # or just leave it undef to autoviv - my $handle = IO::File->new; - open($handle, "<", "myfile") or die "myfile: $!"; - $first = <$handle> - or return (); # Automatically closed here. - mung($first) or die "mung failed"; # Or here. - return (first, <$handle>) if $ALL; # Or here. - return $first; # Or here. - } - -B The previous example has a bug because the automatic -close that happens when the refcount on C reaches zero does not -properly detect and report failures. I close the handle -yourself and inspect the return value. - - close($handle) - || warn "close failed: $!"; - See L for some details about mixing reading and writing. Portability issues: L.