<!-- category: hidden-gems -->

$|++ Autoflush via Increment

2026-04-30

Your code is fine. Your output buffering is not.

$|++;

But wait. $| is a variable. You just incremented it. What kind of variable fixes buffering when you add 1 to it? Welcome to the weirdest boolean toggle in Perl.

Part 1: WHAT $| DOES

$| = 0;    # buffered (default)
$| = 1;    # autoflush on

With autoflush on, every print triggers an immediate write. Slower for bulk output. But essential when you need output to appear in real time.

Buffered ($| = 0):
    print "."  -->  [buffer: .]
    print "."  -->  [buffer: ..]
    print "."  -->  [buffer: ...]
    ...
    print "."  -->  [buffer: .....(4096 chars)]  -->  WRITE to terminal

Autoflush ($| = 1):
    print "."  -->  WRITE to terminal
    print "."  -->  WRITE to terminal
    print "."  -->  WRITE to terminal

Part 2: WHY $|++ WORKS

When you do $|++, you are incrementing it from 0 to 1. That turns autoflush on. Simple enough.

But what if you do $|++ again? Normal math says 1 + 1 = 2. But $| is magic. It coerces any nonzero value to 1. So $|++ on a value of 1 produces... 1.

say $|;    # 0  (default)
$|++;
say $|;    # 1  (incremented)
$|++;
say $|;    # 1  (still 1, not 2)
$|++;
say $|;    # 1  (always 1)

The ++ is not really "increment." It is "turn on, and stay on no matter how many times you call it." A latch, not a counter.

Part 3: $|++ VS $| = 1

$| = 1;     # explicit: "set autoflush to true"
$|++;       # idiomatic: "turn on autoflush"

Neither is wrong. But $|++ has a certain charm. It looks like you are doing something sneaky, but you are really just flipping a switch. Peak Perl.

Some people prefer $|-- as a joke. Decrementing from 0 to... well, $| treats -1 as truthy, so it also turns autoflush on. But $|-- on 1 gives 0 and turns it off. So $|-- is actually unreliable as a toggle. Stick with $|++ or $| = 1.

Part 4: WHY YOU NEED AUTOFLUSH

Progress indicators:

#!/usr/bin/env perl
use strict;
use warnings;

$|++;    # without this, dots appear in bursts

for my $i (1 .. 1000)
{
    print ".";
    do_slow_thing($i);
}
print "\n";

$ perl generate.pl | tee output.log

CGI scripts:

Old-school CGI sends HTTP headers followed by content. If the headers are buffered and the content arrives in the same buffer flush, the web server might get confused about where headers end. $|++ at the top of a CGI script is classic defensive coding.

Real-time logging:

#!/usr/bin/env perl
use strict;
use warnings;
use POSIX qw(strftime);

$|++;    # flush every log line immediately

while (my $event = wait_for_event())
{
    my $ts = strftime("%Y-%m-%d %H:%M:%S", localtime);
    print "[$ts] $event\n";
}

Part 5: STDOUT VS OTHER FILEHANDLES

$|++;    # sets autoflush on the currently selected filehandle
         # (usually STDOUT)

open my $log, '>', 'app.log' or die $!;
select $log;     # $log is now the default output filehandle

$|++;            # this sets autoflush on $log, NOT STDOUT

print "goes to log\n";          # autoflushed
print STDOUT "goes to term\n";  # NOT autoflushed!

# explicit: set STDOUT autoflush regardless of select()
my $old = select STDOUT;
$| = 1;
select $old;

select((select(STDOUT), $| = 1)[0]);

Part 6: IO::HANDLE TO THE RESCUE

use IO::Handle;

STDOUT->autoflush(1);
STDERR->autoflush(1);

open my $log, '>', 'app.log' or die $!;
$log->autoflush(1);

IO::Handle ships with core Perl. No CPAN install needed. This is the recommended approach in modern code. It is explicit, readable, and works on any filehandle without side effects.

#!/usr/bin/env perl
use strict;
use warnings;
use feature 'say';
use IO::Handle;

# autoflush both standard streams
STDOUT->autoflush(1);
STDERR->autoflush(1);

# now both streams flush immediately
say "this appears right away";
warn "so does this";

Part 7: REAL-TIME LOGGING EXAMPLE

#!/usr/bin/env perl
use strict;
use warnings;
use feature 'say';
use IO::Handle;

open my $logfile, '>>', 'process.log' or die "Cannot open log: $!";
$logfile->autoflush(1);
STDOUT->autoflush(1);

sub log_msg
{
    my ($msg) = @_;
    my $ts = localtime();
    my $line = "[$ts] $msg";
    say $line;              # terminal
    say $logfile $line;     # file
}

log_msg("Starting process");

for my $i (1 .. 100)
{
    log_msg("Processing item $i");
    sleep 1;    # simulate work
}

log_msg("Done");
close $logfile;

Part 8: THE PER-FILEHANDLE GOTCHA

$|++;    # STDOUT autoflush only

# STDERR is still buffered (though in practice,
# STDERR is usually unbuffered by default on most systems)

STDOUT to terminal:  line-buffered  (flush on \n)
STDOUT to pipe:      fully-buffered (flush on buffer full)
STDOUT to file:      fully-buffered (flush on buffer full)
STDERR:              unbuffered     (flush on every write)

$|++ switches STDOUT from line-buffered (or fully-buffered) to unbuffered. Every write, no matter how small, gets flushed immediately.

Part 9: PERFORMANCE IMPLICATIONS

#!/usr/bin/env perl
use strict;
use warnings;
use Time::HiRes qw(gettimeofday tv_interval);

open my $fh, '>', '/dev/null' or die $!;

# buffered
my $t0 = [gettimeofday];
for (1 .. 100_000)
{
    print $fh "line of data\n";
}
my $buffered = tv_interval($t0);

# autoflushed
$fh->autoflush(1);
$t0 = [gettimeofday];
for (1 .. 100_000)
{
    print $fh "line of data\n";
}
my $flushed = tv_interval($t0);

printf "Buffered: %.3fs\n", $buffered;
printf "Flushed:  %.3fs\n", $flushed;

Part 10: THE FULL PICTURE

      .--.
     |o_o |     "$|++
     |:_/ |      Three characters.
    //   \ \     Zero buffering."
   (|     | )
  /'\_   _/`\
  \___)=(___/

For new code, use IO::Handle->autoflush(1). It is clearer, it works on any filehandle, and it does not depend on select.

For one-liners and quick scripts, $|++ is still unbeatable. Three characters that solve the "why is my output stuck in a buffer" problem. No import. No method call. Just a variable increment that happens to do exactly what you need.

Buffering exists for performance. Autoflush exists for sanity. Know when to use each one. And when your progress dots come out in bursts, $|++ is the answer.

perl.gg