Draft manual entry, help text, and option parsing for "--query" option (#101).

docs/pv.1

@@ -11,6 +11,8 @@ pv \- monitor and manage the progress of data through a pipe
 \fIPID\fR[:\fIFD\fR]|=\fINAME\fR|@\fILISTFILE\fR...
 .PP
 \fBpv\fR \fB\-R\fR|\fB\-\-remote\fR \fIPID\fR [\fIOPTION\fR]...
+.PP
+\fBpv\fR \fB\-Q\fR|\fB\-\-query\fR \fIPID\fR [\fIOPTION\fR]...
 .\"
 .SH DESCRIPTION
 Show the progress of data through a pipeline by giving information such as
@@ -395,6 +397,16 @@ Note that some options cannot be changed while running, such as
 \*(lq\fB\-\-cursor\fR\*(rq, \*(lq\fB\-\-line\-mode\fR\*(rq,
 \*(lq\fB\-\-force\fR\*(rq, \*(lq\fB\-\-delay\-start\fR\*(rq,
 \*(lq\fB\-\-skip\-errors\fR\*(rq, and \*(lq\fB\-\-stop\-at\-size\fR\*(rq.
+.TP
+.BI \-Q\  PID \fR,\ \fB\-\-query\  PID
+Display the transfer progress of another instance of \fBpv\fR with process
+ID \fIPID\fR.
+Some output modifiers can only be used while querying another process if
+they match those of that process - such as
+\*(lq\fB\-\-line\-mode\fR\*(rq,
+\*(lq\fB\-\-null\fR\*(rq, and
+\*(lq\fB\-\-average\-rate\-window\fR\*(rq.
+Data transfer modifiers will have no effect.
 .\"
 .SS "Other options"
 .TP

docs/pv.1.md

@@ -11,6 +11,8 @@ pv - monitor and manage the progress of data through a pipe
 
 **pv** **-R**\|**\--remote** *PID* \[*OPTION*\]\...
 
+**pv** **-Q**\|**\--query** *PID* \[*OPTION*\]\...
+
 # DESCRIPTION
 
 Show the progress of data through a pipeline by giving information such
@@ -410,6 +412,15 @@ are explicitly switched on will be shown.
     "**\--delay-start**", "**\--skip-errors**", and
     "**\--stop-at-size**".
 
+**-Q PID, \--query PID**
+
+:   Display the transfer progress of another instance of **pv** with
+    process ID *PID*. Some output modifiers can only be used while
+    querying another process if they match those of that process - such
+    as "**\--line-mode**", "**\--null**", and
+    "**\--average-rate-window**". Data transfer modifiers will have no
+    effect.
+
 ## Other options
 
 **-P FILE, \--pidfile FILE**

src/include/options.h

@@ -58,6 +58,7 @@ struct opts_s {
 	off_t size;                    /* total size of data */
 	off_t error_skip_block;        /* skip block size, 0 for adaptive */
 	pid_t remote;                  /* PID of pv to update settings of */
+	pid_t query;                   /* PID of pv to query progress of */
 	unsigned int skip_errors;      /* skip read errors counter */
 	unsigned int average_rate_window; /* time window in seconds for average rate calculations */
 	unsigned int width;            /* screen width */

src/main/help.c

@@ -368,6 +368,11 @@ void display_help(void)
 		 N_("update settings of process PID"),
 		 { 0, 0, 0, 0} },
 #endif				/* PV_REMOTE_CONTROL */
+#ifdef PV_REMOTE_QUERY
+		{ "-Q", "--query", N_("PID"),
+		 N_("show progress of process PID"),
+		 { 0, 0, 0, 0} },
+#endif				/* PV_REMOTE_QUERY */
 		{ "", NULL, NULL, NULL, { 0, 0, 0, 0} },
 		{ "-P", "--pidfile", N_("FILE"),
 		 N_("save process ID in FILE"),

src/main/main.c

@@ -368,6 +368,8 @@ int main(int argc, char **argv)
 		}
 	}
 
+	/* TODO: add logic for --query mode. */
+
 	/*
 	 * If no files were given, pretend "-" was given (stdin).
 	 */

src/main/options.c

@@ -617,6 +617,7 @@ opts_t opts_parse(unsigned int argc, char **argv)
 		{ "discard", 0, NULL, (int) 'X' },
 		{ "store-and-forward", 1, NULL, (int) 'U' },
 		{ "remote", 1, NULL, (int) 'R' },
+		{ "query", 1, NULL, (int) 'Q' },
 		{ "pidfile", 1, NULL, (int) 'P' },
 		{ "watchfd", 1, NULL, (int) 'd' },
 		{ "output", 1, NULL, (int) 'o' },
@@ -629,7 +630,7 @@ opts_t opts_parse(unsigned int argc, char **argv)
 	/*@+nullassign@ */
 	int option_index = 0;
 #endif				/* HAVE_GETOPT_LONG */
-	char *short_options = "hVpteIrab8kTA:fvnqcWD:s:gl0i:w:H:N:u:F:x:L:B:CEZ:SYKOXU:R:P:d:m:o:"
+	char *short_options = "hVpteIrab8kTA:fvnqcWD:s:gl0i:w:H:N:u:F:x:L:B:CEZ:SYKOXU:R:Q:P:d:m:o:"
 #ifdef ENABLE_DEBUGGING
 	    "!:"
 #endif
@@ -733,6 +734,8 @@ opts_t opts_parse(unsigned int argc, char **argv)
 			/*@fallthrough@ */
 		case 'R':
 			/*@fallthrough@ */
+		case 'Q':
+			/*@fallthrough@ */
 		case 'm':
 			if (!pv_getnum_check(optarg, PV_NUMTYPE_BARE_INTEGER)) {
 				/*@-mustfreefresh@ *//* see above */
@@ -994,6 +997,9 @@ opts_t opts_parse(unsigned int argc, char **argv)
 		case 'R':
 			opts->remote = (pid_t) pv_getnum_count(optarg, false);
 			break;
+		case 'Q':
+			opts->query = (pid_t) pv_getnum_count(optarg, false);
+			break;
 		case 'P':
 			opts->pidfile = pv_strdup(optarg);
 			if (NULL == opts->pidfile) {
@@ -1102,6 +1108,15 @@ opts_t opts_parse(unsigned int argc, char **argv)
 			/*@+mustfreefresh@ */
 		}
 
+		if (0 != opts->query) {
+			/*@-mustfreefresh@ *//* see above */
+			fprintf(stderr, "%s: %s\n", opts->program_name,
+				_("cannot use remote query when watching file descriptors"));
+			opts_free(opts);
+			return NULL;
+			/*@+mustfreefresh@ */
+		}
+
 		if (NULL != opts->output) {
 			/*@-mustfreefresh@ *//* see above */
 			fprintf(stderr, "%s: -o: %s\n", opts->program_name,
@@ -1138,6 +1153,16 @@ opts_t opts_parse(unsigned int argc, char **argv)
 #endif
 	}
 
+	/* Don't allow -R and -Q together. */
+	if ((0 != opts->remote) && (0 != opts->query)) {
+		/*@-mustfreefresh@ *//* see above */
+		fprintf(stderr, "%s: %s\n", opts->program_name,
+			_("cannot use remote control and remote query together"));
+		opts_free(opts);
+		return NULL;
+		/*@+mustfreefresh@ */
+	}
+
 	/*
 	 * Default options: -pterb
 	 */
@@ -1153,6 +1178,8 @@ opts_t opts_parse(unsigned int argc, char **argv)
 	if (opts->error_skip_block > 0 && 0 == opts->skip_errors)
 		opts->skip_errors = 1;
 
+	/* TODO: error if -Q given and there are any remaining arguments. */
+
 	/*
 	 * Store remaining command-line arguments.
 	 */