path: root/pw.1

PW(1)                                       Pipe Watch                                      PW(1)

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

SYNOPSIS
       command | pw [options] command | pw [options] | next-command command | pw [options] > file

DESCRIPTION
       pw  ("Pipe Watch") is an interactive data monitoring utility which may be used as the ter-
       minating point of a command pipeline, or a middle element.

       pw requires a session with a controlling TTY. The TTY should be connected to an ANSI  ter-
       minal.  The  controlling TTY does not have to be the standard input or output of pw, since
       the utility gains access to the TTY by opening /dev/tty.

       When pw is used as the last element of the pipeline, it reads data from its  standard  in-
       put,  and  discards it (discard mode). When used as a middle pipeline element, or when its
       output is redirected to a file, or to a device other than the controlling TTY of the  ses-
       sion, it passes data from its standard input to its standard output (pass-through mode).

       In  parallel  with  passing  or discarding data pw provides a useful visual display on the
       controlling terminal, and also takes interactive commands from the terminal.

       In addition, when pw is placed into the job control background and permitted  to  execute,
       it  keeps reading and passing/discarding it without updating the display, while all of its
       features such as triggers remain active.

       The visual display is based on a concept whereby lines are passing through a line-oriented
       FIFO  buffer,  which  is sampled at various times. The samples are used to update the dis-
       play.

       Around program startup, while the FIFO buffer is not yet full,  lines  arriving  into  the
       FIFO  are displayed immediately.  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,  and
              of  the  line numbers of snapshot lines which activated a trigger. When toggled on,
              the >, < and | characters which indicate line truncation and  pane  separation  are
              shown in inverse video (dark foreground, light background).  At the moment when the
              conditions are met for recording a new triggered snapshot, all  lines  targeted  by
              trigger  patterns  (which  must necessarily all have matched) are flagged for high-
              lighting. Whenever line numbers are enabled with the # command, and highlighting is
              enabled,  then  the  line  numbers of the flagged lines are shown in inverse video.
              Once a line is flagged, it stays flagged as it moves through the FIFO  and  through
              the snapshot history.

       [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  its  standard input, and possibly pass the data it to its
              standard output, without updating 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 muffles their output, while allowing
              them to execute indefinitely. Because pw is reading their output, they never  block
              on  a  pipe write.  At any time any such a backgrounded 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.

              Note that the grep filtering has no effect on the data passing  through  pw.   When
              the  utility  is  in  pass-through mode, it copies all bytes from standard input to
              standard output, regardless of the snapshots, triggers or filtering, which only af-
              fect the interactive features.

       :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 and processing characters from the standard input,
              without  appending them to the currently accumulating line, until the newline char-
              acter occurs.

       -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 6                                   6 Oct 2024                                      PW(1)