FAQ 5.1 How do I flush/unbuffer an output filehandle? Why must I do this?



This is an excerpt from the latest version perlfaq5.pod, which
comes with the standard Perl distribution. These postings aim to
reduce the number of repeated questions as well as allow the community
to review and update the answers. The latest version of the complete
perlfaq is at http://faq.perl.org .

--------------------------------------------------------------------

5.1: How do I flush/unbuffer an output filehandle? Why must I do this?

(contributed by brian d foy)

You might like to read Mark Jason Dominus's "Suffering From Buffering"
at http://perl.plover.com/FAQs/Buffering.html .

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, "STDOUT". You can set the special variable $| 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
}

# now should alternate . and +
while( 1 )
{
sleep 1;
print STDOUT ".";
print STDERR "+";
print STDOUT "\n" unless ++$count % 25;
}

Besides the $| special variable, you can use "binmode" to give your
filehandle a ":unix" layer, which is unbuffered:

binmode( STDOUT, ":unix" );

while( 1 ) {
sleep 1;
print ".";
print "\n" unless ++$count % 50;
}

For more information on output layers, see the entries for "binmode" and
"open" in perlfunc, and the "PerlIO" module documentation.

If you are using "IO::Handle" or one of its subclasses, you can call the
"autoflush" method to change the settings of the filehandle:

use IO::Handle;
open my( $io_fh ), ">", "output.txt";
$io_fh->autoflush(1);

The "IO::Handle" objects also have a "flush" method. You can flush the
buffer any time you want without auto-buffering

$io_fh->flush;



--------------------------------------------------------------------

The perlfaq-workers, a group of volunteers, maintain the perlfaq. They
are not necessarily experts in every domain where Perl might show up,
so please include as much information as possible and relevant in any
corrections. The perlfaq-workers also don't have access to every
operating system or platform, so please include relevant details for
corrections to examples that do not work on particular platforms.
Working code is greatly appreciated.

If you'd like to help maintain the perlfaq, see the details in
perlfaq.pod.
.