diff options
| -rw-r--r-- | README.md | 53 |
1 files changed, 28 insertions, 25 deletions
@@ -10,7 +10,7 @@ Unix-like systems, developed starting in April 2022. ## More Info `pw` can monitor anything that produces textual output. `tail -f /var/logfile`, -`tcpdump`, you name it. +`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 @@ -18,47 +18,50 @@ 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 do things like: +With `pw` you can: -* Look for certain pieces of known information in live textual data. +* Interactively apply and remove filters on-the-fly, without interrupting + the source. -* Explore the data to discover information and patterns. +* Make recurring patterns in the stream appear to "freeze" on the screen, using + triggers. -* Make recurring patterns in the stream appear to "freeze" with -on the screen triggered snapshots. +* Prevent the overwhelming amount of output from a program to flooding the + terminal, while consuming all of that output so that the program isn't + blocked. `pw` can pause its display updates entirely. -* Prevent the overwhelming amount of output from a program to flooding -the terminal, while consuming all of that output so that the program -isn't blocked. `pw` can pause its display updates entirely. - -* Gain visibility into the diagnostic stream produced by a program, -and analytic ability, without having to capture and store any large -subset (or all) of that data anywhere. +* Juggle multiple shell background jobs that produce output, yet execute + indefinitely without blocking. When `pw` runs as as part of a shell + background job, it consumes and discards input, like a `/dev/null` device. + When put into the foreground again, it displays data. For instance the command `tcpdump -i <ethernet-device> -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. Modern digital oscilloscopes +`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. -All of the above is achieved with low resources. `pw` is a little over 1200 -lines of code, all in one source file, compiling to a tiny executable. It only -retains a small number of snapshots of small windows the real-time input, -storage for which requires requiring less than 64 kilobytes of memory. +## 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. -## Dependencies +* **`pw` is tiny:** it is around 1300 lines of C in a single source file, + compiling to an executable of around 25 kilobytes. -`pw` depends on no 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` 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 |