---
name: "IO::Pager"
section: "3pm"
platform: "linux"
package: "perl-io-pager"
version: "2.10-6"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/IO::Pager"
---

# IO::Pager(3pm)

Select a pager (possibly perl-based) & pipe it text if a TTY

## NAME

IO::Pager - Select a pager (possibly perl-based) & pipe it text if a TTY

## SYNOPSIS

```
  # Select an appropriate pager and set the PAGER environment variable
  use IO::Pager;
  # TIMTOWTDI Object-oriented
  {
    # open()                           # Use all the defaults.
    my $object = new IO::Pager;
    # open FILEHANDLE                  # Unbuffered is default subclass
    my $object = new IO::Pager *STDOUT;
    # open FILEHANDLE,EXPR             # Specify subclass
    my $object = new IO::Pager *STDOUT,  'Unbuffered';
    # Direct subclass instantiation    # FH is optional
    use IO::Pager::Unbuffered;
    my $object = new IO::Pager::Unbuffered  *STDOUT;
    $object->print("OO shiny...\n") while 1;
    print "Some other text sent to STODUT, perhaps from a foreign routine."
    # $object passes out of scope and filehandle is automagically closed
  }
  # TIMTOWTDI Procedural
  {
    # open FILEHANDLE                    # Unbuffered is default subclass
    my $token = IO::Pager::open *STDOUT;
    # open FILEHANDLE,EXPR               # Specify subclass
    my $token = IO::Pager::open *STDOUT,  'Unbuffered';
    # open FILEHANDLE,MODE,EXPR          # En lieu of a separate binmode()
    my $token = IO::Pager::open *STDOUT, '|-:utf8', 'Unbuffered';
    print <<"  HEREDOC" ;
    ...
    A bunch of text later
    HEREDOC
    # $token passes out of scope and filehandle is automagically closed
  }
  {
    # You can also use scalar filehandles...
    my $token = IO::Pager::open(my $FH) or warn($!); XXX
    print $FH "No globs or barewords for us thanks!\n" while 1;
  }
```

## DESCRIPTION

IO::Pager can be used to locate an available pager and set the *PAGER* environment variable (see "NOTES"). It is also a factory for creating I/O objects such as IO::Pager::Buffered and IO::Pager::Unbuffered.

IO::Pager subclasses are designed to programmatically decide whether or not to pipe a filehandle's output to a program specified in *PAGER*. Subclasses may implement only the IO handle methods desired and inherit the remainder of those outlined below from IO::Pager. For anything else, YMMV. See the appropriate subclass for implementation specific details.

## METHODS

### new( FILEHANDLE, \[MODE\], \[SUBCLASS\] )

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.

### open( FILEHANDLE, \[MODE\], \[SUBCLASS\] )

Instantiate a new IO::Pager, which will paginate output sent to FILEHANDLE if interacting with a TTY.

Save the return value to check for errors, use as an object, or for implict close of OO handles when the variable passes out of scope.

- FILEHANDLE

  You may provide a glob or scalar.

  Defaults to currently **select()**-ed *FILEHANDLE*.

- SUBCLASS

  Specifies which variety of IO::Pager to create. This accepts fully qualified packages *IO::Pager::Buffered*, or simply the third portion of the package name *Buffered* for brevity.

  Defaults to IO::Pager::Unbuffered.

  Returns false and sets *$!* on failure, same as perl's `"open"`.

### PID

Call this method on the token returned by `"open"` to get the process identifier for the child process i.e; pager; if you need to perform some long term process management e.g; perl's `"waitpid"`

You can also access the PID by numifying the instantiation token like so:

```
  my $child = $token+0;
```

### close( FILEHANDLE )

Explicitly close the filehandle, this stops any redirection of output on FILEHANDLE that may have been warranted.

*This does not default to the current filehandle*.

Alternatively, you may rely upon the implicit close of lexical handles as they pass out of scope e.g;

```
  {
     IO::Pager::open local *RIBBIT;
     print RIBBIT "No toad sexing allowed";
     ...
  }
  #The filehandle is closed to additional output
  {
     my $token = new IO::Pager::Buffered;
     $token->print("I like trains");
     ...
  }
  #The string "I like trains" is flushed to the pager, and the handle closed
```

### binmode( FILEHANDLE, \[LAYER\] )

Used to set the I/O layer a.k.a. discipline of a filehandle, such as `':utf8'` for UTF-8 encoding.

*:LOG(\[\>\>FILE\])*

IO::Pager implements a pseudo-IO-layer for capturing output and sending it to a file, similar to [**tee**(1)](/tee/1.md). Although it is limited to one file, this feature is pure-perl and adds no dependencies.

You may indicate what file to store in parentheses, otherwise the default is `"$$.log"`. You may also use an implicit (no indicator) or explicit (*\>*) indicator to overwrite an existing file, or an explicit (*\>\>*) for appending to a log file. For example:

```
    binmode(*STDOUT, ':LOG(clobber.log)');
    ...
    $STDOUT->binmode(':LOG(>>noclobber.log)');
```

For full tee-style support, use PerlIO::Util like so:

```
    binmode(*STDOUT, ":tee(TH)");
    #OR
    $STDOUT->binmode(':tee(TH)');
```

### eof( FILEHANDLE )

Used in the eval-until-eof idiom below, *IO::Pager* will handle broken pipes from deceased children for you in one of two ways. If *$ENV{IP\_EOF}* is false then program flow will pass out of the loop on *SIGPIPE*, this is the default. If the variable is true, then the program continues running with output for the previously paged filehandle directed to the *STDOUT* stream; more accurately, the filehandle is reopened to file descriptor 1.

```
  use IO::Pager::Page; #or whichever you prefer;
  ...
  eval{
    say "Producing prodigious portions of product";
    ...
  } until( eof(*STDOUT) );
  print "Cleaning up after our child before terminating."
```

If using **eof()** with less, especially when IP\_EOF is set, you may want to use the *--no-init* option by setting *$ENV{IP\_EOF}='X'* to prevent the paged output from being erased when the pager exits.

### fileno( FILEHANDLE )

Return the filehandle number of the write-only pipe to the pager.

### print( FILEHANDLE LIST )

**print()** to the filehandle.

### printf( FILEHANDLE FORMAT, LIST )

**printf()** to the filehandle.

### syswrite( FILEHANDLE, SCALAR, \[LENGTH\], \[OFFSET\] )

**syswrite()** to the filehandle.

## ENVIRONMENT

- IP\_EOF

  Controls IO:Pager behavior when `"eof"` is used.

- PAGER

  The location of the default pager.

- PATH

  If the location in PAGER is not absolute, PATH may be searched.

  See "NOTES" for more information.

## FILES

IO::Pager may fall back to these binaries in order if *PAGER* is not executable.

- /etc/alternatives/pager

  - /usr/local/bin/less

  - /usr/bin/less

  - IO::Pager::Perl as "tp" via IO::Pager::less

  - /usr/bin/more

  See "NOTES" for more information.

## NOTES

The algorithm for determining which pager to use is as follows:

- 1\. Defer to *PAGER*

  If the *PAGER* environment variable is set, use the pager it identifies, unless this pager is not available.

- 2\. Usual suspects

  Try the standard, hardcoded paths in "FILES".

- 3\. File::Which

  If File::Which is available, use the first pager possible amongst `"less"`, `"most"`, `"w3m"`, `"lv"`, `"pg"` and more.

- 4\. Term::Pager via IO::Pager::Perl

  You may also set `$ENV`{PAGER} to Term::Pager to select this extensible, pure perl pager for display.

- 5\. more

  Set *PAGER* to `"more"`, and cross our fingers.

Steps 1, 3 and 5 rely upon the *PATH* environment variable.

## CAVEATS

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
```

## SEE ALSO

IO::Pager::Buffered, IO::Pager::Unbuffered, I::Pager::Perl, IO::Pager::Page, IO::Page, Meta::Tool::Less

## AUTHOR

Jerrad Pierce \<jpierce@cpan.org\>

Florent Angly \<florent.angly@gmail.com\>

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

## COPYRIGHT AND LICENSE

Copyright (C) 2003-2020 Jerrad Pierce

- •

  Thou shalt not claim ownership of unmodified materials.

- •

  Thou shalt not claim whole ownership of modified materials.

- •

  Thou shalt grant the indemnity of the provider of materials.

- •

  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.