called a B<filehandle>. A filehandle is an internal name for an external
file. It is the job of the C<open> function to make the association
between the internal name and the external name, and it is the job
-of the C<close> function to break that associations.
+of the C<close> function to break that association.
For your convenience, Perl sets up a few special filehandles that are
already open when you run. These include C<STDIN>, C<STDOUT>, C<STDERR>,
while (<ARGV>) { ... }
As you see from those examples, C<STDOUT> and C<STDERR> are output
-handles, and C<STDIN> and C<ARGV> are input handles. Those are
+handles, and C<STDIN> and C<ARGV> are input handles. They are
in all capital letters because they are reserved to Perl, much
like the C<@ARGV> array and the C<%ENV> hash are. Their external
associations were set up by your shell.
-For eveyrthing else, you will need to open it on your own. Although there
-are many other variants, the most common way to call Perl's open() function
+You will need to open every other filehandle on your own. Although there
+are many variants, the most common way to call Perl's open() function
is with three arguments and one return value:
C< I<OK> = open(I<HANDLE>, I<MODE>, I<PATHNAME>)>
my $handle = undef; # this will be filled in on success
open($handle, "< $encoding", $filename)
- || die "$0: can't open $filename for reading: $!\n";
+ || die "$0: can't open $filename for reading: $!";
As with the shell, in Perl the C<< "<" >> is used to open the file in
read-only mode. If it succeeds, Perl allocates a brand new filehandle for
$line = <$handle> // die "no input found";
-However, if hitting EOF is an expected and normal event, you
-would not to exit just because you ran out of input. Instead,
-you probably just want to exit an input loop. Immediately
-afterwards you can then test to see if there was an actual
-error that caused the loop to terminate, and act accordingly:
+However, if hitting EOF is an expected and normal event, you do not want to
+exit simply because you have run out of input. Instead, you probably just want
+to exit an input loop. You can then test to see if an actual error has caused
+the loop to terminate, and act accordingly:
while (<$handle>) {
# do something with data in $_
open mode:
open($handle, "<", $filename)
- || die "$0: can't open $filename for reading: $!\n";
+ || die "$0: can't open $filename for reading: $!";
But never use the bare C<< "<" >> without having set up a default encoding
first. Otherwise, Perl cannot know which of the many, many, many possible
=head2 Opening Text Files for Writing
-On the other hand, you want to write to a file, you first have to decide
-what to do about any existing contents. You have two basic choices here:
-to preserve or to clobber.
+When you want to write to a file, you first have to decide what to do about
+any existing contents of that file. You have two basic choices here: to
+preserve or to clobber.
-If you want to preserve any existing contents, then you want to open the
-file in append mode. As in the shell, in Perl you use C<<< ">>" >>> to
-open an existing file in append mode, and creates the file if it does not
+If you want to preserve any existing contents, then you want to open the file
+in append mode. As in the shell, in Perl you use C<<< ">>" >>> to open an
+existing file in append mode. C<<< ">>" >>> creates the file if it does not
already exist.
my $handle = undef;
my $encoding = ":encoding(UTF-8)";
open($handle, ">> $encoding", $filename)
- || die "$0: can't open $filename for appending: $!\n";
+ || die "$0: can't open $filename for appending: $!";
Now you can write to that filehandle using any of C<print>, C<printf>,
C<say>, C<write>, or C<syswrite>.
-The file does not have to exist just to open it in append mode. If the
-file did not previously exist, then the append-mode open creates it for
-you. But if the file does previously exist, its contents are safe from
-harm because you will be adding your new text past the end of the old text.
+As noted above, if the file does not already exist, then the append-mode open
+will create it for you. But if the file does already exist, its contents are
+safe from harm because you will be adding your new text past the end of the
+old text.
On the other hand, sometimes you want to clobber whatever might already be
there. To empty out a file before you start writing to it, you can open it
my $encoding = ":encoding(UTF-8)";
open($handle, "> $encoding", $filename)
- || die "$0: can't open $filename in write-open mode: $!\n";
+ || die "$0: can't open $filename in write-open mode: $!";
Here again Perl works just like the shell in that the C<< ">" >> clobbers
an existing file.
C<<< ">" >>> as needed:
open($handle, "< $encoding", $filename)
- || die "$0: can't open $filename for reading: $!\n";
+ || die "$0: can't open $filename for reading: $!";
open($handle, ">> $encoding", $filename)
- || die "$0: can't open $filename for appending: $!\n";
+ || die "$0: can't open $filename for appending: $!";
open($handle, "> $encoding", $filename)
- || die "$0: can't open $filename in write-open mode: $!\n";
+ || die "$0: can't open $filename in write-open mode: $!";
Alternately, you can change to binary mode on an existing handle this way:
You can also pass C<binmode> an explicit encoding to change it on the fly.
This isn't exactly "binary" mode, but we still use C<binmode> to do it:
- binmode(STDIN, ":encoding(MacRoman)") || die "cannot binmode STDIN";
- binmode(STDOUT, ":encoding(UTF-8)") || die "cannot binmode STDOUT";
+ binmode(STDIN, ":encoding(MacRoman)") || die "cannot binmode STDIN";
+ binmode(STDOUT, ":encoding(UTF-8)") || die "cannot binmode STDOUT";
Once you have your binary file properly opened in the right mode, you can
use all the same Perl I/O functions as you used on text files. However,
my($in_fh, $out_fh, $buffer);
- open($in_fh, "<", $name_in) || die "$0: cannot open $name_in for reading: $!";
- open($out_fh, ">", $name_out) || die "$0: cannot open $name_out for writing: $!";
+ open($in_fh, "<", $name_in)
+ || die "$0: cannot open $name_in for reading: $!";
+ open($out_fh, ">", $name_out)
+ || die "$0: cannot open $name_out for writing: $!";
for my $fh ($in_fh, $out_fh) {
binmode($fh) || die "binmode failed";
=head1 AUTHOR and COPYRIGHT
-To be announced.
-
-=head1 HISTORY
-
-To be announced.
+Copyright 2013 Tom Christiansen.
+This documentation is free; you can redistribute it and/or modify it under
+the same terms as Perl itself.
https://perl5.git.perl.org / perl5.git / blobdiff