Draft documentation and option parsing for a "--monitor" option to run a command and monitor its input and output (#67).

src/include/options.h

@@ -32,7 +32,8 @@ typedef enum {
 	PV_ACTION_STORE_AND_FORWARD,	/* store to file, then output from it */
 	PV_ACTION_WATCHFD,		/* watch process file descriptors */
 	PV_ACTION_REMOTE_CONTROL,	/* remotely control another pv */
-	PV_ACTION_QUERY			/* watch the state of another pv */
+	PV_ACTION_QUERY,		/* watch the state of another pv */
+	PV_ACTION_MONITOR		/* run a process, watch its stdin/out */
 } pvaction_t;
 
 /*

src/main/help.c

@@ -372,6 +372,9 @@ void display_help(void)
 		 N_("show progress of process PID"),
 		 { 0, 0, 0, 0} },
 #endif				/* PV_REMOTE_CONTROL */
+		{ "-M", "--monitor", NULL,
+		 N_("monitor the input and output of a command"),
+		 { 0, 0, 0, 0} },
 		{ "", NULL, NULL, NULL, { 0, 0, 0, 0} },
 		{ "-P", "--pidfile", N_("FILE"),
 		 N_("save process ID in FILE"),

src/main/main.c

@@ -560,6 +560,11 @@ int main(int argc, char **argv)
 		/* Query the progress of another running pv. */
 		retcode = pv_query_loop(state, opts->query);
 		break;
+	case PV_ACTION_MONITOR:
+		/* Run a process and monitor its input and output. */
+		/* TODO: run the monitor action. */
+		retcode = 1;
+		break;
 	}
 
 	/* Clear up the PID file, if one was written. */

src/main/options.c

@@ -680,6 +680,7 @@ opts_t opts_parse(unsigned int argc, char **argv)
 		{ "watchfd", 1, NULL, (int) 'd' },
 		{ "output", 1, NULL, (int) 'o' },
 		{ "average-rate-window", 1, NULL, (int) 'm' },
+		{ "monitor", 0, NULL, (int) 'M' },
 #ifdef ENABLE_DEBUGGING
 		{ "debug", 1, NULL, (int) '!' },
 #endif				/* ENABLE_DEBUGGING */
@@ -688,7 +689,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:Q: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:M"
 #ifdef ENABLE_DEBUGGING
 	    "!:"
 #endif
@@ -1102,6 +1103,9 @@ opts_t opts_parse(unsigned int argc, char **argv)
 		case 'm':
 			opts->average_rate_window = pv_getnum_count(optarg, opts->decimal_units);
 			break;
+		case 'M':
+			opts->action = PV_ACTION_MONITOR;
+			break;
 #ifdef ENABLE_DEBUGGING
 		case '!':
 			debugging_output_destination(optarg);
@@ -1250,6 +1254,18 @@ opts_t opts_parse(unsigned int argc, char **argv)
 		/*@+mustfreefresh@ */
 	}
 
+	/*
+	 * At least one non-option argument is required with -M.
+	 */
+	if ((PV_ACTION_MONITOR == opts->action) && (optind >= (int) argc)) {
+		/*@-mustfreefresh@ *//* see above */
+		fprintf(stderr, "%s: -M: %s\n", opts->program_name,
+			_("a command to run must be specified"));
+		opts_free(opts);
+		return NULL;
+		/*@+mustfreefresh@ */
+	}
+
 	/*
 	 * Store remaining command-line arguments.
 	 */