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

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.
 	 */