path: root/pw.1

PW(1)                                       Pipe Watch                                      PW(1)

NAME
       pw - Pipe Watch: monitor recent lines of output from pipe

SYNOPSIS
       command | pw [-i interval] [-l interval] [-n number-of-lines] [-dEB]

DESCRIPTION
       pw  stands  for Pipe Watch, a utility that continuously reads lines of text from a pipe or
       pipe-like source, passes them through a FIFO buffer, and maintains a display based on  the
       occasional sampling of the contents of the FIFO buffer, with useful features such as trig-
       gering and filtering.

       Upon successful startup, pw simultaneously monitors its standard input for the arrival  of
       new  data,  as  well  as  the TTY for interactive commands.  Lines from standard input are
       placed into a FIFO buffer.  While the FIFO buffer is not yet full, lines are displayed im-
       mediately.   After the FIFO buffer fills up with the specified number of lines (controlled
       by the -n option) then pw transitions into the free-running mode in which, old  lines  are
       removed from the tail of the FIFO as new ones are added to the head, and the display is no
       longer refreshed for every new line arriving into the FIFO.

       In free-running mode, the display is automatically refreshed with  the  latest  FIFO  data
       only if:

       1.     suspended mode is not in effect; and

       2.     trigger mode is not in effect; and

       3.     pw isn't executing in the background (see the Ctrl-Z command).

       When  the  above  conditions  do not hold, and thus the display is being automatically re-
       freshed, it is refreshed at these times:

       1.     when there is some keyboard activity from the terminal; or

       2.     when the interval period has expired without new input having been seen; or else

       3.     whenever the long period elapses.

       In other words, while the input is rapidly producing data, and there is no keyboard input,
       the display is updated infrequently, only according to the long interval.

       If  pw  is  executing  in  the foreground, and if display updates aren't suspended, and if
       trigger mode is effect, then the display updates automatically only when a trigger is  ac-
       tivated by a pattern match on the FIFO contents. Trigger mode is activated using the > and
       ?  commands below.

       When standard input indicates end-of-data.  pw terminates, unless the -d (do not quit) op-
       tion  has  been  specified, in which case it pw stays in interactive mode. The the end-of-
       data status is indicated by the string EOF being displayed in the status  line  after  the
       data.

DISPLAY
       Lines  displayed  by  pw  are trimmed not to exceed the number of terminal columns. When a
       line is trimmed, it is terminated by the < character to indicate that there are more char-
       acters. The display may be scrolled interactively to read the long lines.

       Control characters are replaced as follows.  The ASCII DEL character (127) is converted to
       the character sequence ^?  and other ASCII control characters are converted to ^@, ^A, ...
       ^Z,  ...   ^_,  except  for TAB which is expanded into spaces according to the current tab
       stop.  All other characters remain as-is. No attempt is made to account for the  width  of
       East Asian Unicode characters, and such.

       The  above  replacement  of  control characters happens when lines are read from the input
       source, not when they are being displayed. Therefore, changing the tab stop  size  has  no
       effect on lines which are already captured and displayed.

       When  the  display  is scrolled horizontally, the > character appears at the start of each
       line to indicate this state.  Thus, if neither end of a long line  is  currently  visible,
       then its visible portion appears delimited by >...<.

COMMANDS
       While  reading data from standard input, pw monitors the TTY for input, providing the fol-
       lowing commands.

       The commands may be prefixed by a numeric argument, which is ignored by commands to  which
       it  is not applicable. The numeric argument is specified by entering digits, which are not
       echoed. The last 3 digits of the input are retained, so that the argument has an effective
       range from 0 to 999.  Leading zeros are interpreted as the 0 command.

       The commands are:

       q, Ctrl-C
              Quit the program. Must be used multiple times in succession if a quit count greater
              than 1 is in effect. (See the -q option).

       [count]. (period)
              Repeats the most recent simple command, with the specified count  or  if  count  is
              omitted,  with  the  original count of that command. If count is given, it also re-
              places the remembered count, for the next time the  .   (period)  command  is  used
              without  a  count.  Colon and trigger commands are not simple commands; they cannot
              be repeated by the period command.

       [count]l, [count]Left Arrow
              Scroll the display to the left by count characters, defaulting to 8 if count is ab-
              sent.

       [count]h, [count]Right Arrow
              Scroll  the  display  to the right by count characters, defaulting to 8 if count is
              absent.

       0, Home
              Reset scroll to first column.

       Ctrl-L Refresh the display.

       [count]<, [count]>
              Adjust the left vertical split, separating the left pane of the display.  The  left
              pane  is  an  area  of the display which always shows the prefix of each line, pro-
              tected from horizontal scrolling. If the line is longer than the prefix,  then  ei-
              ther  the  > character appears to separate the left pane from the right pane, where
              the horizontally scrolling portion of remainder of the line appears, or else the  |
              character  appears  to  separate the left pane from the middle pane.  The left pane
              has a zero width by default, so that it does not appear.  These  commands  decrease
              and increase its width by the specified count which defaults to one character.

       [count][, [count]]
              Adjust the right vertical split, separating the middle pane of the display from the
              right pane. The middle pane is an area of the display which always shows some  mid-
              dle  portion  of  each line, protected from horizontal scrolling. It may appear to-
              gether with the left split (see the < and > commands) or by itself. The > character
              separates the middle pane from the right pane.

              The  middle  pane  has  a zero width by default, so that it does not appear.  These
              commands decrease and increase the width by count which defaults to one  character.
              Which  portion of each line is shown in the middle pane is determined each time the
              middle pane is increased from zero width to nonzero: in other words, when the  mid-
              dle  pane is changed from its hidden state to visible.  At that moment, the current
              horizontal scroll position, together with the size of the left pane, determines the
              part of the line which is assigned to the middle pane. After that, the width of the
              pane can be adjusted without affecting what portion of the line it shows,  indepen-
              dently of any horizontal scrolling adjustments occurring in the right pane.

       [count]{, [count]}
              Adjust  what  portion of line is visible in the middle pane, incrementing or decre-
              menting the viewport origin by count characters, defaulting to one, without  chang-
              ing the width.  The effect is that the content of the middle pane appears to scroll
              horizontally to the right when } is used, or left when { is used.  When  no  middle
              pane  is  being shown, these commands have no effect other than refreshing the dis-
              play.

       Ctrl-I, Tab
              Toggle the highlighting of separator characters appearing in the line display.  The
              when  toggled on, the >, < and | characters which indicate line truncation and pane
              separation are shown in inverse video (dark foreground, light background).

       [count]t
              Set the tab stop size. If count is omitted, zero, or  greater  than  16,  then  the
              value  8 is substituted. The tab stop size does not affect lines which have already
              been captured and displayed; tabs are expanded to spaces when lines are  read  from
              standard input and entered into the FIFO.

       Ctrl-G Shows  the status of the display parameters, in a form which can be given to the -p
              option as an argument in order to re-create the same configuration.  The parameters
              are  five  nonnegative  integers,  shown in decimal. The first for are in character
              units; the fifth is a bitmask value.  The documentation for the -p option  explains
              the numbers.

       Space  Suspend  the  acquisition  of new snapshots.  In suspended mode, input continues to
              pass through the FIFO, but new snapshots of data aren't taken. The display  updates
              only  due  to horizontal scrolling, history browsing, resize, or Ctrl-Z suspend and
              resume.  The status indicator SUSPENDED is displayed below the  data.  If  the  the
              status is already EOF then suspend mode cannot be entered.

       Enter  Cancel  suspended  mode, resuming display refresh. The display is refreshed immedi-
              ately and the SUSPENDED status indicator disappears.

       :      Enter colon command mode. In colon command mode, the status line clears and a colon
              prompt  appears there. An extended command can be entered.  Pressing Enter in colon
              mode dispatches the command.  Colon commands are documented in the  COLON  COMMANDS
              section below.  Simple editing is available, described in the EDITING COMMANDS sec-
              tion below.

       [pos]/[!]pattern, [pos]?[!]pattern
              Set a trigger if a non-empty pattern is specified, or else cancel a trigger  if  an
              empty  pattern  is  specified.   The  / command specifies a head-referenced trigger
              mode, whereas ?  specifies tail-referenced trigger mode.

              Under trigger mode, the display is suspended, similarly to  suspend  mode.   It  is
              only refreshed when data arrives into the FIFO such that the state of the FIFO then
              matches certain regular expression patterns.

              A head-referenced trigger is relative to most recently received data which  appears
              at  the  bottom  of the display. A tail-referenced trigger is on least-recently re-
              ceived data, relative to the top of the display.  If one or more triggers are  set,
              then  trigger  mode is in effect. If all triggers are removed, trigger mode is can-
              celed.

              Tail-referenced and head-referenced triggers are mutually exclusive.   If  a  tail-
              referenced trigger command is successfully executed, then all head-referenced trig-
              gers are removed. Vice versa, a tail-referenced trigger command cancels  all  head-
              referenced triggers.

              If  the numeric prefix pos is omitted, or specified as zero, then it defaults to 1.
              The prefix specifies the relative position of the pattern.  A head-referenced trig-
              ger's  position  is  relative to the most recent data in the FIFO, and therefore is
              effectively a reverse line number relative to the bottom of the display.  For exam-
              ple  /foo or, equivalently, 1/foo triggers when the bottom line of the display con-
              tains a match for the expression foo.  Whereas 3/bar triggers when the  third  line
              from  the  bottom  matches  bar.  To cancel the 3/bar trigger without canceling the
              1/foo trigger, the command 3/ can be used: 3/ with an empty pattern. Inversely, the
              tail-referenced  pattern  positions  are  from the top of the display. Thus ?foo or
              1?foo trigger when the top line contains a match for foo.

              If the value of pos specifies a line beyond the display range, or a  value  greater
              than 100, the command is ignored.

              Trigger  patterns saved in a history which may be navigated for recall using the up
              and down arrow keys or Ctrl-P and Ctrl-N.   While  the  trigger  pattern  is  being
              edited,  the  current  set of triggers remains in effect. Editing a trigger pattern
              may be canceled with ESC, in which case it is not entered into the history and  and
              the  trigger command isn't executed.  The history stores only the patterns, not the
              pos prefix or the ?  or / command. Erroneous patterns, and the patterns of  ignored
              commands are still entered into the history; empty patterns are not.

              The pattern of a newly issued command interpreted as either an extended regular ex-
              pression (ERE) or (BRE) depending on the current setting.  This is true even if  it
              is recalled from a history entry which had been created under a different mode.

              If  the  pattern is preceded by the character !  then it is logically inverted. The
              trigger will activate on lines which do not match the pattern. To  write  an  unin-
              verted  pattern which begins with !, precede the !  with a backslash. This is not a
              regex character escape sequence, but part of the trigger command  syntax.  It  must
              not be used anywhere in a pattern, other than immediately after the / or ?  command
              character.

              In trigger mode, the status string TRIG/ or TRIG?  is shown followed by the list of
              triggers  in parentheses.  Patterns which have a position other than 1 are preceded
              by the position shown in square brackets.

       [count]a, [count]d
              Advance or delay the currently active triggers by count lines, defaulting to 1. Ad-
              vancing means that all of the triggers are assigned to more recently received lines
              closer to the head of the FIFO.  on earlier data. Delaying  is  the  opposite:  the
              triggers  are  assigned  to less recently received items, closer to the tail of the
              FIFO.  The advance/delay commands will not move any trigger  to  a  position  which
              corresponds to a line that is not displayed.

       k, Up Arrow
              Switch  the  display  to  earlier snapshot. Each time pw updates the display with a
              snapshot of data, the existing snapshot is entered into a history window, where  it
              becomes snapshot 1.  The previous snapshot 1 becomes 2, and so on. 19 snapshots are
              retained.  The k command switches to an older snapshot: from current to 1, or  from
              1 to 2, and so on.  When snapshot 1 to 19 is being displayed, the status line shows
              HISTnum where num is the snapshot number.

              Tip: the snapshot history is particularly useful when it is gathered by triggering.
              See  the / and ?  commands above. Triggered snapshots can reveal recurring patterns
              in the input.  The history can be used  to  identify  differences  among  triggered
              snapshots  which  appear  and disappear too rapidly to be read in real time. One of
              the possible uses of that information is to refine the trigger patterns in order to
              capture  snapshots that are more similar to each other.  In the absence of trigger-
              ing, historic snapshots may be completely unrelated.

              Tip: it is usually useful to pause the acquisition of snapshots when  browsing  the
              history:  see  the  Space  command above. Snapshot acquisition is be observed while
              browsing the history, since every historic snapshot moves to a higher number when a
              snapshot  is  taken, while the displayed number stays the same, and the display up-
              dates accordingly.

       l, Down Arrow
              Go back to earlier snapshot in history. If snapshot 1 is currently being displayed,
              then  pw switches to the current snapshot and the HIST indicator in the status line
              disappears.

       [count]+
              Increases the display size by count lines, defaulting to 1.  This doesn't come into
              effect immediately; the newly opened position must be filled by a line of data from
              standard input. There is no way to reduce the size dynamically. Resizing is limited
              to the terminal height, if the height is known.

              Resizing  clears  the  snapshot history. The command is disabled when viewing snap-
              shots from the history; it must be executed while viewing the current snapshot.

       #      Toggle the display of line numbers. In tail-referenced trigger mode, the lines  are
              numbered from bottom to top.  In all other situations, top to bottom.

       Ctrl-Z Suspends  pw, and indeed the entire surrounding process group, to the background to
              gain shell access. This requires a job control  shell.   When  pw  is  foregrounded
              again,  it  will  refresh the display in a new text area below the cursor, avoiding
              overwriting anything in the terminal. Thus suspending and  then  immediately  fore-
              grounding  provides  a  way to save a snapshot of the window into the terminal ses-
              sions history.

              It is possible to execute pw in the job control background. This may happen in  two
              ways:  either the pw job is backgrounded from the beginning using the shell's & op-
              erator, or else it is suspended with Ctrl-Z and then requested to  execute  in  the
              background  using  the  shell's  bg command. When pw executes in the background, it
              continues reading from the pipe and discard input, but doesn't update the  display.
              This  useful  behavior  allows pw to be used for monitoring multiple programs which
              continuously produce output, all from the same job control session. Redirecting the
              output of such programs to pw and putting them into the background effectively muf-
              fles their output, while allowing them to execute indefinitely. Because pw is read-
              ing  their  output, they never block on a pipe write.  At any time any such a back-
              grounded job can be brought into the foreground to visualize its most recent output
              in the pw display.

       Ctrl-D Toggle  the  highlighting  of  differences between snapshots. When this mode is en-
              abled, the currently displayed snapshot is compared to a previous snapshot.  If any
              character  in  the currently displayed snapshot is different from the corresponding
              character of the previous snapshot, or if the previous snapshot  does  not  have  a
              corresponding character (because the corresponding line in the previous snapshot is
              shorter), then the character is displayed in inverse video.

              When the FIFO isn't full, or the snapshot history is empty, display of  differences
              is suppressed, even if the mode is enabled.

              The  moment  the  first snapshot recedes into a previously empty history, the first
              snapshot becomes the previous snapshot being compared with the current snapshot. If
              no  history  navigation  takes  place, then on subsequent snapshots, this stays the
              same: current will be compared with the HIST 1 snapshot.

              When the history is navigated to view the previous  snapshots,  then  the  previous
              snapshot  is always the previously displayed one which was left behind by the posi-
              tion change.  For instance, when navigating from the HIST 3 snapshot to the HIST  4
              snapshot,  then  3 becomes the previous reference, and 4 current. The display high-
              lights the differences from 3 to 4. Then if a reverse navigation step is  performed
              from  HIST 4 back to HIST 3, then 3 becomes currently displayed and 4 is the previ-
              ous reference snapshot used for comparison: the display highlights the 4 to 3  dif-
              ferences, thus chronologically reversed.

              Furthermore,  As  the history window moves due to a new snapshot being taken, these
              positions stay the same. Whatever snapshots are currently 3 and 4 will be  compared
              in the order that had been determined by the last navigational direction.

COLON COMMANDS
       First, some general remarks.

       The  capture  of snapshots, driving display refresh, doesn't pause during the editing of a
       colon command. If that is desired, the suspend command must be used first.

       The name of a colon command consists of a combination of one or more letters a through z ,
       upper  or  lower  case.  Only  the first two letters of a command are significant: for in-
       stance, the command :save is actually :sa.  Commands which are one letter long may not  be
       written  with superfluous letters, though. For instance, :grep is not understood as :g but
       as the (nonexistent) command :gr.

       The command may be followed by an argument, which is separated from the command by exactly
       one space.  If the argument does not begin with a lower-case letter, then the space may be
       omitted. If the command is followed by no characters at all, or exactly  one  space,  then
       its  argument  is effectively the empty string; by convention, this is understood as there
       being no argument.

       When a command is executed, a message appears in its place, diagnosing an error  situation
       or  confirming  a successful result. When such a message appears, it persists until a com-
       mand is issued. If the command is Enter, it has only the effect of dismissing the  message
       and  restoring  the usual status line, and not the usual effect of resuming pw out of sus-
       pended capture mode.

       Colon commands are saved in a history which may be navigated for recall using the  up  and
       down arrow keys or Ctrl-P and Ctrl-N.

       The commands are:

       :w filename
              Write the currently displayed lines into the specified file.

       :a filename
              Append the currently displayed lines into the specified file.

       :! filename
              Pipe the currently displayed lines into the specified command.

       :g pattern, :v pattern
              Push a grep pattern onto the grep stack. The :g command pushes a plain pattern; the
              :v command pushes a logically inverted pattern. The grep stack holds up to 64  pat-
              terns.   If  the  pattern is successfully pushed onto the stack, it restricts which
              lines are admitted into the FIFO and available for display.  The plain pattern  ad-
              mits  only  the  lines  which match pattern; the inverted pattern admits only lines
              which do not match pattern.  Lines which are already in the FIFO at the time a  new
              pattern  is  introduced  are  not  affected.  The status line shows GREP (pattern[,
              ...])  to indicate that grep mode is in effect, and gives  the  list  of  patterns,
              separated by commas. The inverted patterns are indicated by a leading !  character.

       :r[!]  Remove and forget the most recent grep pattern (:gor:v) from the grep stack. If the
              stack depth decrements from 1, the grep mode is disabled and the GREP  status  line
              disappears.  If  the optional !  modifier is added to the command, then it pops the
              entire stack, forgetting all the patterns and disabling grep mode. The modifier  is
              not an argument and may not be separated from the command.

       :i real
              Set the poll interval to the number of seconds specified by real.  See the descrip-
              tion of the -i command line option for the argument format and semantics.

       :l real
              Set the long interval to the number of seconds specified by real.  See the descrip-
              tion of the -i command option for the argument format and the -l option for the se-
              mantics.

       :E, :B Enable extended regular expressions (EREs) or basic regular expressions (BREs), re-
              spectively.  If no -E option is given to the program, then BRE mode is in effect on
              start up.  This setting does not affect the meaning of patterns that are  currently
              in  effect  in  the grep stack or in the trigger.  The setting affects new patterns
              that will subsequently be presented to the program.  Note that the currently active
              patterns  shown in the status line are not accompanied by any indication of whether
              they were compiled as ERE or BRE.

              Any other command string results in a brief error message.

       :f integer
              Capture a triggered snapshot only once every integer times the trigger event occurs
              If integer is 0 or 1, then trigger on every matching event.

              When integer is 1 or more, pw counts the number of trigger events which occur. Only
              when the counter reaches the specified value is a  snapshot  taken;  and  then  the
              counter is reset to zero.

              There  is  an  internal difference between the value 0 and 1 in that 0 disables the
              feature: no counting takes place.

       :c [integer]
              Limit the number of trigger-driven captures to the count specified by integer,  af-
              ter which capture is automatically suspended, as if by the Space command.

              If  integer  is  omitted, then the count of snapshots is reset to zero, without af-
              fecting the configuration that was previously specified by a :c command with an ar-
              gument.

              If  integer  is  zero, then the counting mode is disabled; capture does not suspend
              regardless of how many capture events occur.

              Note that capture events are counted, not trigger events.   Thus,  if  the  capture
              frequency  is reduced using the :f command, then the ignored trigger events are not
              counted.

              When the required number of captures is taken, and capture is suspended, the  trig-
              ger  count is reset to zero. Thus when the Enter command is used to resume capture,
              the same number of capture events will have to occur again before  the  next  auto-
              matic suspension.

       :p [integer[,integer[,integer[,integer[,integer[,integer]]]]]]
              Sets the display parameters, exactly in the manner of the -p option. Any parameters
              not specified are reset to their default initial values: zero in the case of  char-
              acter positions, off in the case of flags.

       :sa [filename]
              Save  a  snapshot  of  the configuration state to the specified file.  The state is
              saved as a sequence of colon and trigger commands, such that the resulting file  is
              suitable  as  an argument to the -f option. If saving the state to filename is suc-
              cessful, then when pw is started up with filename as the argument to the -f option,
              the  grep stack, trigger state and display parameters will be stored to exactly the
              same configuration that existed at the time the state was saved.

EDITING COMMANDS
       The colon command mode and trigger entry modes support rudimentary editing.  The  commands
       are as follows:

       Ctrl-B, Left Arrow
              Move the cursor one character to the left.

       Ctrl-F, Right Arrow
              Move the cursor one character to the right.

       Ctrl-A Move the cursor to the beginning of the line.

       Ctrl-E Move the cursor to the end of the line.

       Backspace
              Erase  the character to the left of the cursor. The ASCII BS and DEL characters are
              both recognized as backspace (an amazing trick not yet mastered by Unix TTY's).  If
              backspace  is used in an empty line, the respective mode terminates without execut-
              ing a command or setting a trigger.

       Ctrl-D Delete the character under the block cursor, or to the right of a  line  or  I-beam
              cursor.

       Ctrl-W Delete  the  word  to the left of the cursor, including any trailing whitespace be-
              tween the word and the cursor.

       Ctrl-U Erase the all the characters to the left of the cursor.

       Ctrl-K Erase the the character under the block cursor, or to the right of a line or I-beam
              cursor, and all characters which follow.

       Ctrl-C, ESC
              Leave edit mode, without executing a colon command or setting a trigger.

OPTIONS
       -i real
              Set  the poll interval to number of seconds specified by real.  This is is a float-
              ing-point constant such as 3 or 1.5. Exponential notation such as 5E-1  (equivalent
              to  0.5) is permitted.  This interval determines the input poll timeout of pw's in-
              put processing loop. If no data arrives from the primary input, or from the TTY for
              this amount of time, a timeout occurs, and the display is refreshed if the FIFO has
              changed since the last refresh.  The default poll interval is 1s.

       -l real
              Set the long update interval to number of seconds specified by real.  The format is
              the  same  as -i, and the default value is 10s. Every time the long update interval
              passes, the display is updated, if the FIFO has  changed  since  the  last  update.
              This  happens even when input is arriving too rapidly to permit the poll timeout to
              take place. The purpose of the long interval is to ensure that  there  are  updates
              even  when  the data source continuously and rapidly produces data, and there is no
              TTY input activity. The long interval should be at least several times longer  than
              the  short interval. The granularity of the timing of the long interval updates de-
              pends on the poll interval; in the absence of TTY input, pw will  not  perform  any
              display  updates  more  often  that the poll interval, even if the long interval is
              made smaller than the poll interval.

       -n integer
              Set the number of lines N to the specified decimal integer value. The default value
              is  15.  This value must be positive, and is clipped to the number of display lines
              available in the terminal, less one.

       -m integer
              Set the maximum line length to integer.  The default value is 4095. Values  smaller
              than  72  are  adjusted  to  72.  The length is measured in display characters, not
              original characters.  A control character like ^C counts as two characters. The be-
              havior  of  pw  is  that when it is collecting a line, and the line has reached the
              maximum length, it keeps reading characters from the standard input,  but  discards
              them, while remaining responsive to TTY input.

       -d     Disable auto-quit: when no more input is available, instead of updating the display
              one last time and terminating, pw will updating the status to EOF  and  staying  in
              the  interactive  mode. This is useful when the last portion of the input is of in-
              terest, and contains long lines that require horizontal scrolling.

       -q integer
              Install a quit count specified by integer which must be positive.  The  quit  count
              determines  how many times the q or Ctrl-C commands have to be issued in succession
              before pw will quit. This is a safeguard against quitting accidentally. The default
              is 1: the commands quit immediately.

       -E     Enable  extended  regular  expressions (EREs). By default, regular expressions pro-
              cessed by pw are treated as basic regular  expressions  (BREs).  The  mode  can  be
              switched at run time using the :E and :B commands.

       -B     Disable  extended regular expressions (EREs), switching to basic (BREs). Since that
              is the default, this option has no effect unless it appears after a -E option.

       -g [!]pattern

              Push pattern onto the grep stack as if using the :v or :g commands,  but  prior  to
              startup, and hence prior to reading any input.

              For more detail, see the :g and :v run-time commands.

              A  leading  !  before the pattern indicates inversion, like what is arranged by the
              :v command. Similarly to the convention in the trigger command syntax, to specify a
              non-inverted  pattern  which  starts  with  a  literal !  character, precede that !
              character with a backslash. This convention is part of  the  -g  option's  argument
              syntax,  and  not a regular expression escape sequence, and is not recognized other
              than before a non-inverted pattern.

              If the -g option is used one or more times, the status display will show GREP  fol-
              lowed by the patterns enclosed in parentheses, as usual.  Patterns pushed by -g may
              be removed interactively with the :r command.

              Whether the pattern argument of a -g is compiled as a BRE or ERE depends on whether
              a  -B  or -E option more recently appeared before that -g option. If neither option
              is used, then pattern is interpreted as a BRE.

       -p [integer[,[integer[,integer[,integer[,integer[,integer]]]]]]
              Specify the display parameters,  as  comma-separated  non-negative  integers.   The
              meaning of these integer values is:

              1.     horizontal scroll position;

              2.     width of left pane;

              3.     width of middle pane;

              4.     middle pane view offset;

              5.     bitmask  of several flags controlling line number display (# command), high-
                     lighting (Ctrl-I/Tab command), and suspended mode (Space command), the  val-
                     ues being internal and undocumented; and

              6.     the tab stop size.

              All five numbers are optional, and default to zero if omitted. Since -p requires an
              argument, the only way all four may be omitted is if a blank or empty  argument  is
              given.   The  tab stop must be in the range 0 to 16. A value of 0 is interpreted as
              8.  The Ctrl-G command displays these same parameters in the same format, so it  is
              possible to set them up interactively and then copy the values shown by Ctrl-G.

       -e command
              Execute a colon or trigger command. For instance

                -e :c15

              sets  the  capture  count  to  15.  Note that the colon is included in the command.
              Trigger commands may be preceded by a count. For example:

                -e 3/^Failed

              sets a head-referenced trigger for the pattern ^Failed matching against line  3  of
              the FIFO.

       -f file
              Read colon and trigger commands from file and execute them.

              Each line of file must contain either a command in the same form as the argument of
              the -e option, or else a comment indicated by the first character being # (hash).

              If any line is diagnosed as erroneous, a diagnostic is issued and execution contin-
              ues. In this case, pw will terminate unsuccessfully after file is read.

              Command  lines  with leading whitespace are invalid, and trailing whitespace counts
              as a command character (for example, as a constituent of a pattern),

ENVIRONMENT
       pw ignores the TERM environment variable, requiring an ANSI terminal.

       pw requires the following conditions to hold in regard to its execution environment,  oth-
       erwise it terminates with an error diagnostic:

       1.     It must be possible to open the /dev/tty device,

       2.     Standard  input  is  either  not  a  TTY device, or else not the same TTY device as
              /dev/tty.

TERMINATION STATUS
       If pw reaches EOF on standard input without encountering a read error, then  its  termina-
       tion  status will be successful.  This is regardless of whether it automatically quits, or
       whether it stays in interactive mode and then quits due to a quit command.   If  the  data
       ends prematurely due to a read error, or if the program is asked to quit before all of the
       data has been read, then unsuccessful termination status will be indicated.

       Incorrect usage, such as nonexistent options or bad arguments to options, result in a  di-
       agnostic on standard error and an unsuccessful termination.

       Unexpected conditions like out of memory result in abnormal termination (abort).

BUGS
       This was written over the course of a couple of hours, and tested only interactively.

       Many of the issues which follow are easy; patches welcome.

       The display format, such as the handling of control characters, is hard-coded.

       The  program  uses hard-coded ANSI sequences, so it doesn't support interesting old termi-
       nals. On the other hand,  it  carries  no  dependency  on  any  terminal  abstraction  li-
       brary/data.

       There  is  no support for unwrapping long lines, which would be useful for copy and paste.
       However, the features like :w to save the displayed data somewhat compensate for this.

       During the :!  command's execution, the TTY settings are not restored.

       The timeout isn't applied to the arrival of data into the FIFO, but on the arrival of data
       into  the  program. Therefore, the grep stack feature doesn't necessarily do what you want
       in terms of the timeout-based refresh behavior.  Consider a situation in which  ten  lines
       are arriving per second at a steady rate. The default 1s timeout therefore never goes off.
       The long refresh interval is what is updating the display, every 10s by default. Now  sup-
       pose you put in a :gpattern command which only passes every 20th line. Effectively, it now
       looks as if a line appears every 2s, and so the 1s timeout should be going off to  refresh
       the  display.  Unfortunately,  that's not how it works. The program is still receiving ten
       lines per second from standard input, and that's where the timeout is applied.  Until that
       is  fixed,  the  way  to get more timely refresh behavior under heavy filtering is to play
       with the long interval.

       If the terminal window is resized to a narrower size, many terminals wrap any  lines  that
       would get truncated by the operation and this makes a mess of the display. While pw recov-
       ers the display area, wrapped lines get pushed above it and remain. This issue  is  likely
       unfixable,  other  than  by  implementing a text-editor-like full screen mode which has no
       scroll back above the display, and which recovers the prior content when exiting.

       There is some funniness when line number mode is turned on and pw  is  in  the  middle  of
       filling the FIFO to match the display size. You will see line number values of zero, which
       then correct themselves when the display is refreshed. This is by design,  for  very  good
       reasons.  Patches to try to fix this will be rejected in the strongest terms.

       Difference  highlighting  mode is confusing when comparing snapshots that overlap, or that
       are entirely unrelated. The way it is implemented makes it primarily useful with snapshots
       that  are triggered and filtered for similarity.  It doesn't track insertions or deletions
       of characters; If 999 changes to 1000, the rest of the line will be be  different,  except
       for characters that are still the same by coincidence.

SEE ALSO
       pw-relnotes(5)

AUTHOR
       Kaz Kylheku <kaz@kylheku.com>

COPYRIGHT
       Copyright 2022-2023, BSD2 License.

Version 3                                  10 Mar 2022                                      PW(1)