| blob | a6703f2b90d34121e22cfada966015e20aaf59ff |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
3 .\" 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
4 .\" http://www.opengroup.org/bookstore/.
5 .\" 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 Sun OS 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.
6 .\" This notice shall appear on any product containing this material.
7 .\" 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.
8 .\" 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.
9 .\" 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]
10 .TH PG 1 "Feb 25, 1996"
11 .SH NAME
12 pg \- files perusal filter for CRTs
13 .SH SYNOPSIS
14 .LP
15 .nf
16 \fBpg\fR [\fB-\fInumber\fR\fR] [\fB-p\fR \fIstring\fR] [\fB-cefnrs\fR] [+ \fIlinenumber\fR]
17 [+/ \fIpattern\fR /] [\fIfilename\fR]...
18 .fi
20 .SH DESCRIPTION
21 .sp
22 .LP
23 The \fBpg\fR command is a filter that allows the examination of \fIfilenames\fR
24 one screenful at a time on a CRT. If the user types a RETURN, another page is
25 displayed; other possibilities are listed below.
26 .sp
27 .LP
28 This command is different from previous paginators in that it allows you to
29 back up and review something that has already passed. The method for doing this
30 is explained below.
31 .sp
32 .LP
33 To determine terminal attributes, \fBpg\fR scans the \fBterminfo\fR(4) data
34 base for the terminal type specified by the environment variable \fBTERM\fR. If
35 \fBTERM\fR is not defined, the terminal type \fBdumb\fR is assumed.
36 .SH OPTIONS
37 .sp
38 .ne 2
39 .na
40 \fB\fB-\fR\fInumber\fR\fR
41 .ad
42 .RS 15n
43 An integer specifying the size (in lines) of the window that \fBpg\fR is to use
44 instead of the default. (On a terminal containing 24 lines, the default window
45 size is 23).
46 .RE
48 .sp
49 .ne 2
50 .na
51 \fB\fB-p\fR\fIstring\fR\fR
52 .ad
53 .RS 15n
54 \fBpg\fR uses \fIstring\fR as the prompt. If the prompt string contains a
55 \fB%d\fR, the first occurrence of \fB%d\fR in the prompt will be replaced by
56 the current page number when the prompt is issued. The default prompt string is
57 ``\fB:\fR''.
58 .RE
60 .sp
61 .ne 2
62 .na
63 \fB\fB-c\fR\fR
64 .ad
65 .RS 15n
66 Home the cursor and clear the screen before displaying each page. This option
67 is ignored if \fBclear_screen\fR is not defined for this terminal type in the
68 \fBterminfo\fR(4) data base.
69 .RE
71 .sp
72 .ne 2
73 .na
74 \fB\fB-e\fR\fR
75 .ad
76 .RS 15n
77 \fBpg\fR does \fInot\fR pause at the end of each file.
78 .RE
80 .sp
81 .ne 2
82 .na
83 \fB\fB-f\fR\fR
84 .ad
85 .RS 15n
86 Normally, \fBpg\fR splits lines longer than the screen width, but some
87 sequences of characters in the text being displayed (for instance, escape
88 sequences for underlining) generate undesirable results. The \fB-f\fR option
89 inhibits \fBpg\fR from splitting lines.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fB-n\fR\fR
96 .ad
97 .RS 15n
98 Normally, commands must be terminated by a <\fInewline\fR> character. This
99 option causes an automatic end of command as soon as a command letter is
100 entered.
101 .RE
103 .sp
104 .ne 2
105 .na
106 \fB\fB-r\fR\fR
107 .ad
108 .RS 15n
109 Restricted mode. The shell escape is disallowed. \fBpg\fR prints an error
110 message but does not exit.
111 .RE
113 .sp
114 .ne 2
115 .na
116 \fB\fB-s\fR\fR
117 .ad
118 .RS 15n
119 \fBpg\fR prints all messages and prompts in the standard output mode (usually
120 inverse video).
121 .RE
123 .sp
124 .ne 2
125 .na
126 \fB\fB+\fR\fIlinenumber\fR\fR
127 .ad
128 .RS 15n
129 Start up at \fIlinenumber\fR.
130 .RE
132 .sp
133 .ne 2
134 .na
135 \fB\fB+/\fR\fIpattern\fR\fB/\fR\fR
136 .ad
137 .RS 15n
138 Start up at the first line containing the regular expression pattern.
139 .RE
141 .SH OPERANDS
142 .sp
143 .LP
144 The following operands are supported:
145 .sp
146 .ne 2
147 .na
148 \fB\fIfilename\fR\fR
149 .ad
150 .RS 12n
151 A path name of a text file to be displayed. If no \fIfilename\fR is given, or
152 if it is \(mi, the standard input is read.
153 .RE
155 .SH USAGE
156 .SS "Commands"
157 .sp
158 .LP
159 The responses that may be typed when \fBpg\fR pauses can be divided into three
160 categories: those causing further perusal, those that search, and those that
161 modify the perusal environment.
162 .sp
163 .LP
164 Commands that cause further perusal normally take a preceding \fIaddress\fR, an
165 optionally signed number indicating the point from which further text should be
166 displayed. This \fIaddress\fR is interpreted in either pages or lines depending
167 on the command. A signed \fIaddress\fR specifies a point relative to the
168 current page or line, and an unsigned \fIaddress\fR specifies an address
169 relative to the beginning of the file. Each command has a default address that
170 is used if none is provided.
171 .sp
172 .LP
173 The perusal commands and their defaults are as follows:
174 .sp
175 .ne 2
176 .na
177 \fB(+1)<\fInewline\fR> or <\fIblank\fR>\fR
178 .ad
179 .RS 28n
180 This causes one page to be displayed. The address is specified in pages.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fB(+1) \fBl\fR\fR
187 .ad
188 .RS 28n
189 With a relative address this causes \fBpg\fR to simulate scrolling the screen,
190 forward or backward, the number of lines specified. With an absolute address
191 this command prints a screenful beginning at the specified line.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB(+1) \fBd\fR or \fB^D\fR\fR
198 .ad
199 .RS 28n
200 Simulates scrolling half a screen forward or backward.
201 .RE
203 .sp
204 .ne 2
205 .na
206 \fB\fIi\fR\fBf\fR\fR
207 .ad
208 .RS 28n
209 Skip \fIi\fR screens of text.
210 .RE
212 .sp
213 .ne 2
214 .na
215 \fB\fIi\fR\fBz\fR\fR
216 .ad
217 .RS 28n
218 Same as <\fInewline\fR> except that \fIi\fR, if present, becomes the new
219 default number of lines per screenful.
220 .RE
222 .sp
223 .LP
224 The following perusal commands take no \fIaddress\fR.
225 .sp
226 .ne 2
227 .na
228 \fB\fB\&.\fR or \fB^L\fR\fR
229 .ad
230 .RS 13n
231 Typing a single period causes the current page of text to be redisplayed.
232 .RE
234 .sp
235 .ne 2
236 .na
237 \fB\fB$\fR\fR
238 .ad
239 .RS 13n
240 Displays the last full window in the file. Use with caution when the input is a
241 pipe.
242 .RE
244 .sp
245 .LP
246 The following commands are available for searching for text patterns in the
247 text. The regular expressions are described on the \fBregex\fR(5) manual page.
248 They must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
249 option is specified.
250 .sp
251 .ne 2
252 .na
253 \fB\fIi\fR\fB/\fR\fIpattern\fR\fB/\fR\fR
254 .ad
255 .RS 14n
256 Search forward for the \fIi\fRth (default \fIi\fR=1) occurrence of
257 \fIpattern\fR. Searching begins immediately after the current page and
258 continues to the end of the current file, without wrap-around.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fIi\fR\fB^\fR\fIpattern\fR\fB^\fR\fR
265 .ad
266 .RS 14n
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fIi\fR\fB?\fR\fIpattern\fR\fB?\fR\fR
274 .ad
275 .RS 14n
276 Search backwards for the \fIi\fRth (default \fIi\fR=1) occurrence of
277 \fIpattern\fR. Searching begins immediately before the current page and
278 continues to the beginning of the current file, without wrap-around. The ^
279 notation is useful for Adds 100 terminals which will not properly handle the ?.
280 .RE
282 .sp
283 .LP
284 After searching, \fBpg\fR will normally display the line found at the top of
285 the screen. This can be modified by appending \fBm\fR or \fBb\fR to the search
286 command to leave the line found in the middle or at the bottom of the window
287 from now on. The suffix \fBt\fR can be used to restore the original situation.
288 .sp
289 .LP
290 The user of \fBpg\fR can modify the environment of perusal with the following
291 commands:
292 .sp
293 .ne 2
294 .na
295 \fB\fIi\fR\fBn\fR\fR
296 .ad
297 .RS 14n
298 Begin perusing the \fIi\fRth next file in the command line. The \fIi\fR is an
299 unsigned number, default value is 1.
300 .RE
302 .sp
303 .ne 2
304 .na
305 \fB\fIi\fR\fBp\fR\fR
306 .ad
307 .RS 14n
308 Begin perusing the \fIi\fRth previous file in the command line. \fIi\fR is an
309 unsigned number, default is 1.
310 .RE
312 .sp
313 .ne 2
314 .na
315 \fB\fIi\fR\fBw\fR\fR
316 .ad
317 .RS 14n
318 Display another window of text. If \fIi\fR is present, set the window size to
319 \fIi\fR.
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fBs\fR \fIfilename\fR\fR
326 .ad
327 .RS 14n
328 Save the input in the named file. Only the current file being perused is saved.
329 The white space between the \fBs\fR and \fIfilename\fR is optional. This
330 command must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
331 option is specified.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fBh\fR\fR
338 .ad
339 .RS 14n
340 Help by displaying an abbreviated summary of available commands.
341 .RE
343 .sp
344 .ne 2
345 .na
346 \fB\fBq\fR or \fBQ\fR\fR
347 .ad
348 .RS 14n
349 Quit \fBpg\fR.
350 .RE
352 .sp
353 .ne 2
354 .na
355 \fB\fB!\fR\fBcommand\fR\fR
356 .ad
357 .RS 14n
358 \fICommand\fR is passed to the shell, whose name is taken from the \fBSHELL\fR
359 environment variable. If this is not available, the default shell is used. This
360 command must always be terminated by a <\fInewline\fR>, even if the \fB-n\fR
361 option is specified.
362 .RE
364 .sp
365 .LP
366 At any time when output is being sent to the terminal, the user can hit the
367 quit key (normally CTRL-\e) or the interrupt (break) key. This causes \fBpg\fR
368 to stop sending output, and display the prompt. The user may then enter one of
369 the above commands in the normal manner. Unfortunately, some output is lost
370 when this is done, because any characters waiting in the terminal's output
371 queue are flushed when the quit signal occurs.
372 .sp
373 .LP
374 If the standard output is not a terminal, then \fBpg\fR acts just like
375 \fBcat\fR(1), except that a header is printed before each file (if there is
376 more than one).
377 .SS "Large File Behavior"
378 .sp
379 .LP
380 See \fBlargefile\fR(5) for the description of the behavior of \fBpg\fR when
381 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
382 .SH EXAMPLES
383 .LP
384 \fBExample 1 \fRAn example of the \fBpg\fR command.
385 .sp
386 .LP
387 The following command line uses \fBpg\fR to read the system news:
389 .sp
390 .LP
391 \fBexample% news | pg\fR \fB-p\fR \fB"(Page %d):"\fR
393 .SH ENVIRONMENT VARIABLES
394 .sp
395 .LP
396 See \fBenviron\fR(5) for descriptions of the following environment variables
397 that affect the execution of \fBpg\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
398 \fBNLSPATH\fR.
399 .sp
400 .LP
401 The following environment variables affect the execution of \fBpg\fR:
402 .sp
403 .ne 2
404 .na
405 \fB\fBCOLUMNS\fR\fR
406 .ad
407 .RS 11n
408 Determine the horizontal screen size. If unset or \fINULL,\fR use the value of
409 \fBTERM\fR, the window size, baud rate, or some combination of these, to
410 indicate the terminal type for the screen size calculation.
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fBLINES\fR\fR
417 .ad
418 .RS 11n
419 Determine the number of lines to be displayed on the screen. If unset or
420 \fINULL,\fR use the value of \fBTERM\fR, the window size, baud rate, or some
421 combination of these, to indicate the terminal type for the screen size
422 calculation.
423 .RE
425 .sp
426 .ne 2
427 .na
428 \fB\fBSHELL\fR\fR
429 .ad
430 .RS 11n
431 Determine the name of the command interpreter executed for a !command.
432 .RE
434 .sp
435 .ne 2
436 .na
437 \fB\fBTERM\fR\fR
438 .ad
439 .RS 11n
440 Determine terminal attributes. Optionally attempt to search a system-dependent
441 database, keyed on the value of the \fBTERM\fR environment variable. If no
442 information is available, a terminal incapable of cursor-addressable movement
443 is assumed.
444 .RE
446 .SH EXIT STATUS
447 .sp
448 .LP
449 The following exit values are returned:
450 .sp
451 .ne 2
452 .na
453 \fB\fB0\fR\fR
454 .ad
455 .RS 6n
456 Successful completion.
457 .RE
459 .sp
460 .ne 2
461 .na
462 \fB\fB>0\fR\fR
463 .ad
464 .RS 6n
465 An error occurred.
466 .RE
468 .SH FILES
469 .sp
470 .ne 2
471 .na
472 \fB\fB/tmp/pg*\fR\fR
473 .ad
474 .sp .6
475 .RS 4n
476 temporary file when input is from a pipe
477 .RE
479 .sp
480 .ne 2
481 .na
482 \fB\fB/usr/share/lib/terminfo/?/*\fR\fR
483 .ad
484 .sp .6
485 .RS 4n
486 terminal information database
487 .RE
489 .SH SEE ALSO
490 .sp
491 .LP
492 \fBcat\fR(1), \fBgrep\fR(1), \fBmore\fR(1), \fBterminfo\fR(4),
493 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBregex\fR(5)
494 .SH NOTES
495 .sp
496 .LP
497 While waiting for terminal input, \fBpg\fR responds to BREAK, CTRL-C, and
498 CTRL\(mi\e by terminating execution. Between prompts, however, these signals
499 interrupt \fBpg\fR's current task and place the user in prompt mode. These
500 should be used with caution when input is being read from a pipe, since an
501 interrupt is likely to terminate the other commands in the pipeline.
502 .sp
503 .LP
504 The terminal \fB/\fR, \fB^\fR, or \fB?\fR may be omitted from the searching
505 commands.
506 .sp
507 .LP
508 If terminal tabs are not set every eight positions, undesirable results may
509 occur.
510 .sp
511 .LP
512 When using \fBpg\fR as a filter with another command that changes the terminal
513 I/O options, terminal settings may not be restored correctly.