text-utils/pg.1

   1 .\" @(#)pg.1    1.7 (gritter) 4/25/01
   2 .TH PG 1 "April 2001" "util-linux" "User Commands"
   3 .SH NAME
   4 pg \- browse pagewise through text files
   5 .SH SYNOPSIS
   6 .B pg
   7 .RB [ \-\fInumber\fP ]
   8 .RB [ \-p
   9 .IR string ]
  10 .RB [ \-cefnrs ]
  11 .RB [ +\fIline\fP ]
  12 .RB [ +/\fIpattern\fP/ ]
  13 .RI [ file ...]
  14 .SH DESCRIPTION
  15 .B pg
  16 displays a text file on a
  17 .SM CRT
  18 one screenful at once.
  19 After each page, a prompt is displayed.  The user may then either press the
  20 newline key to view the next page or one of the keys described below.
  21 .PP
  22 If no filename is given on the command line,
  23 .B pg
  24 reads from standard input.
  25 If standard output is not a terminal,
  26 .B pg
  27 acts like
  28 .IR cat (1)
  29 but precedes each file with its name if there is more than one.
  30 .PP
  31 If input comes from a pipe,
  32 .B pg
  33 stores the data in a buffer file while reading
  34 to make navigation possible.
  35 .SH OPTIONS
  36 .B pg
  37 accepts the following options:
  38 .TP
  39 .BI + number
  40 Start at the given line.
  41 .TP
  42 .BI +/ pattern /
  43 Start at the line containing the Basic Regular Expression
  44 .I pattern
  45 given.
  46 .TP
  47 .BI \- number
  48 The number of lines per page.  Usually, this is the number of
  49 .SM CRT
  50 lines minus one.
  51 .TP
  52 .B \-c
  53 Clear the screen before a page is displayed,
  54 if the terminfo entry for the terminal provides this capability.
  55 .TP
  56 .B \-e
  57 Do not pause and display
  58 .SM (EOF)
  59 at the end of a file.
  60 .TP
  61 .B \-f
  62 Do not split long lines.
  63 .TP
  64 .B \-n
  65 Without this option, commands must be terminated by a newline character.
  66 With this option,
  67 .B pg
  68 advances once a command letter is entered.
  69 .TP
  70 .BI \-p \ string
  71 Instead of the normal prompt
  72 .IR : ,
  73 .I string
  74 is displayed.
  75 If
  76 .I string
  77 contains
  78 .IR %d ,
  79 its first occurrence is replaced by the number of the current page.
  80 .TP
  81 .B \-r
  82 Disallow the shell escape.
  83 .TP
  84 .B \-s
  85 Print messages in
  86 .I standout
  87 mode,
  88 if the terminfo entry for the terminal provides this capability.
  89 .TP
  90 .B \-h, \-\-help
  91 display short help and exit.
  92 .TP
  93 .B \-V, \-\-version
  94 Disaplay version information and exit.
  95 .SH USAGE
  96 The following commands may be entered at the prompt.  Commands preceded by
  97 .I i
  98 in this document accept a number as argument, positive or negative.
  99 If this argument starts with
 100 .I +
 101 or
 102 .I \-,
 103 it is interpreted relative to the current position in the input file,
 104 otherwise relative to the beginning.
 105 .TP
 106 .IB i <newline>
 107 Display the next or the indicated page.
 108 .TP
 109 \fIi\fR\fBd\fR or \fB^D\fR
 110 Display the next halfpage.  If
 111 .I i
 112 is given, it is always interpreted relative to the current position.
 113 .TP
 114 .IB i l
 115 Display the next or the indicated line.
 116 .TP
 117 .IB i f
 118 Skip a page forward.
 119 .I i
 120 must be a positive number and is always interpreted relative
 121 to the current position.
 122 .TP
 123 \fIi\fR\fBw\fR or \fIi\fR\fBz\fR
 124 Behave as
 125 .I <newline>
 126 except that
 127 .I i
 128 becomes the new page size.
 129 .TP
 130 .BR . " or " ^L
 131 Redraw the screen.
 132 .TP
 133 .B $
 134 Advance to the last line of the input file.
 135 .TP
 136 .IB i / pattern /
 137 Search forward until the first or the \fIi\fR-th
 138 occurrence of the Basic Regular Expression
 139 .I pattern
 140 is found.  The search starts
 141 after the current page and stops at the end of the file.
 142 No wrap-around is performed.
 143 .I i
 144 must be a positive number.
 145 .TP
 146 \fIi\fR\fB?\fR\fIpattern\fR\fB?\fR or \fIi\fR\fB^\fR\fIpattern\fR\fB^\fR
 147 Search backward until the first or the \fIi\fR-th
 148 occurrence of the Basic Regular Expression
 149 .I pattern
 150 is found.  The search starts
 151 before the current page and stops at the beginning of the file.
 152 No wrap-around is performed.
 153 .I i
 154 must be a positive number.
 155 .PP
 156 The search commands accept an added letter.  If
 157 .B t
 158 is given, the line containing the pattern is displayed at the top of the
 159 screen, which is the default.
 160 .B m
 161 selects the middle and
 162 .B b
 163 the bottom of the screen.
 164 The selected position is used in following searches, too.
 165 .TP
 166 .IB i n
 167 Advance to the next file or
 168 .I i
 169 files forward.
 170 .TP
 171 .IB i p
 172 Reread the previous file or
 173 .I i
 174 files backward.
 175 .TP
 176 .BI s \ filename
 177 Save the current file to the given
 178 .I filename.
 179 .TP
 180 .B h
 181 Display a command summary.
 182 .TP
 183 .BI ! command
 184 Execute
 185 .I command
 186 using the shell.
 187 .TP
 188 .BR q " or " Q
 189 Quit.
 190 .PP
 191 If the user presses the interrupt or quit key while
 192 .B pg
 193 reads from the
 194 input file or writes on the terminal,
 195 .B pg
 196 will immediately display the prompt.
 197 In all other situations these keys will terminate
 198 .BR pg .
 199 .SH "ENVIRONMENT VARIABLES"
 200 The following environment variables
 201 affect the behaviour of
 202 .BR pg :
 203 .TP
 204 .B COLUMNS
 205 Overrides the system-supplied number of columns if set.
 206 .TP
 207 .BR LANG ,\  LC_ALL ,\  LC_COLLATE ,\  LC_CTYPE ,\  LC_MESSAGES
 208 See
 209 .IR locale (7).
 210 .TP
 211 .B LINES
 212 Overrides the system-supplied number of lines if set.
 213 .TP
 214 .B SHELL
 215 Used by the
 216 .BR ! " command."
 217 .TP
 218 .B TERM
 219 Determines the terminal type.
 220 .SH "SEE ALSO"
 221 .BR cat (1),
 222 .BR more (1),
 223 .BR sh (1),
 224 .BR terminfo (5),
 225 .BR locale (7),
 226 .BR regex (7),
 227 .BR term (7)
 228 .SH NOTES
 229 .B pg
 230 expects the terminal tabulators to be set every eight positions.
 231 .PP
 232 Files that include
 233 .SM NUL
 234 characters cannot be displayed by
 235 .BR pg .
 236 .SH AVAILABILITY
 237 The pg command is part of the util-linux package and is available from
 238 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.