| blob | 2016f8b3c2baf0de7623db2bdae4fef173ee2d01 |
1 .\"
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/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
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.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
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.
30 .\"
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.
35 .\"
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]
41 .\"
42 .\"
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.
46 .\"
47 .TH PG 1 "Feb 25, 1996"
48 .SH NAME
49 pg \- files perusal filter for CRTs
50 .SH SYNOPSIS
51 .LP
52 .nf
53 \fBpg\fR [\fB-\fInumber\fR\fR] [\fB-p\fR \fIstring\fR] [\fB-cefnrs\fR] [+ \fIlinenumber\fR]
54 [+/ \fIpattern\fR /] [\fIfilename\fR]...
55 .fi
57 .SH DESCRIPTION
58 .sp
59 .LP
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.
63 .sp
64 .LP
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
67 is explained below.
68 .sp
69 .LP
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.
73 .SH OPTIONS
74 .sp
75 .ne 2
76 .na
77 \fB\fB-\fR\fInumber\fR\fR
78 .ad
79 .RS 15n
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
82 size is 23).
83 .RE
85 .sp
86 .ne 2
87 .na
88 \fB\fB-p\fR\fIstring\fR\fR
89 .ad
90 .RS 15n
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
94 ``\fB:\fR''.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fB-c\fR\fR
101 .ad
102 .RS 15n
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.
106 .RE
108 .sp
109 .ne 2
110 .na
111 \fB\fB-e\fR\fR
112 .ad
113 .RS 15n
114 \fBpg\fR does \fInot\fR pause at the end of each file.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fB-f\fR\fR
121 .ad
122 .RS 15n
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.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fB-n\fR\fR
133 .ad
134 .RS 15n
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
137 entered.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fB-r\fR\fR
144 .ad
145 .RS 15n
146 Restricted mode. The shell escape is disallowed. \fBpg\fR prints an error
147 message but does not exit.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB\fB-s\fR\fR
154 .ad
155 .RS 15n
156 \fBpg\fR prints all messages and prompts in the standard output mode (usually
157 inverse video).
158 .RE
160 .sp
161 .ne 2
162 .na
163 \fB\fB+\fR\fIlinenumber\fR\fR
164 .ad
165 .RS 15n
166 Start up at \fIlinenumber\fR.
167 .RE
169 .sp
170 .ne 2
171 .na
172 \fB\fB+/\fR\fIpattern\fR\fB/\fR\fR
173 .ad
174 .RS 15n
175 Start up at the first line containing the regular expression pattern.
176 .RE
178 .SH OPERANDS
179 .sp
180 .LP
181 The following operands are supported:
182 .sp
183 .ne 2
184 .na
185 \fB\fIfilename\fR\fR
186 .ad
187 .RS 12n
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.
190 .RE
192 .SH USAGE
193 .SS "Commands"
194 .sp
195 .LP
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.
199 .sp
200 .LP
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.
208 .sp
209 .LP
210 The perusal commands and their defaults are as follows:
211 .sp
212 .ne 2
213 .na
214 \fB(+1)<\fInewline\fR> or <\fIblank\fR>\fR
215 .ad
216 .RS 28n
217 This causes one page to be displayed. The address is specified in pages.
218 .RE
220 .sp
221 .ne 2
222 .na
223 \fB(+1) \fBl\fR\fR
224 .ad
225 .RS 28n
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.
229 .RE
231 .sp
232 .ne 2
233 .na
234 \fB(+1) \fBd\fR or \fB^D\fR\fR
235 .ad
236 .RS 28n
237 Simulates scrolling half a screen forward or backward.
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fB\fIi\fR\fBf\fR\fR
244 .ad
245 .RS 28n
246 Skip \fIi\fR screens of text.
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fIi\fR\fBz\fR\fR
253 .ad
254 .RS 28n
255 Same as <\fInewline\fR> except that \fIi\fR, if present, becomes the new
256 default number of lines per screenful.
257 .RE
259 .sp
260 .LP
261 The following perusal commands take no \fIaddress\fR.
262 .sp
263 .ne 2
264 .na
265 \fB\fB\&.\fR or \fB^L\fR\fR
266 .ad
267 .RS 13n
268 Typing a single period causes the current page of text to be redisplayed.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fB$\fR\fR
275 .ad
276 .RS 13n
277 Displays the last full window in the file. Use with caution when the input is a
278 pipe.
279 .RE
281 .sp
282 .LP
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
286 option is specified.
287 .sp
288 .ne 2
289 .na
290 \fB\fIi\fR\fB/\fR\fIpattern\fR\fB/\fR\fR
291 .ad
292 .RS 14n
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.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fIi\fR\fB^\fR\fIpattern\fR\fB^\fR\fR
302 .ad
303 .RS 14n
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fIi\fR\fB?\fR\fIpattern\fR\fB?\fR\fR
311 .ad
312 .RS 14n
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 ?.
317 .RE
319 .sp
320 .LP
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.
325 .sp
326 .LP
327 The user of \fBpg\fR can modify the environment of perusal with the following
328 commands:
329 .sp
330 .ne 2
331 .na
332 \fB\fIi\fR\fBn\fR\fR
333 .ad
334 .RS 14n
335 Begin perusing the \fIi\fRth next file in the command line. The \fIi\fR is an
336 unsigned number, default value is 1.
337 .RE
339 .sp
340 .ne 2
341 .na
342 \fB\fIi\fR\fBp\fR\fR
343 .ad
344 .RS 14n
345 Begin perusing the \fIi\fRth previous file in the command line. \fIi\fR is an
346 unsigned number, default is 1.
347 .RE
349 .sp
350 .ne 2
351 .na
352 \fB\fIi\fR\fBw\fR\fR
353 .ad
354 .RS 14n
355 Display another window of text. If \fIi\fR is present, set the window size to
356 \fIi\fR.
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBs\fR \fIfilename\fR\fR
363 .ad
364 .RS 14n
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
368 option is specified.
369 .RE
371 .sp
372 .ne 2
373 .na
374 \fB\fBh\fR\fR
375 .ad
376 .RS 14n
377 Help by displaying an abbreviated summary of available commands.
378 .RE
380 .sp
381 .ne 2
382 .na
383 \fB\fBq\fR or \fBQ\fR\fR
384 .ad
385 .RS 14n
386 Quit \fBpg\fR.
387 .RE
389 .sp
390 .ne 2
391 .na
392 \fB\fB!\fR\fBcommand\fR\fR
393 .ad
394 .RS 14n
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
398 option is specified.
399 .RE
401 .sp
402 .LP
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.
409 .sp
410 .LP
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
413 more than one).
414 .SH EXAMPLES
415 .LP
416 \fBExample 1 \fRAn example of the \fBpg\fR command.
417 .sp
418 .LP
419 The following command line uses \fBpg\fR to read the system news:
421 .sp
422 .LP
423 \fBexample% news | pg\fR \fB-p\fR \fB"(Page %d):"\fR
425 .SH ENVIRONMENT VARIABLES
426 .sp
427 .LP
428 See \fBenviron\fR(5) for descriptions of the following environment variables
429 that affect the execution of \fBpg\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
430 \fBNLSPATH\fR.
431 .sp
432 .LP
433 The following environment variables affect the execution of \fBpg\fR:
434 .sp
435 .ne 2
436 .na
437 \fB\fBCOLUMNS\fR\fR
438 .ad
439 .RS 11n
440 Determine the horizontal screen size. If unset or \fINULL,\fR use the value of
441 \fBTERM\fR, the window size, baud rate, or some combination of these, to
442 indicate the terminal type for the screen size calculation.
443 .RE
445 .sp
446 .ne 2
447 .na
448 \fB\fBLINES\fR\fR
449 .ad
450 .RS 11n
451 Determine the number of lines to be displayed on the screen. If unset or
452 \fINULL,\fR use the value of \fBTERM\fR, the window size, baud rate, or some
453 combination of these, to indicate the terminal type for the screen size
454 calculation.
455 .RE
457 .sp
458 .ne 2
459 .na
460 \fB\fBSHELL\fR\fR
461 .ad
462 .RS 11n
463 Determine the name of the command interpreter executed for a !command.
464 .RE
466 .sp
467 .ne 2
468 .na
469 \fB\fBTERM\fR\fR
470 .ad
471 .RS 11n
472 Determine terminal attributes. Optionally attempt to search a system-dependent
473 database, keyed on the value of the \fBTERM\fR environment variable. If no
474 information is available, a terminal incapable of cursor-addressable movement
475 is assumed.
476 .RE
478 .SH EXIT STATUS
479 .sp
480 .LP
481 The following exit values are returned:
482 .sp
483 .ne 2
484 .na
485 \fB\fB0\fR\fR
486 .ad
487 .RS 6n
488 Successful completion.
489 .RE
491 .sp
492 .ne 2
493 .na
494 \fB\fB>0\fR\fR
495 .ad
496 .RS 6n
497 An error occurred.
498 .RE
500 .SH FILES
501 .sp
502 .ne 2
503 .na
504 \fB\fB/tmp/pg*\fR\fR
505 .ad
506 .sp .6
507 .RS 4n
508 temporary file when input is from a pipe
509 .RE
511 .sp
512 .ne 2
513 .na
514 \fB\fB/usr/share/lib/terminfo/?/*\fR\fR
515 .ad
516 .sp .6
517 .RS 4n
518 terminal information database
519 .RE
521 .SH SEE ALSO
522 .sp
523 .LP
524 \fBcat\fR(1), \fBgrep\fR(1), \fBmore\fR(1), \fBterminfo\fR(4),
525 \fBattributes\fR(5), \fBenviron\fR(5), \fBregex\fR(5)
526 .SH NOTES
527 .sp
528 .LP
529 While waiting for terminal input, \fBpg\fR responds to BREAK, CTRL-C, and
530 CTRL\(mi\e by terminating execution. Between prompts, however, these signals
531 interrupt \fBpg\fR's current task and place the user in prompt mode. These
532 should be used with caution when input is being read from a pipe, since an
533 interrupt is likely to terminate the other commands in the pipeline.
534 .sp
535 .LP
536 The terminal \fB/\fR, \fB^\fR, or \fB?\fR may be omitted from the searching
537 commands.
538 .sp
539 .LP
540 If terminal tabs are not set every eight positions, undesirable results may
541 occur.
542 .sp
543 .LP
544 When using \fBpg\fR as a filter with another command that changes the terminal
545 I/O options, terminal settings may not be restored correctly.