## What is `pw`?
`pw` stands for Pipe Watch. Pipe Watch is a new, unique text stream monitoring
utility for Unix-like systems, developed starting in April 2022.
Pipe Watch is used similarly to a pager, like the `less` utility, but the
paradigm is quite different.
## Demo Video
## More Info
`pw` can monitor anything that produces textual output. `tail -f /var/logfile`,
`tcpdump`, `strace`, ...
`pw` does not show you everything. Of course, it reads all the data, but it
does that in the background. It continuously pumps lines of input through a
small FIFO buffer. This buffer is sampled, and the sample is displayed. When
that sampling occurs is controlled in various interactive ways. What goes into
the FIFO can be filtered and the filters can be edited interactively.
With `pw` you can:
* Interactively apply and remove filters on-the-fly, without interrupting
the source.
* Make recurring patterns in the stream appear to "freeze" on the screen, using
triggers.
* Prevent the overwhelming amount of output from a program from flooding the
terminal, while consuming all of that output so that the program isn't
blocked. `pw` can pause its display updates entirely.
* Juggle multiple shell background jobs that produce output, yet execute
indefinitely without blocking. When `pw` runs as part of a shell
background job, it continues to consume input, process filters and take
snapshots, without displaying anything. When put into the foreground again,
display resumes.
For instance the command `tcpdump -i -l | pw` turns `tcpdump`
into an interactive network monitoring tool in which you can use the dynamic
filtering in `pw` to select different kinds of packets, and use the trigger
feature to capture certain patterns of interaction.
`pw` is like an oscilloscope for text streams. Digital oscilloscopes
sample the signal and pass it through a fifo, which is sampled to the
oscilloscope screen, and can trigger the sampling on certain conditions in the
signal to make waveforms appear to stand still. `pw` does something like that
for text streams.
## Dependencies and Resource Use
* **`pw` has very low dependencies**: it requires libraries other than the
POSIX standard functions; all terminal control is via ANSI sequences. It does
like to have a `struct winsize` and an `ioctl` to fill it in. There is a
seven line GNU Makefile to build it. If that doesn't work for you, try it
some other way. It tested it on on Solaris 10, and older Mac OS, Cygwin and a
few GNU/Linuxes. It built on OpenBSD, but didn't run properly; I didn't
investigate into it. Patches welcome.
* **`pw` is tiny:** it is a little over 2000 lines of C in a single source
file, compiling to an executable of around 32 kilobytes.
(Except on MacOS, where an additional file called `macpoll.c` is
compiled and linked in, because MacOS's `poll` function does not work with
devices such as TTYs, only pipes and sockets.)
* **`pw` requires a very low amount of RAM:** Given inputs with typical line
lengths, and 24 line snapshots, `pw` it needs less than 64 kilobytes of RAM
to store the data which is passing through it.
## Documentation
The [`pw` man page](../tree/pw.1) has all the usage details.
## License
`pw` is offered under the two-clause BSD license. See the
[`LICENSE`](../tree/LICENSE) file.
## Other Videos
Original Demo:
Vertical Panes Demo
## High Level State Diagram
