pg - files perusal filter for CRTs


     pg [-number] [-p string] [-cefnrs] [ + linenumber] [ +/ pat-
     tern /] [filename...]


     The pg command is a filter that allows  the  examination  of
     filenames  one  screenful  at  a  time on a CRT. If the user
     types a RETURN, another page is displayed; other  possibili-
     ties are listed below.

     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

     To determine terminal attributes, pg scans  the  terminfo(4)
     data base for the terminal type specified by the environment
     variable TERM. If TERM is not  defined,  the  terminal  type
     dumb is assumed.


           An integer specifying the size (in lines) of the  win-
           dow  that  pg  is to use instead of the default. (On a
           terminal containing 24 lines, the default window  size
           is 23).

     -p string
           pg uses string as the prompt.  If  the  prompt  string
           contains  a  %d,  the  first  occurrence  of %d in the
           prompt will be replaced by  the  current  page  number
           when  the  prompt is issued. The default prompt string
           is ``:''.

     -c    Home the cursor and clear the screen before displaying
           each  page.  This option is ignored if clear_screen is
           not defined for this terminal type in the  terminfo(4)
           data base.

     -e    pg does not pause at the end of each file.

     -f    Normally, pg  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  -f
           option inhibits pg from splitting lines.

     -n    Normally, commands must be terminated by  a  <newline>
           character.  This  option  causes  an  automatic end of
           command as soon as a command letter is entered.

     -r    Restricted mode. The shell escape  is  disallowed.  pg
           prints an error message but does not exit.

     -s    pg prints all messages and  prompts  in  the  standard
           output mode (usually inverse video).

           Start up at linenumber.

           Start up at the  first  line  containing  the  regular
           expression pattern.


     The following operands are supported:

           A path name of a text file  to  be  displayed.  If  no
           filename  is  given, or if it is -, the standard input
           is read.


     The responses that may  be  typed  when  pg  pauses  can  be
     divided   into   three  categories:  those  causing  further
     perusal, those  that  search,  and  those  that  modify  the
     perusal environment.

     Commands that cause further perusal normally take a  preced-
     ing  address,  an  optionally  signed  number indicating the
     point from which further  text  should  be  displayed.  This
     address is interpreted in either pages or lines depending on
     the command. A signed address specifies a point relative  to
     the  current page or line, and an unsigned address specifies
     an address relative to the beginning of the file. Each  com-
     mand has a default address that is used if none is provided.

     The perusal commands and their defaults are as follows:

     (+1)<newline> or <blank>
           This causes one page to be displayed.  The address  is
           specified in pages.

     (+1) l
           With a relative address this  causes  pg  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

     (+1) d or ^D
           Simulates scrolling half a screen forward or backward.

     if    Skip i screens of text.

     iz    Same as <newline> except that i, if  present,  becomes
           the new default number of lines per screenful.

     The following perusal commands take no address.

     . or ^L
           Typing a single period causes the current page of text
           to be redisplayed.

     $     Displays the last windowful in the file. Use with cau-
           tion when the input is a pipe.

     The following commands are available for searching for  text
     patterns  in the text. The regular expressions are described
     on the regex(5) manual page. They must always be  terminated
     by a <newline>, even if the -n option is specified.

           Search forward for the ith (default i=1) occurrence of
           pattern.   Searching   begins  immediately  after  the
           current page and continues to the end of  the  current
           file, without wrap-around.


           Search backwards for the ith (default i=1)  occurrence
           of  pattern.  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 ?.

     After searching, pg will normally display the line found  at
     the  top  of the screen. This can be modified by appending m
     or b to the search command to leave the line  found  in  the
     middle  or at the bottom of the window from now on. The suf-
     fix t can be used to restore the original situation.

     The user of pg can modify the environment  of  perusal  with
     the following commands:

     in    Begin perusing the ith next file in the command  line.
           The i is an unsigned number, default value is 1.

     ip    Begin perusing the ith previous file  in  the  command
           line. i is an unsigned number, default is 1.

     iw    Display another window of text. If i is  present,  set
           the window size to i.

     s filename
           Save the input in the named  file.  Only  the  current
           file  being  perused is saved. The white space between
           the s and filename  is  optional.  This  command  must
           always  be  terminated  by a <newline>, even if the -n
           option is specified.

     h     Help by displaying an abbreviated summary of available

     q or Q
           Quit pg.

           Command is passed to the shell, whose  name  is  taken
           from  the  SHELL  environment variable. If this is not
           available, the default shell  is  used.  This  command
           must  always be terminated by a <newline>, even if the
           -n option is specified.

     At any time when output is being sent to the  terminal,  the
     user can hit the quit key (normally CTRL-\) or the interrupt
     (break) key. This causes pg  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

     If the standard output is not a terminal, then pg acts  just
     like  cat(1),  except  that  a header is printed before each
     file (if there is more than one).

  Large File Behavior
     See largefile(5) for the description of the behavior  of  pg
     when encountering files greater than or equal to 2 Gbyte ( 2
    **31 bytes).


     Example 1: An example of the pg command.

     The following command line uses pg to read the system news:

          example% news | pg -p "(Page %d):"


     See environ(5) for descriptions of the following environment
     variables   that  affect  the  execution  of  pg:  LC_CTYPE,

     The following environment variables affect the execution  of

           Determine the horizontal  screen  size.  If  unset  or
           NULL,  use the value of TERM,    the window size, baud
           rate, or some combination of these,  to  indicate  the
           terminal type for the screen size calculation.

     LINES Determine the number of lines to be displayed  on  the
           screen.  If  unset  or  NULL,  use  the value of TERM,
           the window size, baud rate,  or  some  combination  of
           these,  to  indicate  the terminal type for the screen
           size calculation.

     SHELL Determine the name of the command interpreter executed
           for a !command.

     TERM  Determine terminal attributes. Optionally  attempt  to
           search a system-dependent database, keyed on the value
           of the TERM environment variable. If no information is
           available,  a terminal incapable of cursor-addressable
           movement is assumed.


     The following exit values are returned:

     0     Successful completion.

     >0    An error occurred.


           temporary file when input is from a pipe

           terminal information database


     See attributes(5) for descriptions of the  following  attri-

    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | Availability                | SUNWcsu                     |
    | CSI                         | enabled                     |


     cat(1),  grep(1),   more(1),   terminfo(4),   attributes(5),
     environ(5), largefile(5), regex(5)


     While waiting for terminal  input,  pg  responds  to  BREAK,
     CTRL-C,   and   CTRL-\  by  terminating  execution.  Between
     prompts, however, these signals interrupt pg'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

     The terminal /, ^, or ? may be omitted  from  the  searching

     If terminal tabs are not set every eight positions, undesir-
     able results may occur.

     When using pg as a filter with another command that  changes
     the  terminal  I/O  options,  terminal  settings  may not be
     restored correctly.

Man(1) output converted with man2html