From bd4ca7301c47a85e28a1da908f6cb2f44971226b Mon Sep 17 00:00:00 2001 From: Andrew Wood Date: Sat, 4 Oct 2025 20:17:46 +0100 Subject: [PATCH] Document the new "=NAME" (#95) and "@FILE" (#12) syntax for --watchfd options. --- docs/pv.1 | 15 +++++++++++---- docs/pv.1.md | 16 ++++++++++++---- src/main/options.c | 3 --- 3 files changed, 23 insertions(+), 11 deletions(-) diff --git a/docs/pv.1 b/docs/pv.1 index 15f1065..bc90b78 100644 --- a/docs/pv.1 +++ b/docs/pv.1 @@ -7,7 +7,8 @@ pv \- monitor the progress of data through a pipe .B pv [\fIOPTION\fR]... [\fIFILE\fR]... .PP -\fBpv\fR [\fIOPTION\fR]... \fB\-d\fR|\fB\-\-watchfd\fR \fIPID\fR[:\fIFD\fR]... +\fBpv\fR [\fIOPTION\fR]... \fB\-d\fR|\fB\-\-watchfd\fR +\fIPID\fR[:\fIFD\fR]|=\fINAME\fR|@\fILISTFILE\fR... .PP \fBpv\fR \fB\-R\fR|\fB\-\-remote\fR \fIPID\fR [\fIOPTION\fR]... .\" @@ -349,7 +350,7 @@ doesn't affect the progress display. .\" .SS "Alternative operating modes" .TP -.BI \-d\ PID\fR[\fB:\fR\fIFD\fR],\ \fB\-\-watchfd\ PID\fR[\fB:\fR\fIFD\fR] +\fB\-d\fR, \fB\-\-watchfd\fR \fIPID\fR[\fB:\fR\fIFD\fR]|=\fINAME\fR|@\fILISTFILE\fR... Instead of transferring data, watch file descriptor \fIFD\fR of process \fIPID\fR, and show its progress. Other data transfer modifiers - and remote control - may not be used with @@ -359,8 +360,14 @@ If a \fIPID\fR is specified without an \fIFD\fR, then that process will be watched, and all regular files and block devices it opens will be shown with a progress bar. .IP -All remaining non-option arguments will also be treated as -\fIPID\fRs or as \fIPID\fR:\fIFD\fR pairs. +If a \fINAME\fR is specified, prefixed with "=", then processes with that +name will be found with \fBpgrep\fR(1), and as watched described above. +.IP +If a \fILISTFILE\fR is specified, prefixed with "@", the lines in that file +will be used as additional arguments. +.IP +All remaining non-option arguments will also be treated as additional +arguments. .IP The \fBpv\fR process will exit when all \fIFD\fRs have either changed to a different file, changed read/write mode, or have closed, and all \fIPID\fRs diff --git a/docs/pv.1.md b/docs/pv.1.md index 9d539f5..9ffe6d3 100644 --- a/docs/pv.1.md +++ b/docs/pv.1.md @@ -6,7 +6,8 @@ pv - monitor the progress of data through a pipe **pv** \[*OPTION*\]\... \[*FILE*\]\... -**pv** \[*OPTION*\]\... **-d**\|**\--watchfd** *PID*\[:*FD*\]\... +**pv** \[*OPTION*\]\... **-d**\|**\--watchfd** +*PID*\[:*FD*\]\|=*NAME*\|@*LISTFILE*\... **pv** **-R**\|**\--remote** *PID* \[*OPTION*\]\... @@ -361,7 +362,7 @@ are explicitly switched on will be shown. ## Alternative operating modes -**-d PID\[:FD\], \--watchfd PID\[:FD\]** +**-d**, **\--watchfd** *PID*\[**:***FD*\]\|=*NAME*\|@*LISTFILE*\... : Instead of transferring data, watch file descriptor *FD* of process *PID*, and show its progress. Other data transfer modifiers - and @@ -371,8 +372,15 @@ are explicitly switched on will be shown. watched, and all regular files and block devices it opens will be shown with a progress bar. - All remaining non-option arguments will also be treated as *PID*s or - as *PID*:*FD* pairs. + If a *NAME* is specified, prefixed with \"=\", then processes with + that name will be found with **pgrep**(1), and as watched described + above. + + If a *LISTFILE* is specified, prefixed with \"@\", the lines in that + file will be used as additional arguments. + + All remaining non-option arguments will also be treated as + additional arguments. The **pv** process will exit when all *FD*s have either changed to a different file, changed read/write mode, or have closed, and all diff --git a/src/main/options.c b/src/main/options.c index 8b25f31..4b77bf9 100644 --- a/src/main/options.c +++ b/src/main/options.c @@ -157,7 +157,6 @@ static bool opts_watchfd_add_item(opts_t opts, pid_t pid, int fd) */ static bool opts_watchfd_processname(opts_t opts, const char *process_name) { - /* TODO: document "-d =NAME" syntax */ /* TODO: read from pgrep, without using popen() or system() */ return false; } @@ -173,8 +172,6 @@ static bool opts_watchfd_listfile(opts_t opts, const char *filename) char buffer[1024]; /* flawfinder: ignore */ unsigned int linenumber; - /* TODO: document "-d @FILE" syntax */ - /* * flawfinder: buffer is zeroed before each use, and fgets() is * passed one less than its size so the string functions in the loop