NAME

pg - file perusal filter for soft-copy terminals (LEGACY)

 SYNOPSIS

pg[-number][-cefns][-p string][+linenumber][+/re/][file...]

 DESCRIPTION

The pg utility is a filter that allows the examination of the named file or files one screenful at a time on a soft-copy terminal. Each screenful is followed by a prompt. If the user types a carriage-return character, another page is displayed; other possibilities are enumerated in the EXTENDED DESCRIPTION section.

If the standard output is not a terminal, pg ignores all options and writes the input files to standard output, like the cat utility, except that a header is written before each file (if there is more than one).

 OPTIONS

The pg utility supports the XBD specification, Utility Syntax Guidelines  , except that the -number option takes a multi-digit value and the +linenumber and /re/ options take a leading plus sign instead of minus. The following options are supported when standard input is a terminal:

-number

Change window size. The number argument is a positive integer specifying the size (in lines) of the window that pg is to use instead of the default. (The default size is determined by the LINES environment variable. If LINES is unset or null, a terminal-specific default size is used; the TERM environment variable may affect the determination of the terminal-specific default size. The default is typically one less than the number of lines in the terminal window.)

-p string

Use string as the prompt. If the prompt string contains a %d, the first occurrence of %d in the prompt will be replaced by the current page number when the prompt is issued. The default prompt string is ":".

-c

Home the cursor and clear the screen before displaying each page. This option is ignored if the terminal does not support this.

-e

Do not pause at the end of each file; see the EXTENDED DESCRIPTION section.

-f

Inhibit line splitting. Normally, pg splits lines longer than the screen width, but some sequences of characters in the text being displayed (for example, escape sequences for underlining) generate undesirable results.

-n

Cause an automatic end-of-command as soon as a command letter is entered. Normally, commands must be terminated by a newline character. The -n option is not supported on certain block-mode terminals. If pg is being used on such terminal, the -n option will be silently ignored and the terminating newline character will be required to complete a command.

-s

Write all messages and prompts in standout mode (usually inverse video) if the terminal supports this.

+linenumber

Start up at linenumber.

+/re/

Start up at the first line matching the basic regular expression re.

 OPERANDS

The following operands are supported:

file

A pathname of a text file to be displayed. If no file is given, or if it is -, the standard input is read.

 STDIN

The standard input is a text file that is used if no file operand is given, or if it is -.

 INPUT FILES

The input file named by the file operand is a text file.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of pg:

COLUMNS

Determine the horizontal screen size. If unset or null, use the value of TERM , the window size, baud rate, or some combination of these, to indicate the terminal type for the screen size calculation.

LINES

Determine the number of lines to be displayed on the screen. If unset or null, use the value of TERM , the window size, baud rate, or some combination of these, to indicate the terminal type for the screen size calculation.

SHELL

Determine the name of the command interpreter executed for a !command.

TERM

Determine terminal attributes. Optionally attempt to search a system-dependent database, keyed on the value of the TERM environment variable. If no information is available, a terminal incapable of cursor-addressable movement is assumed.

The following environment variables may affect the execution of pg:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_COLLATE

Determine the locale for the behaviour of ranges, equivalence classes and multi-character collating elements within regular expressions.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files) and the behaviour of character classes within regular expressions.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error, and informative messages written to standard output.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

During the writing of characters to the standard output, pg catches SIGINT and SIGQUIT, returning the user to the prompt. When waiting at the prompt, pg takes the default action on SIGINT and SIGQUIT. The default actions are taken for all other signals.

 STDOUT

The standard output is a display of the input files, with prompts interspersed. When standard output is not associated with a terminal, it consists of the contents of the input files, separated by the following lines, if there is more than one input file:

"::::::::::::::\n%s\n::::::::::::::\n", <pathname>

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

The responses that can be typed when pg pauses can be divided into three categories: those causing further perusal, those that search and those that modify the perusal environment.

Commands that cause further perusal normally take a preceding address; an optionally signed number indicating the point from which further text should be displayed. This address is interpreted in either pages or lines depending on the command. A signed address specifies a point relative to the current page or line, and an unsigned address specifies an address relative to the beginning of the file. Each command has a default address that is used if none is provided.

The perusal commands and their defaults are as follows:

(+1)<newline> or <space>

Display one page. The address is specified in number of pages.

(+1)l

With a relative address, simulate scrolling the screen, forward or backward, by the number of lines specified. With an absolute address, print a screenful beginning at the specified line.

(+1)d or <control>-D

Simulate scrolling half a screen forward or backward.

The following perusal commands take no address:

. or <control>-L

Redisplay the current page of text.

$

Display the last windowful in the file.

The following commands are available for searching for text patterns in the text. Basic regular expression syntax is used in patterns. The res must always be terminated by a newline character, even if the -n option is specified.

i/re/

Search forwards for the ith occurrence of re (default i=1). Searching begins immediately after the current page and continues to the end of the current file, without wrap-around.

i^re^

i?re?

Search backwards for the ith occurrence of re (default i=1). Searching begins immediately before the current page and continues to the beginning of the current file, without wrap-around.

After searching, pg will normally display the line found at the top of the screen. This can be modified by appending m or b to the search command to leave the line found in the middle or at the bottom of the window from now on. The suffix t can be used to restore the original situation.

If the standard output is not a terminal device, pg always exits when it reaches end-of-file on the last file in its argument list. Otherwise, for all files but the last, pg prompts with an indication that it has reached the end-of-file, along with the name of the next file; when -e is used, the end-of-file prompt is bypassed and the prompt indicates the name of the next file. For the last file specified, or for the standard input if no file is specified, pg prompts indicating end-of-file (if -e is not used), and accepts additional commands. If the next command specifies forward scrolling, pg exits. If the -e option is specified, pg exits immediately after writing the last line of the last file.

The user of pg can modify the environment of perusal with the following commands:

in

Begin perusing the ith next file in the command line. The i is an unsigned number; default value is 1.

ip

Begin perusing the ith previous file in the command line. The i is an unsigned number; default is 1.

iw

Display another window of text. If i is present, set the window size to i.

s  filename

Save the input in the file named filename. Only the current file being perused is saved. The blank-character-separation between the s and filename is optional. This command must always be terminated by a newline character, even if the -n option is specified.

h

Help by displaying an abbreviated summary of available commands.

q or Q

Quit pg.

!command

Pass the argument command to the command interpreter, whose name is taken from the SHELL environment variable. If SHELL is unset or null, sh is used as the default command interpreter. This command must always be terminated by a newline character, even if the -n option is specified.

At any time when output is being sent to the terminal, receipt of a quit or interrupt signal causes pg to stop sending output and to display the prompt. The user may then enter one of the above commands in the normal manner. Unfortunately, some output is lost when this is done, due to the fact that any characters waiting in the terminal's output queue are flushed when the signal occurs.

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

This utility is different from previous paginators in that it allows the user to back up and review something that has already passed. The method for doing this is explained in the EXTENDED DESCRIPTION section.

While waiting for terminal input, pg responds to SIGINT and SIGQUIT signals by terminating execution. Between prompts, however, these signals interrupt pg's current task and place the user in prompt mode. These signals should be used with caution when input is being read from a pipe, since an interrupt is likely to terminate the other commands in the pipeline.

Use the $ command with caution when the input is a pipe.

If terminal tabs are not set every eight column positions, undesirable results may occur.

When pg is used as a filter with another command that changes the terminal I/O options, terminal settings might not be restored correctly.

Applications should migrate to the more utility.

 EXAMPLES

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

more, the XBD specification, Basic Regular Expressions  , the XBD specification, General Terminal Interface  .