path: root/usr/src/man/man1/pg.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 1996, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH PG 1 "Feb 25, 1996"
.SH NAME
pg \- files perusal filter for CRTs
.SH SYNOPSIS
.LP
.nf
\fBpg\fR [\fB-\fInumber\fR\fR] [\fB-p\fR \fIstring\fR] [\fB-cefnrs\fR] [+ \fIlinenumber\fR]
     [+/ \fIpattern\fR /] [\fIfilename\fR]...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpg\fR command is a filter that allows the examination of \fIfilenames\fR
one screenful at a time on a CRT. If the user types a RETURN, another page is
displayed; other possibilities are listed below.
.sp
.LP
This command is different from previous paginators in that it allows you to
back up and review something that has already passed. The method for doing this
is explained below.
.sp
.LP
To determine terminal attributes, \fBpg\fR scans the \fBterminfo\fR(4) data
base for the terminal type specified by the environment variable \fBTERM\fR. If
\fBTERM\fR is not defined, the terminal type \fBdumb\fR is assumed.
.SH OPTIONS
.sp
.ne 2
.na
\fB\fB-\fR\fInumber\fR\fR
.ad
.RS 15n
An integer specifying the size (in lines) of the window that \fBpg\fR is to use
instead of the default. (On a terminal containing 24 lines, the default window
size is 23).
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fIstring\fR\fR
.ad
.RS 15n
\fBpg\fR uses \fIstring\fR as the prompt. If the prompt string contains a
\fB%d\fR, the first occurrence of \fB%d\fR in the prompt will be replaced by
the current page number when the prompt is issued. The default prompt string is
``\fB:\fR''.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 15n
Home the cursor and clear the screen before displaying each page. This option
is ignored if \fBclear_screen\fR is not defined for this terminal type in the
\fBterminfo\fR(4) data base.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 15n
\fBpg\fR does \fInot\fR pause at the end of each file.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 15n
Normally, \fBpg\fR splits lines longer than the screen width, but some
sequences of characters in the text being displayed (for instance, escape
sequences for underlining) generate undesirable results. The \fB-f\fR option
inhibits \fBpg\fR from splitting lines.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 15n
Normally, commands must be terminated by a <\fInewline\fR> character. This
option causes an automatic end of command as soon as a command letter is
entered.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 15n
Restricted mode. The shell escape is disallowed. \fBpg\fR prints an error
message but does not exit.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 15n
\fBpg\fR prints all messages and prompts in the standard output mode (usually
inverse video).
.RE

.sp
.ne 2
.na
\fB\fB+\fR\fIlinenumber\fR\fR
.ad
.RS 15n
Start up at \fIlinenumber\fR.
.RE

.sp
.ne 2
.na
\fB\fB+/\fR\fIpattern\fR\fB/\fR\fR
.ad
.RS 15n
Start up at the first line containing the regular expression pattern.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIfilename\fR\fR
.ad
.RS 12n
A path name of a text file to be displayed. If no \fIfilename\fR is given, or
if it is \(mi, the standard input is read.
.RE

.SH USAGE
.SS "Commands"
.sp
.LP
The responses that may be typed when \fBpg\fR pauses can be divided into three
categories: those causing further perusal, those that search, and those that
modify the perusal environment.
.sp
.LP
Commands that cause further perusal normally take a preceding \fIaddress\fR, an
optionally signed number indicating the point from which further text should be
displayed. This \fIaddress\fR is interpreted in either pages or lines depending
on the command. A signed \fIaddress\fR specifies a point relative to the
current page or line, and an unsigned \fIaddress\fR specifies an address
relative to the beginning of the file. Each command has a default address that
is used if none is provided.
.sp
.LP
The perusal commands and their defaults are as follows:
.sp
.ne 2
.na
\fB(+1)<\fInewline\fR> or <\fIblank\fR>\fR
.ad
.RS 28n
This causes one page to be displayed. The address is specified in pages.
.RE

.sp
.ne 2
.na
\fB(+1) \fBl\fR\fR
.ad
.RS 28n
With a relative address this causes \fBpg\fR to simulate scrolling the screen,
forward or backward, the number of lines specified. With an absolute address
this command prints a screenful beginning at the specified line.
.RE

.sp
.ne 2
.na
\fB(+1) \fBd\fR or \fB^D\fR\fR
.ad
.RS 28n
Simulates scrolling half a screen forward or backward.
.RE

.sp
.ne 2
.na
\fB\fIi\fR\fBf\fR\fR
.ad
.RS 28n
Skip \fIi\fR screens of text.
.RE

.sp
.ne 2
.na
\fB\fIi\fR\fBz\fR\fR
.ad
.RS 28n
Same as <\fInewline\fR> except that \fIi\fR, if present, becomes the new
default number of lines per screenful.
.RE

.sp
.LP
The following perusal commands take no \fIaddress\fR.
.sp
.ne 2
.na
\fB\fB\&.\fR or \fB^L\fR\fR
.ad
.RS 13n
Typing a single period causes the current page of text to be redisplayed.
.RE

.sp
.ne 2
.na
\fB\fB$\fR\fR
.ad
.RS 13n
Displays the last full window in the file. Use with caution when the input is a
pipe.
.RE

.sp
.LP
The following commands are available for searching for text patterns in the
text. The regular expressions are described on the \fBregex\fR(5) manual page.
They must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
option is specified.
.sp
.ne 2
.na
\fB\fIi\fR\fB/\fR\fIpattern\fR\fB/\fR\fR
.ad
.RS 14n
Search forward for the \fIi\fRth (default \fIi\fR=1) occurrence of
\fIpattern\fR. Searching begins immediately after the current page and
continues to the end of the current file, without wrap-around.
.RE

.sp
.ne 2
.na
\fB\fIi\fR\fB^\fR\fIpattern\fR\fB^\fR\fR
.ad
.RS 14n

.RE

.sp
.ne 2
.na
\fB\fIi\fR\fB?\fR\fIpattern\fR\fB?\fR\fR
.ad
.RS 14n
Search backwards for the \fIi\fRth (default \fIi\fR=1) occurrence of
\fIpattern\fR. Searching begins immediately before the current page and
continues to the beginning of the current file, without wrap-around. The ^
notation is useful for Adds 100 terminals which will not properly handle the ?.
.RE

.sp
.LP
After searching, \fBpg\fR will normally display the line found at the top of
the screen. This can be modified by appending \fBm\fR or \fBb\fR to the search
command to leave the line found in the middle or at the bottom of the window
from now on. The suffix \fBt\fR can be used to restore the original situation.
.sp
.LP
The user of \fBpg\fR can modify the environment of perusal with the following
commands:
.sp
.ne 2
.na
\fB\fIi\fR\fBn\fR\fR
.ad
.RS 14n
Begin perusing the \fIi\fRth next file in the command line. The \fIi\fR is an
unsigned number, default value is 1.
.RE

.sp
.ne 2
.na
\fB\fIi\fR\fBp\fR\fR
.ad
.RS 14n
Begin perusing the \fIi\fRth previous file in the command line. \fIi\fR is an
unsigned number, default is 1.
.RE

.sp
.ne 2
.na
\fB\fIi\fR\fBw\fR\fR
.ad
.RS 14n
Display another window of text. If \fIi\fR is present, set the window size to
\fIi\fR.
.RE

.sp
.ne 2
.na
\fB\fBs\fR \fIfilename\fR\fR
.ad
.RS 14n
Save the input in the named file. Only the current file being perused is saved.
The white space between the \fBs\fR and \fIfilename\fR is optional. This
command must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
option is specified.
.RE

.sp
.ne 2
.na
\fB\fBh\fR\fR
.ad
.RS 14n
Help by displaying an abbreviated summary of available commands.
.RE

.sp
.ne 2
.na
\fB\fBq\fR or \fBQ\fR\fR
.ad
.RS 14n
Quit \fBpg\fR.
.RE

.sp
.ne 2
.na
\fB\fB!\fR\fBcommand\fR\fR
.ad
.RS 14n
\fICommand\fR is passed to the shell, whose name is taken from the \fBSHELL\fR
environment variable. If this is not available, the default shell is used. This
command must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
option is specified.
.RE

.sp
.LP
At any time when output is being sent to the terminal, the user can hit the
quit key (normally CTRL-\e) or the interrupt (break) key. This causes \fBpg\fR
to stop sending output, and 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, because any characters waiting in the terminal's output
queue are flushed when the quit signal occurs.
.sp
.LP
If the standard output is not a terminal, then \fBpg\fR acts just like
\fBcat\fR(1), except that a header is printed before each file (if there is
more than one).
.SS "Large File Behavior"
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBpg\fR when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH EXAMPLES
.LP
\fBExample 1 \fRAn example of the \fBpg\fR command.
.sp
.LP
The following command line uses \fBpg\fR to read the system news:

.sp
.LP
\fBexample% news | pg\fR \fB-p\fR \fB"(Page %d):"\fR

.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBpg\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
\fBNLSPATH\fR.
.sp
.LP
The following environment variables affect the execution of \fBpg\fR:
.sp
.ne 2
.na
\fB\fBCOLUMNS\fR\fR
.ad
.RS 11n
Determine the horizontal screen size. If unset or \fINULL,\fR use the value of
\fBTERM\fR, the window size, baud rate, or some combination of these, to
indicate the terminal type for the screen size calculation.
.RE

.sp
.ne 2
.na
\fB\fBLINES\fR\fR
.ad
.RS 11n
Determine the number of lines to be displayed on the screen. If unset or
\fINULL,\fR use the value of \fBTERM\fR, the window size, baud rate, or some
combination of these, to indicate the terminal type for the screen size
calculation.
.RE

.sp
.ne 2
.na
\fB\fBSHELL\fR\fR
.ad
.RS 11n
Determine the name of the command interpreter executed for a !command.
.RE

.sp
.ne 2
.na
\fB\fBTERM\fR\fR
.ad
.RS 11n
Determine terminal attributes. Optionally attempt to search a system-dependent
database, keyed on the value of the \fBTERM\fR environment variable. If no
information is available, a terminal incapable of cursor-addressable movement
is assumed.
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/tmp/pg*\fR\fR
.ad
.sp .6
.RS 4n
temporary file when input is from a pipe
.RE

.sp
.ne 2
.na
\fB\fB/usr/share/lib/terminfo/?/*\fR\fR
.ad
.sp .6
.RS 4n
terminal information database
.RE

.SH SEE ALSO
.sp
.LP
\fBcat\fR(1), \fBgrep\fR(1), \fBmore\fR(1), \fBterminfo\fR(4),
\fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBregex\fR(5)
.SH NOTES
.sp
.LP
While waiting for terminal input, \fBpg\fR responds to BREAK, CTRL-C, and
CTRL\(mi\e by terminating execution. Between prompts, however, these signals
interrupt \fBpg\fR's current task and place the user in prompt mode. These
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.
.sp
.LP
The terminal \fB/\fR, \fB^\fR, or \fB?\fR may be omitted from the searching
commands.
.sp
.LP
If terminal tabs are not set every eight positions, undesirable results may
occur.
.sp
.LP
When using \fBpg\fR as a filter with another command that changes the terminal
I/O options, terminal settings may not be restored correctly.