Improvement of docs, help messages and addition of long options

This patch adds the following things for pg_top:
- Improved man documentation (connection options were missing)
- long options, with some options being normalized to the PostgreSQL
standards
- a more complete help message with all the options

2 files changed, 132 insertions, 55 deletions

diff --git a/pg_top.1.in b/pg_top.1.in
index 4e666e0..d0f2818 100644
--- a/pg_top.1.in
+++ b/pg_top.1.in
@@ -8,29 +8,7 @@
 pg_top \- display and update information about the top cpu PostgreSQL processes
 .SH SYNOPSIS
 .B pg_top
-[
-.B \-ITWbcinqu
-] [
-.BI \-d DBNAME
-] [
-.BI \-h HOSTNAME
-] [
-.BI \-o field
-] [
-.BI \-p PORT
-] [
-.BI \-r
-] [
-.BI \-s time
-] [
-.BI \-U USER
-] [
-.BI \-x count
-] [
-.BI \-z username
-] [
-.I number
-]
+[ OPTIONS ] [ NUMBER ]
 .SH DESCRIPTION
 .\" This defines appropriate quote strings for nroff and troff
 .ds lq \&"
@@ -68,30 +46,30 @@ is redirected to a file, it acts as if it were being run on a dumb
 terminal.
 .SH OPTIONS
 .TP
-.B \-C
+.B \-C, \-\-color-mode
 Turn off the use of color in the display.
 .TP
-.B \-I
+.B \-I, \-\-hide-idle
 Do not display idle processes.
 By default, pg_top displays both active and idle processes.
 .TP
-.B \-T
+.B \-T, \-\-show-tags
 List all available color tags and the current set of tests used for
 color highlighting, then exit.
 .TP
-.B \-W
+.B \-W, \-\-password
 Forces pg_top to prompt for a password before connecting to a database.
 .TP
-.B \-b
+.B \-b, \-\-batch
 Use \*(lqbatch\*(rq mode.  In this mode, all input from the terminal is
 ignored.  Interrupt characters (such as ^C and ^\e) still have an effect.
 This is the default on a dumb terminal, or when the output is not a terminal.
 .TP
-.B \-c
+.B \-c, \-\-show-command
 Show the command name for each process. Default is to show the full
 command line.  This option is not supported on all platforms.
 .TP
-.B \-i
+.B \-i, \-\-interactive
 Use \*(lqinteractive\*(rq mode.  In this mode, any input is immediately
 read for processing.  See the section on \*(lqInteractive Mode\*(rq
 for an explanation of
@@ -100,24 +78,24 @@ screen will immediately be updated, even if the command was not
 understood.  This mode is the default when standard output is an
 intelligent terminal.
 .TP
-.B \-n
+.B \-n, \-\-non-interactive
 Use \*(lqnon-interactive\*(rq mode.  This is indentical to \*(lqbatch\*(rq
 mode.
 .TP
-.B \-q
+.B \-q, \-\-quick-mode
 Renice
 .I pg_top
 to \-20 so that it will run faster.  This can be used when the system is
 being very sluggish to improve the possibility of discovering the problem.
 This option can only be used by root.
 .TP
-.B \-r
+.B \-r, \-\-remote-mode
 Monitor a remote database where the database is on a system other than where
 pg_top is running from.
 .I pg_top
 will monitor a remote database if it has the pg_proctab extension installed.
 .TP
-.B \-u
+.B \-u, \-\-show-uid
 Do not take the time to map uid numbers to usernames.  Normally,
 .I pg_top
 will read as much of the file \*(lq/etc/passwd\*(rq as is necessary to map
@@ -125,24 +103,25 @@ all the user id numbers it encounters into login names.  This option
 disables all that, while possibly decreasing execution time.  The uid
 numbers are displayed instead of the names.
 .TP
-.B \-v
+.B \-V, \-\-version
 Write version number information to stderr then exit immediately.
 No other processing takes place when this option is used.  To see current
 revision information while pg_top is running, use the help command \*(lq?\*(rq.
 .TP
-.BI \-s time
+\fB\-s \fR\fB\fITIME\fR\fR, \fB\-\-set-delay=\fR\fB\fITIME\fR\fR
+.I TIME
 Set the delay between screen updates to
-.I time
+.I TIME
 seconds.  The default delay between updates is \nD seconds.
 .TP
-.BI \-o field
+\fB\-o \fR\fB\fIFIELD\fR\fR, \fB\-\-order-field=\fR\fB\fIFIELD\fR\fR
 Sort the process display area on the specified field.  The field name is
 the name of the column as seen in the output, but in lower case.  Likely
 values are \*(lqcpu\*(rq, \*(lqsize\*(rq, \*(lqres\*(rq, and \*(lqtime\*(rq,
 but may vary on different operating systems.  Note that
 not all operating systems support this option.
 .TP
-.BI \-x count
+\fB\-x \fR\fB\fICOUNT\fR\fR, \fB\-\-set-display=\fR\fB\fICOUNT\fR\fR
 Show only
 .I count
 displays, then exit.  A display is considered to be one update of the
@@ -152,16 +131,33 @@ wants to see before
 automatically exits.  For intelligent terminals, no upper limit
 is set.  The default is 1 for dumb terminals.
 .TP
-.BI \-z username
+\fB\-z \fR\fB\fIUSERNAME\fR\fR, \fB\-\-show-username=\fR\fB\fIUSERNAME\fR\fR
 Show only those processes owned by
-.IR username .
+.IR USERNAME .
 This option currently only accepts usernames and will not understand
 uid numbers.
+.TP
+\fB\-h \fR\fB\fIHOST\fR\fR, \fB\-\-host=\fR\fB\fIHOST\fR\fR
+Specifies the host name of the machine on which the server is running. If
+the value begins with a slash, it is used as the directory for the Unix
+domain socket. The default is taken from the PGHOST environment variable,
+if set.
+.TP
+\fB\-p \fR\fB\fIPORT\fR\fR, \fB\-\-port=\fR\fB\fIPORT\fR\fR
+Specifies the TCP port or local Unix domain socket file extension on which
+the server is listening for connections. Defaults to the PGPORT environment
+variable, if set.
+.TP
+\fB\-U \fR\fB\fIUSERNAME\fR\fR, \fB\-\-username=\fR\fB\fIUSERNAME\fR\fR
+User name to connect as.
+.TP
+.B \-W, \-\-password
+Force pg_top to prompt for a password before connecting to a database.
 .PP
 Both
-.I count
+.I COUNT
 and
-.I number
+.I NUMBER
 fields can be specified as \*(lqinfinite\*(rq, indicating that they can
 stretch as far as possible.  This is accomplished by using any proper
 prefix of the keywords
diff --git a/pg_top.c b/pg_top.c
index 7b22b1e..34f9fde 100644
--- a/pg_top.c
+++ b/pg_top.c
@@ -34,6 +34,7 @@ char	   *copyright =
 #include <setjmp.h>
 #include <ctype.h>
 #include <unistd.h>
+#include <getopt.h>
 
 /* determine which type of signal functions to use */
 #ifdef HAVE_SIGACTION
@@ -86,6 +87,11 @@ static int	max_topn;			/* maximum displayable processes */
 char	   *myname = "top";
 jmp_buf		jmp_int;
 
+/* internal variables */
+static const char *progname = "pg_top";
+
+static void usage(const char *progname);
+
 /* pointers to display routines */
 void		(*d_loadave) (int, double *) = i_loadave;
 void		(*d_minibar) (
@@ -111,6 +117,43 @@ int			mode_stats = STATS_DIFF;
 int mode_remote = 0;
 
 /*
+ *	usage - print help message with details about commands
+ */
+static void
+usage(const char *progname)
+{
+	printf("%s monitors a PostgreSQL database cluster.\n\n", progname);
+	printf("Usage:\n");
+	printf("  %s [OPTION]... [NUMBER]\n", progname);
+	printf("\nOptions:\n");
+	printf("  -b, --batch               use batch mode\n");
+	printf("  -c, --show-command        display command name of each process\n");
+	printf("  -C, --color-mode          turn off color mode\n");
+	printf("  -i, --interactive         use interactive mode\n");
+	printf("  -I, --hide-idle           hide idle processes\n");
+	printf("  -n, --non-interactive     use non-interactive mode\n");
+	printf("  -o, --order-field=FIELD   select sort order\n");
+	printf("  -q, --quick-mode          modify schedule priority\n");
+	printf("                            usable only by root\n");
+	printf("  -r, --remote-mode         activate remote mode\n");
+	printf("  -s, --set-delay=SECOND    set delay between screen updates\n");
+	printf("  -T, --show-tags           show color tags\n");
+	printf("  -u, --show-uid            show UID instead of username\n");
+	printf("  -V, --version             output version information, then exit\n");
+	printf("  -x, --set-display=COUNT   set maximum number of displays\n");
+	printf("                            exit once this number is reached\n");
+	printf("  -z, --show-username=NAME  display only processes owned by given\n");
+	printf("                            username\n");
+	printf("  -?, --help                show this help, then exit\n");
+	printf("\nConnection options:\n");
+	printf("  -d, --dbname=DBNAME       database to connect to\n");
+	printf("  -h, --host=HOSTNAME       database server host or socket directory\n");
+	printf("  -p, --port=PORT           database server port\n");
+	printf("  -U, --username=USERNAME   user name to connect as\n");
+	printf("  -W, --password            force password prompt\n");
+}
+
+/*
  *	reset_display() - reset all the display routine pointers so that entire
  *	screen will get redrawn.
  */
@@ -243,12 +286,37 @@ onalrm(int i)					/* SIGALRM handler */
 
 int
 main(int argc, char *argv[])
-
 {
 	register int i;
 	register int active_procs;
 	register int change;
 
+	/* List of all the options available */
+	static struct option long_options[] = {
+		{"batch", no_argument, NULL, 'b'},
+		{"show-command", no_argument, NULL, 'c'},
+		{"color-mode", no_argument, NULL, 'C'},
+		{"interactive", no_argument, NULL, 'i'},
+		{"hide-idle", no_argument, NULL, 'I'},
+		{"non-interactive", no_argument, NULL, 'n'},
+		{"order-field", required_argument, NULL, 'o'},
+		{"quick-mode", no_argument, NULL, 'q'},
+		{"remote-mode", no_argument, NULL, 'r'},
+		{"set-delay", required_argument, NULL, 's'},
+		{"show-tags", no_argument, NULL, 'T'},
+		{"show-uid", no_argument, NULL, 'u'},
+		{"version", no_argument, NULL, 'V'},
+		{"set-display", required_argument, NULL, 'x'},
+		{"show-username", required_argument, NULL, 'z'},
+		{"help", no_argument, NULL, '?'},
+		{"dbname",  required_argument, NULL, 'd'},
+		{"host", required_argument, NULL, 'h'},
+		{"port", required_argument, NULL, 'p'},
+		{"username", required_argument, NULL, 'U'},
+		{"password",  no_argument, NULL, 'W'},
+		{NULL, 0, NULL, 0}
+	};
+
 	struct system_info system_info;
 	struct statics statics;
 	caddr_t		processes;
@@ -259,6 +327,7 @@ main(int argc, char *argv[])
 #ifdef BSD_SIGNALS
 	int			old_sigmask;	/* only used for BSD-style signals */
 #endif   /* BSD_SIGNALS */
+	int			option_index;
 	int			topn = 0;
 	int			delay = Default_DELAY;
 	int			displays = 0;	/* indicates unspecified */
@@ -354,6 +423,21 @@ main(int argc, char *argv[])
 #define CMD_explain_analyze 27
 #define CMD_toggle 28
 
+	/* Show help or version number if necessary */
+    if (argc > 1)
+	{
+		if (strcmp(argv[1], "--help") == 0 || strcmp(argv[1], "-?") == 0)
+		{
+			usage(progname);
+			exit(0);
+		}
+		if (strcmp(argv[1], "--version") == 0 || strcmp(argv[1], "-V") == 0)
+		{
+			printf("pg_top %s\n", version_string());
+			exit(0);
+		}
+	}
+
 	/* set the buffer for stdout */
 	setbuffer(stdout, stdoutbuf, Buffersize);
 
@@ -419,7 +503,9 @@ main(int argc, char *argv[])
 			optind = 1;
 		}
 
-		while ((i = getopt(ac, av, "CDITbcinqruvh:s:d:U:o:Wp:x:z:")) != EOF)
+		while ((i = getopt_long(ac, av,
+								"CDITbcinqruVh:s:d:U:o:Wp:x:z:",
+								long_options, &option_index)) != EOF)
 		{
 			switch (i)
 			{
@@ -433,10 +519,9 @@ main(int argc, char *argv[])
 					debug_set(1);
 					break;
 
-				case 'v':		/* show version number */
-					fprintf(stderr, "%s: version %s\n",
-							myname, version_string());
-					exit(1);
+				case 'V':		/* show version number */
+					printf("pg_top %s\n", version_string());
+					exit(0);
 					break;
 
 				case 'u':		/* toggle uid/username display */
@@ -551,11 +636,7 @@ main(int argc, char *argv[])
 					break;
 
 				default:
-					fprintf(stderr, "\
-pg_top version %s\n\
-Usage: %s [-ITWbcinqru] [-x x] [-s x] [-o field] [-z username]\n\
-          [-p PORT] [-U USER] [-d DBNAME] [-h HOSTNAME] [number]\n",
-							version_string(), myname);
+					fprintf(stderr, "Try \"%s --help\" for more information.\n", progname);
 					exit(1);
 			}
 		}
@@ -1507,7 +1588,7 @@ Usage: %s [-ITWbcinqru] [-x x] [-s x] [-o field] [-z username]\n\
 										 */
 										reset_display();
 										break;
-								
+
 									case CMD_explain_analyze:
 										new_message(MT_standout,
 												 "Re-run SQL for analysis: ");