Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
IO::Pager::Buffered(3)User Contributed Perl DocumentatioIO::Pager::Buffered(3)

       IO::Pager::Buffered - Pipe deferred output to PAGER if destination is a

	 use IO::Pager::Buffered;
	   local $token	= IO::Pager::Buffered::open local *STDOUT;
	   print <<"  HEREDOC" ;
	   A bunch of text later

	   # You can also use scalar filehandles...
	   my $token = IO::Pager::Buffered::open($FH) or warn($!);
	   print $FH "No globs or barewords for	us thanks!\n" while 1;

	   # ...or an object interface
	   my $token = new IO::Pager::Buffered;

	   $token->print("OO shiny...\n") while	1;

       IO::Pager subclasses are	designed to programmatically decide whether or
       not to pipe a filehandle's output to a program specified	in PAGER;
       determined and set by IO::Pager at runtime if not yet defined.

       This subclass buffers all output	for display until execution returns to
       the parent scope	or a manual flush occurs. If this is not what you want
       look at another subclass	such as	IO::Pager::Unbuffered. While probably
       not common, this	may be useful in some cases, such as buffering all
       output to STDOUT	while the process occurs so that warnings on STDERR
       are more	visible, then displaying the less urgent output	from STDOUT
       after. Or, alternately, letting output to STDOUT	slide by and defer
       warnings	for later perusal.

       Class-specific method specifics below, others are inherited from

   open( [FILEHANDLE] )
       Instantiate a new IO::Pager to paginate FILEHANDLE if necessary.
       Assign the return value to a scoped variable. Output does not occur
       until the filehandle is flushed or closed.

   new(	[FILEHANDLE] )
       Almost identical	to open, except	that you will get an IO::Handle	back
       if there's no TTY to allow for IO::Pager	agnostic programming.

   close( FILEHANDLE )
       Flushes the buffer to the pager and closes the filehandle for writing.
       Normally, when using a lexically	or locally scoped variable to hold the
       token supplied by open, explicit	calls to close are unnecessary.
       However,	if you are using IO::Pager::Buffered with an unlocalized
       STDOUT or STDERR	you close the filehandle to display the	buffered
       content or wait for global garbage cleaning upon	program	termination.

       Alternatively, you might	prefer to use a	non-core filehandle with
       IO::Pager, and call "select" in perlfunc	to make	it the default for

   tell( FILEHANDLE )
       Returns the size	of the buffer in bytes.

   flush( FILEHANDLE )
       Immediately flushes the contents	of the buffer.

       If the last print did not end with a newline, the text from the
       preceding newline to the	end of the buffer will be flushed but is
       unlikely	to display until a newline is printed and flushed.

       If you mix buffered and unbuffered operations the output	order is
       unspecified, and	will probably differ for a TTY vs. a file. See

       $, is used see perlvar.

       You probably want to do something with SIGPIPE eg;

	 eval {
	   local $SIG{PIPE} = sub { die	};
	   local $STDOUT = IO::Pager::open(*STDOUT);

	   while (1) {
	     # Do something

	 # Do something	else

       IO::Pager, IO::Pager::Unbuffered, IO::Pager::Page,

       Jerrad Pierce <>

       Florent Angly <>

       This module was inspired	by Monte Mitzelfelt's IO::Page 0.02

       Copyright (C) 2003-2018 Jerrad Pierce

       o   Thou	shalt not claim	ownership of unmodified	materials.

       o   Thou	shalt not claim	whole ownership	of modified materials.

       o   Thou	shalt grant the	indemnity of the provider of materials.

       o   Thou	shalt use and dispense freely without other restrictions.

       Or, if you prefer:

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.0 or,	at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.1			  2020-06-15		IO::Pager::Buffered(3)


Want to link to this manual page? Use this URL:

home | help