2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
25 .\" This notice shall appear on any product containing this material.
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved.
47 .TH PG 1 "Feb 25, 1996"
49 pg \- files perusal filter for CRTs
53 \fBpg\fR [\fB-\fInumber\fR\fR] [\fB-p\fR \fIstring\fR] [\fB-cefnrs\fR] [+ \fIlinenumber\fR]
54 [+/ \fIpattern\fR /] [\fIfilename\fR]...
60 The \fBpg\fR command is a filter that allows the examination of \fIfilenames\fR
61 one screenful at a time on a CRT. If the user types a RETURN, another page is
62 displayed; other possibilities are listed below.
65 This command is different from previous paginators in that it allows you to
66 back up and review something that has already passed. The method for doing this
70 To determine terminal attributes, \fBpg\fR scans the \fBterminfo\fR(4) data
71 base for the terminal type specified by the environment variable \fBTERM\fR. If
72 \fBTERM\fR is not defined, the terminal type \fBdumb\fR is assumed.
77 \fB\fB-\fR\fInumber\fR\fR
80 An integer specifying the size (in lines) of the window that \fBpg\fR is to use
81 instead of the default. (On a terminal containing 24 lines, the default window
88 \fB\fB-p\fR\fIstring\fR\fR
91 \fBpg\fR uses \fIstring\fR as the prompt. If the prompt string contains a
92 \fB%d\fR, the first occurrence of \fB%d\fR in the prompt will be replaced by
93 the current page number when the prompt is issued. The default prompt string is
103 Home the cursor and clear the screen before displaying each page. This option
104 is ignored if \fBclear_screen\fR is not defined for this terminal type in the
105 \fBterminfo\fR(4) data base.
114 \fBpg\fR does \fInot\fR pause at the end of each file.
123 Normally, \fBpg\fR splits lines longer than the screen width, but some
124 sequences of characters in the text being displayed (for instance, escape
125 sequences for underlining) generate undesirable results. The \fB-f\fR option
126 inhibits \fBpg\fR from splitting lines.
135 Normally, commands must be terminated by a <\fInewline\fR> character. This
136 option causes an automatic end of command as soon as a command letter is
146 Restricted mode. The shell escape is disallowed. \fBpg\fR prints an error
147 message but does not exit.
156 \fBpg\fR prints all messages and prompts in the standard output mode (usually
163 \fB\fB+\fR\fIlinenumber\fR\fR
166 Start up at \fIlinenumber\fR.
172 \fB\fB+/\fR\fIpattern\fR\fB/\fR\fR
175 Start up at the first line containing the regular expression pattern.
181 The following operands are supported:
188 A path name of a text file to be displayed. If no \fIfilename\fR is given, or
189 if it is \(mi, the standard input is read.
196 The responses that may be typed when \fBpg\fR pauses can be divided into three
197 categories: those causing further perusal, those that search, and those that
198 modify the perusal environment.
201 Commands that cause further perusal normally take a preceding \fIaddress\fR, an
202 optionally signed number indicating the point from which further text should be
203 displayed. This \fIaddress\fR is interpreted in either pages or lines depending
204 on the command. A signed \fIaddress\fR specifies a point relative to the
205 current page or line, and an unsigned \fIaddress\fR specifies an address
206 relative to the beginning of the file. Each command has a default address that
207 is used if none is provided.
210 The perusal commands and their defaults are as follows:
214 \fB(+1)<\fInewline\fR> or <\fIblank\fR>\fR
217 This causes one page to be displayed. The address is specified in pages.
226 With a relative address this causes \fBpg\fR to simulate scrolling the screen,
227 forward or backward, the number of lines specified. With an absolute address
228 this command prints a screenful beginning at the specified line.
234 \fB(+1) \fBd\fR or \fB^D\fR\fR
237 Simulates scrolling half a screen forward or backward.
246 Skip \fIi\fR screens of text.
255 Same as <\fInewline\fR> except that \fIi\fR, if present, becomes the new
256 default number of lines per screenful.
261 The following perusal commands take no \fIaddress\fR.
265 \fB\fB\&.\fR or \fB^L\fR\fR
268 Typing a single period causes the current page of text to be redisplayed.
277 Displays the last full window in the file. Use with caution when the input is a
283 The following commands are available for searching for text patterns in the
284 text. The regular expressions are described on the \fBregex\fR(5) manual page.
285 They must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
290 \fB\fIi\fR\fB/\fR\fIpattern\fR\fB/\fR\fR
293 Search forward for the \fIi\fRth (default \fIi\fR=1) occurrence of
294 \fIpattern\fR. Searching begins immediately after the current page and
295 continues to the end of the current file, without wrap-around.
301 \fB\fIi\fR\fB^\fR\fIpattern\fR\fB^\fR\fR
310 \fB\fIi\fR\fB?\fR\fIpattern\fR\fB?\fR\fR
313 Search backwards for the \fIi\fRth (default \fIi\fR=1) occurrence of
314 \fIpattern\fR. Searching begins immediately before the current page and
315 continues to the beginning of the current file, without wrap-around. The ^
316 notation is useful for Adds 100 terminals which will not properly handle the ?.
321 After searching, \fBpg\fR will normally display the line found at the top of
322 the screen. This can be modified by appending \fBm\fR or \fBb\fR to the search
323 command to leave the line found in the middle or at the bottom of the window
324 from now on. The suffix \fBt\fR can be used to restore the original situation.
327 The user of \fBpg\fR can modify the environment of perusal with the following
335 Begin perusing the \fIi\fRth next file in the command line. The \fIi\fR is an
336 unsigned number, default value is 1.
345 Begin perusing the \fIi\fRth previous file in the command line. \fIi\fR is an
346 unsigned number, default is 1.
355 Display another window of text. If \fIi\fR is present, set the window size to
362 \fB\fBs\fR \fIfilename\fR\fR
365 Save the input in the named file. Only the current file being perused is saved.
366 The white space between the \fBs\fR and \fIfilename\fR is optional. This
367 command must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
377 Help by displaying an abbreviated summary of available commands.
383 \fB\fBq\fR or \fBQ\fR\fR
392 \fB\fB!\fR\fBcommand\fR\fR
395 \fICommand\fR is passed to the shell, whose name is taken from the \fBSHELL\fR
396 environment variable. If this is not available, the default shell is used. This
397 command must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
403 At any time when output is being sent to the terminal, the user can hit the
404 quit key (normally CTRL-\e) or the interrupt (break) key. This causes \fBpg\fR
405 to stop sending output, and display the prompt. The user may then enter one of
406 the above commands in the normal manner. Unfortunately, some output is lost
407 when this is done, because any characters waiting in the terminal's output
408 queue are flushed when the quit signal occurs.
411 If the standard output is not a terminal, then \fBpg\fR acts just like
412 \fBcat\fR(1), except that a header is printed before each file (if there is
414 .SS "Large File Behavior"
417 See \fBlargefile\fR(5) for the description of the behavior of \fBpg\fR when
418 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
421 \fBExample 1 \fRAn example of the \fBpg\fR command.
424 The following command line uses \fBpg\fR to read the system news:
428 \fBexample% news | pg\fR \fB-p\fR \fB"(Page %d):"\fR
430 .SH ENVIRONMENT VARIABLES
433 See \fBenviron\fR(5) for descriptions of the following environment variables
434 that affect the execution of \fBpg\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
438 The following environment variables affect the execution of \fBpg\fR:
445 Determine the horizontal screen size. If unset or \fINULL,\fR use the value of
446 \fBTERM\fR, the window size, baud rate, or some combination of these, to
447 indicate the terminal type for the screen size calculation.
456 Determine the number of lines to be displayed on the screen. If unset or
457 \fINULL,\fR use the value of \fBTERM\fR, the window size, baud rate, or some
458 combination of these, to indicate the terminal type for the screen size
468 Determine the name of the command interpreter executed for a !command.
477 Determine terminal attributes. Optionally attempt to search a system-dependent
478 database, keyed on the value of the \fBTERM\fR environment variable. If no
479 information is available, a terminal incapable of cursor-addressable movement
486 The following exit values are returned:
493 Successful completion.
513 temporary file when input is from a pipe
519 \fB\fB/usr/share/lib/terminfo/?/*\fR\fR
523 terminal information database
529 \fBcat\fR(1), \fBgrep\fR(1), \fBmore\fR(1), \fBterminfo\fR(4),
530 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBregex\fR(5)
534 While waiting for terminal input, \fBpg\fR responds to BREAK, CTRL-C, and
535 CTRL\(mi\e by terminating execution. Between prompts, however, these signals
536 interrupt \fBpg\fR's current task and place the user in prompt mode. These
537 should be used with caution when input is being read from a pipe, since an
538 interrupt is likely to terminate the other commands in the pipeline.
541 The terminal \fB/\fR, \fB^\fR, or \fB?\fR may be omitted from the searching
545 If terminal tabs are not set every eight positions, undesirable results may
549 When using \fBpg\fR as a filter with another command that changes the terminal
550 I/O options, terminal settings may not be restored correctly.