NAME

pg − display files on a terminal

SYNOPSIS

pg [ −height ] [ −p prompt ] [ −cefns ] [ +line | +/pattern/ ] [ file ...  ]

DESCRIPTION

Pg allows files to be viewed page by page on a terminal.  Each file is displayed in turn with control being given to the user at the end of each page.  The user can choose to move to the next page (the default action) or to move forwards or backwards within the file or between the various files given on the command line. 

The file name “−” or the absence of a file name argument causes pg to read the file to be displayed from the standard input. 

The commands which may be used at a pg prompt can usually be qualified with a signed or unsigned count:

i A signed or unsigned value (sign is indicated by a  + or − sign).  If the value is signed this moves the current position i lines or pages (according to the command) forward in the file before the command takes effect.  A negative number moves backwards.  If the value is unsigned the current position is moved to line or page i in the file (starting from the beginning, counting from 1). 

j An unsigned value which modifies the effect of the command as described in the command description below. 

The default value for a signed number is always +1, that for an unsigned number is 1 except in the case of the w command.  These defaults take effect if no number is given or if the number is 0.  The commands are:

i<newline>
This causes the relevant page to be displayed.  With the default count this will cause the next page to be displayed. A count of −1 will cause the previous page to be displayed.  To redisplay the current page use ^L as described below. 

i<space>
This command has exactly the same effect as i<newline>.

il This moves the current position in lines rather than pages.  Pg will attempt to display a page starting at the resultant line, if the lines to be displayed are adjacent to lines already on the screen pg will only display the new lines, otherwise it will display a whole page. 

id The value of the count is ignored.  If the count is positive (signed or unsigned) the next half page is displayed, if it is negative the previous half page is displayed. 

i^D This has exactly the same effect as id.

.  This causes the current page to be redisplayed.  A count is ignored. 

^L This has exactly the same effect as ..

$ Sets the current position to the start of the last page in a file and displays it.  If the input is from a pipe this command will cause pg to wait for the end of the pipe − this may take a long time to happen.  SIGINT (normally ^C from the keyboard) can be used to interrupt the command. 

i/pattern/
A page is displayed starting at the ith occurence of pattern after the curent page.  The pattern has the same form as regular expressions in the ed(1V) editor.  Even if the −n option has been given the pattern must still be terminated by a newline.  The trailing / may be omitted. 

i^pattern^
Display a page starting at the ith occurence of pattern before the current page (matching sequences of characters within the current page are ignored). 

i?pattern?
This command has exactly the same effect as i^pattern^.

In all cases the line containing a pattern will, by default, be displayed at the top of the screen.  The trailing delimiter of the pattern may be followed by a letter to indicate where the pattern should be displayed on the screen − this changes the default behaviour until reset by a subsequent such letter:

t The pattern will be displayed at the top of the screen (the initial default). 

m The pattern will be displayed on the middle line of the screen. 

b The pattern will be displayed on the bottom line of the screen. 

Additional commands allow control over individual files and over whole pg environment, where allowed they take unsigned arguments. 

jn Display the first page of the jth file after the current one.

jp Display the first page of the jth file before the current one.

jw Display the next page of text (as with the default command), but, if j is given, set the page/window size to j.

sfile Save the current file contents in file file. White space may be inserted between s and the file name.  The command must be terminated by a newline, even if −n is in effect. 

h Display a help message summarising the commands. 

q Quit pg immediately. 

Q Quit pg immediately. 

!command
The command must be terminated by a newline, even if −n has been specified.  The command line is executed as a command by the shell specified by the SHELL environment variable, or by /usr/bin/sh if the program specified by SHELL cannot be located. 

In addition to these commands a SIGQUIT or SIGINT signal (normally ^C or ^\ typed at the keyboard will send these) will cause pg to stop processing output and return control to the user, displaying a prompt.  This may cause some output to be lost in some cases.  If a prompt is already displayed when these signals are received (ie if pg is waiting for input from the user) these signals will cause pg to terminate.  Notice that the normal consequence of causing one of these signals from the keyboard is that the signal is received by all the processes currently attached to the terminal − this may thus cause processes in a pipeline with pg to terminate. 

If the standard output is not to a terminal pg will pass its input through unmodified (see cat(1V)) except that a header will be printed before the start of each file if multiple files are given on the command line.

OPTIONS

+line Pg starts displaying the file at line number line.

+/pattern/
Pg starts displaying the file at the first line containing a sequence of characters which match the regular expression pattern.

−height
Pg uses height as the height of the output window (the number of lines from the file displayed per page of output) instead of the default. 

−c Before displaying a new page clear the screen.  The page is displayed starting at the top of the screen.  This option has no effect if the terminal database does not give a control sequence to clear the screen. 

−e Normally pg will pause at the end of each file and display a message indicating that it has reached the end of the file.  This option causes pg not to display the message but to immediately display the name of the next file or, when all files have been seen, to immediately exit.  On terminals which clear or change the screen when pg exits this will make it impossible to read the last page. 

−f If this option is in effect pg will not attempt to split long lines (lines longer than the screen width).  This can avoid undesirable effects as a result of lines being split in the middle of an escape sequence. 

−n This option causes pg to act on commands as soon a complete command has been typed, rather than waiting for a newline character to terminate the command. 

−p prompt
Replaces the default prompt string “:” with the string prompt. If the string contains “%d” it will be replaced by the number of the current page when the prompt is displayed. 

−s If the terminal supports standout mode this option causes pg to display all messages and prompts in this mode − often this will result in the message being displayed in reverse video. 

ENVIRONMENT

The pg command uses the TERM environment variable to find the characteristics of the terminal.  If the variable is set wrongly, or the terminal is incompletely or incorrectly described in the terminal database, pg may be unable to drive the terminal correctly. 

SEE ALSO

cat (1V), ed (1V), egrep (1), grep (1), more (1). 

NOTES

More(1) or page (also documented in the more manual page) is the recommended interface.  Pg will not work correctly if another process (for example one in the same pipeline as pg) attempts to use the terminal at the same time.

Pg is 8-bit transparent − with the exception of newline characters files containing full 8-bit characters or control characters will be displayed with no changes to these characters. 

System V