=head1 NAME
-perlfaq5 - Files and Formats ($Revision: 7875 $)
+perlfaq5 - Files and Formats
=head1 DESCRIPTION
=head2 How do I flush/unbuffer an output filehandle? Why must I do this?
X<flush> X<buffer> X<unbuffer> X<autoflush>
-Perl does not support truly unbuffered output (except
-insofar as you can C<syswrite(OUT, $char, 1)>), although it
-does support is "command buffering", in which a physical
-write is performed after every output command.
-
-The C standard I/O library (stdio) normally buffers
-characters sent to devices so that there isn't a system call
-for each byte. In most stdio implementations, the type of
-output buffering and the size of the buffer varies according
-to the type of device. Perl's print() and write() functions
-normally buffer output, while syswrite() bypasses buffering
-all together.
-
-If you want your output to be sent immediately when you
-execute print() or write() (for instance, for some network
-protocols), you must set the handle's autoflush flag. This
-flag is the Perl variable $| and when it is set to a true
-value, Perl will flush the handle's buffer after each
-print() or write(). Setting $| affects buffering only for
-the currently selected default file handle. You choose this
-handle with the one argument select() call (see
-L<perlvar/$E<verbar>> and L<perlfunc/select>).
-
-Use select() to choose the desired handle, then set its
-per-filehandle variables.
-
- $old_fh = select(OUTPUT_HANDLE);
- $| = 1;
- select($old_fh);
+(contributed by brian d foy)
-Some modules offer object-oriented access to handles and their
-variables, although they may be overkill if this is the only
-thing you do with them. You can use IO::Handle:
+You might like to read Mark Jason Dominus's "Suffering From Buffering"
+at http://perl.plover.com/FAQs/Buffering.html .
- use IO::Handle;
- open(DEV, ">/dev/printer"); # but is this?
- DEV->autoflush(1);
+Perl normally buffers output so it doesn't make a system call for every
+bit of output. By saving up output, it makes fewer expensive system calls.
+For instance, in this little bit of code, you want to print a dot to the
+screen for every line you process to watch the progress of your program.
+Instead of seeing a dot for every line, Perl buffers the output and you
+have a long wait before you see a row of 50 dots all at once:
+
+ # long wait, then row of dots all at once
+ while( <> ) {
+ print ".";
+ print "\n" unless ++$count % 50;
+
+ #... expensive line processing operations
+ }
+
+To get around this, you have to unbuffer the output filehandle, in this
+case, C<STDOUT>. You can set the special variable C<$|> to a true value
+(mnemonic: making your filehandles "piping hot"):
+
+ $|++;
+
+ # dot shown immediately
+ while( <> ) {
+ print ".";
+ print "\n" unless ++$count % 50;
+
+ #... expensive line processing operations
+ }
+
+The C<$|> is one of the per-filehandle special variables, so each
+filehandle has its own copy of its value. If you want to merge
+standard output and standard error for instance, you have to unbuffer
+each (although STDERR might be unbuffered by default):
+
+ {
+ my $previous_default = select(STDOUT); # save previous default
+ $|++; # autoflush STDOUT
+ select(STDERR);
+ $|++; # autoflush STDERR, to be sure
+ select($previous_default); # restore previous default
+ }
-or IO::Socket:
+ # now should alternate . and +
+ while( 1 )
+ {
+ sleep 1;
+ print STDOUT ".";
+ print STDERR "+";
+ print STDOUT "\n" unless ++$count % 25;
+ }
+
+Besides the C<$|> special variable, you can use C<binmode> to give
+your filehandle a C<:unix> layer, which is unbuffered:
- use IO::Socket; # this one is kinda a pipe?
- my $sock = IO::Socket::INET->new( 'www.example.com:80' );
+ binmode( STDOUT, ":unix" );
+
+ while( 1 ) {
+ sleep 1;
+ print ".";
+ print "\n" unless ++$count % 50;
+ }
- $sock->autoflush();
+For more information on output layers, see the entries for C<binmode>
+and C<open> in L<perlfunc>, and the C<PerlIO> module documentation.
+
+If you are using C<IO::Handle> or one of its subclasses, you can
+call the C<autoflush> method to change the settings of the
+filehandle:
+
+ use IO::Handle;
+ open my( $io_fh ), ">", "output.txt";
+ $io_fh->autoflush(1);
+
+The C<IO::Handle> objects also have a C<flush> method. You can flush
+the buffer any time you want without auto-buffering
+
+ $io_fh->flush;
=head2 How do I change, delete, or insert a line in a file, or append to the beginning of a file?
X<file, editing>
open my $in, '<', $file or die "Can't read old file: $!";
open my $out, '>', "$file.new" or die "Can't write new file: $!";
- print "# Add this line to the top\n"; # <--- HERE'S THE MAGIC
+ print $out "# Add this line to the top\n"; # <--- HERE'S THE MAGIC
while( <$in> )
{
open my $in, '<', $file or die "Can't read old file: $!";
open my $out, '>', "$file.new" or die "Can't write new file: $!";
- print "# Add this line to the top\n";
+ print $out "# Add this line to the top\n";
while( <$in> )
{
close $out;
To change only a particular line, the input line number, C<$.>, is
-useful. Use C<next> to skip all lines up to line 5, make a change and
-print the result, then stop further processing with C<last>.
+useful. First read and print the lines up to the one you want to
+change. Next, read the single line you want to change, change it, and
+print it. After that, read the rest of the lines and print those:
- while( <$in> )
+ while( <$in> ) # print the lines before the change
+ {
+ print $out $_;
+ last if $. == 4; # line number before change
+ }
+
+ my $line = <$in>;
+ $line =~ s/\b(perl)\b/Perl/g;
+ print $out $line;
+
+ while( <$in> ) # print the rest of the lines
{
- next unless $. == 5;
- s/\b(perl)\b/Perl/g;
print $out $_;
- last;
}
To skip lines, use the looping controls. The C<next> in this example
C<.c.orig> file.
=head2 How can I copy a file?
-X<copy> X<file, copy>
+X<copy> X<file, copy> X<File::Copy>
(contributed by brian d foy)
-Use the File::Copy module. It comes with Perl and can do a
+Use the C<File::Copy> module. It comes with Perl and can do a
true copy across file systems, and it does its magic in
a portable fashion.
copy( $original, $new_copy ) or die "Copy failed: $!";
-If you can't use File::Copy, you'll have to do the work yourself:
+If you can't use C<File::Copy>, you'll have to do the work yourself:
open the original file, open the destination file, then print
-to the destination file as you read the original.
+to the destination file as you read the original. You also have to
+remember to copy the permissions, owner, and group to the new file.
=head2 How do I make a temporary file name?
X<file, temporary>
If you don't need to know the name of the file, you can use C<open()>
-with C<undef> in place of the file name. The C<open()> function
-creates an anonymous temporary file.
+with C<undef> in place of the file name. In Perl 5.8 or later, the
+C<open()> function creates an anonymous temporary file:
open my $tmp, '+>', undef or die $!;
BEGIN {
use Fcntl;
my $temp_dir = -d '/tmp' ? '/tmp' : $ENV{TMPDIR} || $ENV{TEMP};
- my $base_name = sprintf("%s/%d-%d-0000", $temp_dir, $$, time());
+ my $base_name = sprintf "%s/%d-%d-0000", $temp_dir, $$, time;
sub temp_file {
local *FH;
my $count = 0;
- until (defined(fileno(FH)) || $count++ > 100) {
- $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e;
- # O_EXCL is required for security reasons.
- sysopen(FH, $base_name, O_WRONLY|O_EXCL|O_CREAT);
+ until( defined(fileno(FH)) || $count++ > 100 ) {
+ $base_name =~ s/-(\d+)$/"-" . (1 + $1)/e;
+ # O_EXCL is required for security reasons.
+ sysopen FH, $base_name, O_WRONLY|O_EXCL|O_CREAT;
+ }
+
+ if( defined fileno(FH) ) {
+ return (*FH, $base_name);
+ }
+ else {
+ return ();
+ }
}
- if (defined(fileno(FH))
- return (*FH, $base_name);
- }
- else {
- return ();
- }
- }
}
=head2 How can I manipulate fixed-record-length files?
=head2 How can I write() into a string?
X<write, into a string>
-See L<perlform/"Accessing Formatting Internals"> for an swrite() function.
+See L<perlform/"Accessing Formatting Internals"> for an C<swrite()> function.
+
+=head2 How can I open a filehandle to a string?
+X<string> X<open> X<IO::String> X<filehandle>
+
+(contributed by Peter J. Holzer, hjp-usenet2@hjp.at)
+
+Since Perl 5.8.0 a file handle referring to a string can be created by
+calling open with a reference to that string instead of the filename.
+This file handle can then be used to read from or write to the string:
+
+ open(my $fh, '>', \$string) or die "Could not open string for writing";
+ print $fh "foo\n";
+ print $fh "bar\n"; # $string now contains "foo\nbar\n"
+
+ open(my $fh, '<', \$string) or die "Could not open string for reading";
+ my $x = <$fh>; # $x now contains "foo\n"
+
+With older versions of Perl, the C<IO::String> module provides similar
+functionality.
=head2 How can I output my numbers with commas added?
X<number, commify>
=head2 How can I translate tildes (~) in a filename?
X<tilde> X<tilde expansion>
-Use the <> (glob()) operator, documented in L<perlfunc>. Older
-versions of Perl require that you have a shell installed that groks
-tildes. Recent perl versions have this feature built in. The
-File::KGlob module (available from CPAN) gives more portable glob
-functionality.
+Use the E<lt>E<gt> (C<glob()>) operator, documented in L<perlfunc>.
+Versions of Perl older than 5.6 require that you have a shell
+installed that groks tildes. Later versions of Perl have this feature
+built in. The C<File::KGlob> module (available from CPAN) gives more
+portable glob functionality.
Within Perl, you may use this directly:
Unless you have a particular reason to use the two argument form you
should use the three argument form of open() which does not treat any
-charcters in the filename as special.
+characters in the filename as special.
open FILE, "<", " file "; # filename is " file "
open FILE, ">", ">file"; # filename is ">file"
except that lamentably, file creation (and deletion) is not atomic
over NFS, so this won't work (at least, not every time) over the net.
Various schemes involving link() have been suggested, but
-these tend to involve busy-wait, which is also subdesirable.
+these tend to involve busy-wait, which is also less than desirable.
=head2 I still don't get locking. I just want to increment the number in the file. How can I do this?
X<counter> X<file, counter>
=head2 All I want to do is append a small amount of text to the end of a file. Do I still have to use locking?
X<append> X<file, append>
-If you are on a system that correctly implements flock() and you use the
-example appending code from "perldoc -f flock" everything will be OK
-even if the OS you are on doesn't implement append mode correctly (if
-such a system exists.) So if you are happy to restrict yourself to OSs
-that implement flock() (and that's not really much of a restriction)
-then that is what you should do.
+If you are on a system that correctly implements C<flock> and you use
+the example appending code from "perldoc -f flock" everything will be
+OK even if the OS you are on doesn't implement append mode correctly
+(if such a system exists.) So if you are happy to restrict yourself to
+OSs that implement C<flock> (and that's not really much of a
+restriction) then that is what you should do.
If you know you are only going to use a system that does correctly
-implement appending (i.e. not Win32) then you can omit the seek() from
-the above code.
-
-If you know you are only writing code to run on an OS and filesystem that
-does implement append mode correctly (a local filesystem on a modern
-Unix for example), and you keep the file in block-buffered mode and you
-write less than one buffer-full of output between each manual flushing
-of the buffer then each bufferload is almost guaranteed to be written to
-the end of the file in one chunk without getting intermingled with
-anyone else's output. You can also use the syswrite() function which is
-simply a wrapper around your systems write(2) system call.
+implement appending (i.e. not Win32) then you can omit the C<seek>
+from the code in the previous answer.
+
+If you know you are only writing code to run on an OS and filesystem
+that does implement append mode correctly (a local filesystem on a
+modern Unix for example), and you keep the file in block-buffered mode
+and you write less than one buffer-full of output between each manual
+flushing of the buffer then each bufferload is almost guaranteed to be
+written to the end of the file in one chunk without getting
+intermingled with anyone else's output. You can also use the
+C<syswrite> function which is simply a wrapper around your system's
+C<write(2)> system call.
There is still a small theoretical chance that a signal will interrupt
-the system level write() operation before completion. There is also a
-possibility that some STDIO implementations may call multiple system
-level write()s even if the buffer was empty to start. There may be some
-systems where this probability is reduced to zero.
+the system level C<write()> operation before completion. There is also
+a possibility that some STDIO implementations may call multiple system
+level C<write()>s even if the buffer was empty to start. There may be
+some systems where this probability is reduced to zero, and this is
+not a concern when using C<:perlio> instead of your system's STDIO.
=head2 How do I randomly update a binary file?
X<file, binary patch>
use File::Slurp;
$all_of_it = read_file($filename); # entire file in scalar
- @all_lines = read_file($filename); # one line perl element
+ @all_lines = read_file($filename); # one line per element
The customary Perl approach for processing all the lines in a file is to
do so one line at a time:
Error checking, as always, has been left as an exercise for the reader.
=head2 How do I close a file descriptor by number?
-X<file, closing file descriptors>
+X<file, closing file descriptors> X<POSIX> X<close>
+
+If, for some reason, you have a file descriptor instead of a
+filehandle (perhaps you used C<POSIX::open>), you can use the
+C<close()> function from the C<POSIX> module:
+
+ use POSIX ();
+
+ POSIX::close( $fd );
-This should rarely be necessary, as the Perl close() function is to be
+This should rarely be necessary, as the Perl C<close()> function is to be
used for things that Perl opened itself, even if it was a dup of a
-numeric descriptor as with MHCONTEXT above. But if you really have
+numeric descriptor as with C<MHCONTEXT> above. But if you really have
to, you may be able to do this:
require 'sys/syscall.ph';
$rc = syscall(&SYS_close, $fd + 0); # must force numeric
die "can't sysclose $fd: $!" unless $rc == -1;
-Or, just use the fdopen(3S) feature of open():
+Or, just use the fdopen(3S) feature of C<open()>:
{
- local *F;
- open F, "<&=$fd" or die "Cannot reopen fd=$fd: $!";
- close F;
+ open my( $fh ), "<&=$fd" or die "Cannot reopen fd=$fd: $!";
+ close $fh;
}
=head2 Why can't I use "C:\temp\foo" in DOS paths? Why doesn't `C:\temp\foo.exe` work?
=head2 How do I select a random line from a file?
X<file, selecting a random line>
-Here's an algorithm from the Camel Book:
+Short of loading the file into a database or pre-indexing the lines in
+the file, there are a couple of things that you can do.
+
+Here's a reservoir-sampling algorithm from the Camel Book:
srand;
rand($.) < 1 && ($line = $_) while <>;
in. You can find a proof of this method in I<The Art of Computer
Programming>, Volume 2, Section 3.4.2, by Donald E. Knuth.
-You can use the File::Random module which provides a function
+You can use the C<File::Random> module which provides a function
for that algorithm:
use File::Random qw/random_line/;
my $line = random_line($filename);
-Another way is to use the Tie::File module, which treats the entire
+Another way is to use the C<Tie::File> module, which treats the entire
file as an array. Simply access a random array element.
=head2 Why do I get weird spaces when I print an array of lines?
-Saying
+(contributed by brian d foy)
+
+If you are seeing spaces between the elements of your array when
+you print the array, you are probably interpolating the array in
+double quotes:
+
+ my @animals = qw(camel llama alpaca vicuna);
+ print "animals are: @animals\n";
+
+It's the double quotes, not the C<print>, doing this. Whenever you
+interpolate an array in a double quote context, Perl joins the
+elements with spaces (or whatever is in C<$">, which is a space by
+default):
- print "@lines\n";
+ animals are: camel llama alpaca vicuna
-joins together the elements of C<@lines> with a space between them.
-If C<@lines> were C<("little", "fluffy", "clouds")> then the above
-statement would print
+This is different than printing the array without the interpolation:
- little fluffy clouds
+ my @animals = qw(camel llama alpaca vicuna);
+ print "animals are: ", @animals, "\n";
-but if each element of C<@lines> was a line of text, ending a newline
-character C<("little\n", "fluffy\n", "clouds\n")> then it would print:
+Now the output doesn't have the spaces between the elements because
+the elements of C<@animals> simply become part of the list to
+C<print>:
- little
- fluffy
- clouds
+ animals are: camelllamaalpacavicuna
-If your array contains lines, just print them:
+You might notice this when each of the elements of C<@array> end with
+a newline. You expect to print one element per line, but notice that
+every line after the first is indented:
+
+ this is a line
+ this is another line
+ this is the third line
+
+That extra space comes from the interpolation of the array. If you
+don't want to put anything between your array elements, don't use the
+array in double quotes. You can send it to print without them:
print @lines;
+=head2 How do I traverse a directory tree?
+
+(contributed by brian d foy)
+
+The C<File::Find> module, which comes with Perl, does all of the hard
+work to traverse a directory structure. It comes with Perl. You simply
+call the C<find> subroutine with a callback subroutine and the
+directories you want to traverse:
+
+ use File::Find;
+
+ find( \&wanted, @directories );
+
+ sub wanted {
+ # full path in $File::Find::name
+ # just filename in $_
+ ... do whatever you want to do ...
+ }
+
+The C<File::Find::Closures>, which you can download from CPAN, provides
+many ready-to-use subroutines that you can use with C<File::Find>.
+
+The C<File::Finder>, which you can download from CPAN, can help you
+create the callback subroutine using something closer to the syntax of
+the C<find> command-line utility:
+
+ use File::Find;
+ use File::Finder;
+
+ my $deep_dirs = File::Finder->depth->type('d')->ls->exec('rmdir','{}');
+
+ find( $deep_dirs->as_options, @places );
+
+The C<File::Find::Rule> module, which you can download from CPAN, has
+a similar interface, but does the traversal for you too:
+
+ use File::Find::Rule;
+
+ my @files = File::Find::Rule->file()
+ ->name( '*.pm' )
+ ->in( @INC );
+
+=head2 How do I delete a directory tree?
+
+(contributed by brian d foy)
+
+If you have an empty directory, you can use Perl's built-in C<rmdir>. If
+the directory is not empty (so, no files or subdirectories), you either
+have to empty it yourself (a lot of work) or use a module to help you.
+
+The C<File::Path> module, which comes with Perl, has a C<rmtree> which
+can take care of all of the hard work for you:
+
+ use File::Path qw(rmtree);
+
+ rmtree( \@directories, 0, 0 );
+
+The first argument to C<rmtree> is either a string representing a directory path
+or an array reference. The second argument controls progress messages, and the
+third argument controls the handling of files you don't have permissions to
+delete. See the C<File::Path> module for the details.
+
+=head2 How do I copy an entire directory?
+
+(contributed by Shlomi Fish)
+
+To do the equivalent of C<cp -R> (i.e. copy an entire directory tree
+recursively) in portable Perl, you'll either need to write something yourself
+or find a good CPAN module such as L<File::Copy::Recursive>.
=head1 REVISION
-Revision: $Revision: 7875 $
+Revision: $Revision$
-Date: $Date: 2006-10-04 22:39:26 +0200 (mer, 04 oct 2006) $
+Date: $Date$
See L<perlfaq> for source control details and availability.
=head1 AUTHOR AND COPYRIGHT
-Copyright (c) 1997-2006 Tom Christiansen, Nathan Torkington, and
+Copyright (c) 1997-2009 Tom Christiansen, Nathan Torkington, and
other authors as noted. All rights reserved.
This documentation is free; you can redistribute it and/or modify it
projects / p5sagit/p5-mst-13.2.git / blobdiff