Add --help-config facility to dump information about GUC parameters

without needing a running backend.  Reorder postgresql.conf.sample
to match new layout of runtime.sgml.  This commit re-adds work lost
in Wednesday's crash.

src/backend/main/main.c

@@ -13,7 +13,7 @@
  *
  *
  * IDENTIFICATION
- *	  $Header: /cvsroot/pgsql/src/backend/main/main.c,v 1.57 2003/05/15 16:35:28 momjian Exp $
+ *	  $Header: /cvsroot/pgsql/src/backend/main/main.c,v 1.58 2003/07/04 16:41:21 tgl Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -37,6 +37,7 @@
 #include "miscadmin.h"
 #include "bootstrap/bootstrap.h"
 #include "tcop/tcopprot.h"
+#include "utils/help_config.h"
 #include "utils/ps_status.h"
 
 
@@ -198,7 +199,7 @@ main(int argc, char *argv[])
 	}
 
 	/*
-	 * Now dispatch to one of PostmasterMain, PostgresMain, or
+	 * Now dispatch to one of PostmasterMain, PostgresMain, GucInfoMain, or
 	 * BootstrapMain depending on the program name (and possibly first
 	 * argument) we were called with.  The lack of consistency here is
 	 * historical.
@@ -218,6 +219,14 @@ main(int argc, char *argv[])
 	if (argc > 1 && strcmp(new_argv[1], "-boot") == 0)
 		exit(BootstrapMain(argc - 1, new_argv + 1));
 
+	/*
+	 * If the first argument is "--help-config", then invoke runtime
+	 * configuration option display mode.
+	 * We remove "--help-config" from the arguments passed on to GucInfoMain.
+	 */
+	if (argc > 1 && strcmp(new_argv[1], "--help-config") == 0)
+		exit(GucInfoMain(argc - 1, new_argv + 1));
+
 	/*
 	 * Otherwise we're a standalone backend.  Invoke PostgresMain,
 	 * specifying current userid as the "authenticated" Postgres user

src/backend/tcop/postgres.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $Header: /cvsroot/pgsql/src/backend/tcop/postgres.c,v 1.348 2003/06/20 21:58:02 tgl Exp $
+ *	  $Header: /cvsroot/pgsql/src/backend/tcop/postgres.c,v 1.349 2003/07/04 16:41:21 tgl Exp $
  *
  * NOTES
  *	  this is the "main" module of the postgres backend and
@@ -1910,6 +1910,7 @@ usage(char *progname)
 	printf("  -P              disable system indexes\n");
 	printf("  -s              show statistics after each query\n");
 	printf("  -S SORT-MEM     set amount of memory for sorts (in kbytes)\n");
+	printf("  --help-config   show configuration options, then exit. Details: --help-config -h\n");
 	printf("  --help          show this help, then exit\n");
 	printf("  --version       output version information, then exit\n");
 	printf("\nDeveloper options:\n");
@@ -2547,7 +2548,7 @@ PostgresMain(int argc, char *argv[], const char *username)
 	if (!IsUnderPostmaster)
 	{
 		puts("\nPOSTGRES backend interactive interface ");
-		puts("$Revision: 1.348 $ $Date: 2003/06/20 21:58:02 $\n");
+		puts("$Revision: 1.349 $ $Date: 2003/07/04 16:41:21 $\n");
 	}
 
 	/*

src/backend/utils/misc/Makefile

-# $Header: /cvsroot/pgsql/src/backend/utils/misc/Makefile,v 1.20 2002/11/01 22:52:33 tgl Exp $
+# $Header: /cvsroot/pgsql/src/backend/utils/misc/Makefile,v 1.21 2003/07/04 16:41:21 tgl Exp $
 
 subdir = src/backend/utils/misc
 top_builddir = ../../../..
@@ -6,7 +6,7 @@ include $(top_builddir)/src/Makefile.global
 
 override CPPFLAGS := -I$(srcdir) $(CPPFLAGS)
 
-OBJS = database.o superuser.o guc.o ps_status.o
+OBJS = database.o superuser.o guc.o help_config.o ps_status.o
 
 # This location might depend on the installation directories. Therefore
 # we can't subsitute it into config.h.

src/backend/utils/misc/postgresql.conf.sample

@@ -27,70 +27,83 @@
 #
 #	Connection Parameters
 #
-#tcpip_socket = false
-#ssl = false
 
+# CONNECTIONS AND AUTHENTICATION
+# ----------------------------------
+# Connection Settings
+
+#tcpip_socket = false
 #max_connections = 32
+	# note: increasing max_connections costs about 500 bytes of shared
+	# memory per connection slot, in addition to costs from shared_buffers
+        # and max_locks_per_transaction.
 #superuser_reserved_connections = 2
-
-#port = 5432 
-
+#port = 5432
 #unix_socket_directory = ''
 #unix_socket_group = ''
 #unix_socket_permissions = 0777	# octal
-
 #virtual_host = ''
 
+# Security & Authentication
+
+#authentication_timeout = 60	# 1-600, in seconds
+#ssl = false
+#password_encryption = true
 #krb_server_keyfile = ''
+#db_user_namespace = false
 
 
-#
-#	Shared Memory Size
-#
+# RESOURCE USAGE (except WAL)
+# ---------------------------------
+# Memory
+
 #shared_buffers = 64		# min 16, at least max_connections*2, 8KB each
-#max_locks_per_transaction = 64	# min 10, ~260*max_connections bytes each
-#wal_buffers = 8		# min 4, 8KB each
-# fsm = free space map
-#max_fsm_relations = 1000	# min 100, ~50 bytes each
+#sort_mem = 1024		# min 64, size in KB
+#vacuum_mem = 8192		# min 1024, size in KB
+
+# Free Space Map
+
 #max_fsm_pages = 20000		# min max_fsm_relations*16, 6 bytes each
-# note: increasing max_connections also costs about 500 bytes each,
-# in addition to costs from shared_buffers and max_locks_per_transaction.
+#max_fsm_relations = 1000	# min 100, ~50 bytes each
 
+# Kernel Resource Usage
 
-#
-#	Non-shared Memory Sizes
-#
-#sort_mem = 1024		# min 64, size in KB
-#vacuum_mem = 8192		# min 1024, size in KB
+#max_files_per_process = 1000	# min 25
+#preload_libraries = ''
 
 
-#
-#	Write-ahead log (WAL)
-#
+# WRITE AHEAD LOG
+# ---------------------------------
+# Settings
+
+#fsync = true			# turns forced synchronization on or off
+#wal_sync_method = fsync	# the default varies across platforms:
+				# fsync, fdatasync, open_sync, or open_datasync
+#wal_buffers = 8		# min 4, 8KB each
+
+# Checkpoints
+
 #checkpoint_segments = 3	# in logfile segments, min 1, 16MB each
 #checkpoint_timeout = 300	# range 30-3600, in seconds
 #checkpoint_warning = 30	# 0 is off, in seconds
-#
 #commit_delay = 0		# range 0-100000, in microseconds
 #commit_siblings = 5		# range 1-1000
-#
-#fsync = true
-#wal_sync_method = fsync	# the default varies across platforms:
-#				# fsync, fdatasync, open_sync, or open_datasync
-#wal_debug = 0			# range 0-16
 
 
-#
-#	Optimizer Parameters
-#
-#enable_seqscan = true
-#enable_indexscan = true
-#enable_tidscan = true
-#enable_sort = true
+# QUERY TUNING
+# --------------------------------
+# Planner Method Enabling
+
 #enable_hashagg = true
-#enable_nestloop = true
-#enable_mergejoin = true
 #enable_hashjoin = true
+#enable_indexscan = true
+#enable_mergejoin = true
+#enable_nestloop = true
+#enable_seqscan = true
+#enable_sort = true
+#enable_tidscan = true
+
+# Planner Cost Constants
 
 #effective_cache_size = 1000	# typically 8KB each
 #random_page_cost = 4		# units are one sequential page fetch cost
@@ -98,117 +111,127 @@
 #cpu_index_tuple_cost = 0.001	# (same)
 #cpu_operator_cost = 0.0025	# (same)
 
-#from_collapse_limit = 8
-#join_collapse_limit = 8	# 1 disables collapsing of explicit JOINs
-
-#default_statistics_target = 10	# range 1-1000
+# Genetic Query Optimizer
 
-#
-#	GEQO Optimizer Parameters
-#
 #geqo = true
-#geqo_selection_bias = 2.0	# range 1.5-2.0
 #geqo_threshold = 11
-#geqo_pool_size = 0		# default based on tables in statement, 
-				# range 128-1024
 #geqo_effort = 1
 #geqo_generations = 0
-#geqo_random_seed = -1		# auto-compute seed
+#geqo_pool_size = 0		# default based on tables in statement,
+				# range 128-1024
+#geqo_random_seed = -1		# -1 = use variable seed
+#geqo_selection_bias = 2.0	# range 1.5-2.0
 
+# Other Planner Options
+
+#default_statistics_target = 10	# range 1-1000
+#from_collapse_limit = 8
+#join_collapse_limit = 8	# 1 disables collapsing of explicit JOINs
+
+
+# ERROR REPORTING AND LOGGING
+# ------------------------------------
+# Syslog
+
+#syslog = 0			# range 0-2
+#syslog_facility = 'LOCAL0'
+#syslog_ident = 'postgres'
+
+# When to Log
 
-#
-#	Message display
-#
 #client_min_messages = notice	# Values, in order of decreasing detail:
 				#   debug5, debug4, debug3, debug2, debug1,
 				#   log, info, notice, warning, error
+
 #log_min_messages = notice	# Values, in order of decreasing detail:
 				#   debug5, debug4, debug3, debug2, debug1,
 				#   info, notice, warning, error, log, fatal,
 				#   panic
 
-#log_error_verbosity = default	# terse, default, or verbose messages
-
-#silent_mode = false
-
-#log_connections = false
-#log_hostname = false
-#log_source_port = false
-#log_pid = false
-#log_statement = false
-#log_duration = false
-#log_timestamp = false
+#log_error_verbosity = default   # terse, default, or verbose messages
 
 #log_min_error_statement = panic # Values in order of increasing severity:
 				 #   debug5, debug4, debug3, debug2, debug1,
 				 #   info, notice, warning, error, panic(off)
-
+				 
 #log_min_duration_statement = 0  # Log all statements whose
 				 # execution time exceeds the value, in
 				 # milliseconds.  Zero disables.
 
+#silent_mode = false		 # DO NOT USE without Syslog!
+
+# What to Log
+
 #debug_print_parse = false
 #debug_print_rewritten = false
 #debug_print_plan = false
 #debug_pretty_print = false
+#log_connections = false
+#log_duration = false
+#log_pid = false
+#log_statement = false
+#log_timestamp = false
+#log_hostname = false
+#log_source_port = false
 
-#explain_pretty_print = true
-
-# requires USE_ASSERT_CHECKING
-#debug_assertions = true
-
-
-#
-#	Syslog
-#
-#syslog = 0			# range 0-2
-#syslog_facility = 'LOCAL0'
-#syslog_ident = 'postgres'
-
+# RUNTIME STATISTICS
+# -------------------------------------
+# Statistics Monitoring
 
-#
-#	Statistics
-#
 #log_parser_stats = false
 #log_planner_stats = false
 #log_executor_stats = false
 #log_statement_stats = false
 
-# requires BTREE_BUILD_STATS
-#log_btree_build_stats = false
-
+# Query/Index Statistics Collector
 
-#
-#	Access statistics collection
-#
 #stats_start_collector = true
-#stats_reset_on_server_start = true
 #stats_command_string = false
-#stats_row_level = false
 #stats_block_level = false
+#stats_row_level = false
+#stats_reset_on_server_start = true
 
 
-#
-#	Misc
-#
-#dynamic_library_path = '$libdir'
+# CLIENT CONNECTION DEFAULTS
+# -------------------------------------
+# Statement Behavior
+
 #search_path = '$user,public'	# schema names
+#default_transaction_isolation = 'read committed'
+#default_transaction_read_only = false
+#statement_timeout = 0		# 0 is disabled, in milliseconds
+
+# Locale and Formatting
+
 #datestyle = 'iso, us'
 #timezone = unknown		# actually, defaults to TZ environment setting
 #australian_timezones = false
-#client_encoding = sql_ascii	# actually, defaults to database encoding
-#authentication_timeout = 60	# 1-600, in seconds
-#deadlock_timeout = 1000	# in milliseconds
-#default_transaction_isolation = 'read committed'
-#default_transaction_read_only = false
 #extra_float_digits = 0		# min -15, max 2
+#client_encoding = sql_ascii	# actually, defaults to database encoding
+
+# These settings are initialized by initdb -- they may be changed
+
+# Other Defaults
+
+#explain_pretty_print = true
+#dynamic_library_path = '$libdir'
 #max_expr_depth = 10000		# min 10
-#max_files_per_process = 1000	# min 25
-#password_encryption = true
+
+# LOCK MANAGEMENT
+# -----------------------------------------
+
+#deadlock_timeout = 1000	# in milliseconds
+#max_locks_per_transaction = 64	# min 10, ~260*max_connections bytes each
+
+
+# VERSION/PLATFORM COMPATIBILITY
+# -----------------------------------------
+# Previous Postgres Versions
+
+#add_missing_from = true
 #regex_flavor = advanced	# advanced, extended, or basic
 #sql_inheritance = true
+
+# Other Platforms & Clients
+
 #transform_null_equals = false
-#statement_timeout = 0		# 0 is disabled, in milliseconds
-#db_user_namespace = false
-#preload_libraries = ''
-#add_missing_from = true

src/bin/initdb/initdb.sh

@@ -27,7 +27,7 @@
 # Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
 # Portions Copyright (c) 1994, Regents of the University of California
 #
-# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.192 2003/06/02 19:00:29 tgl Exp $
+# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.193 2003/07/04 16:41:21 tgl Exp $
 #
 #-------------------------------------------------------------------------
 
@@ -586,16 +586,12 @@ $ECHO_N "creating configuration files... "$ECHO_C
 cp "$PG_HBA_SAMPLE" "$PGDATA"/pg_hba.conf              || exit_nicely
 cp "$PG_IDENT_SAMPLE" "$PGDATA"/pg_ident.conf          || exit_nicely
 (
-  cat "$POSTGRESQL_CONF_SAMPLE"
-  echo
-  echo
-  echo "#"
-  echo "#	Locale settings"
-  echo "#"
-  echo "# (initialized by initdb -- may be changed)"
+  trigger="# These settings are initialized by initdb -- they may be changed"
+  sed -n "1,/$trigger/p" "$POSTGRESQL_CONF_SAMPLE"
   for cat in MESSAGES MONETARY NUMERIC TIME; do
     echo "LC_$cat = '`pg_getlocale $cat`'"
   done
+  sed -n "1,/$trigger/!p" "$POSTGRESQL_CONF_SAMPLE"
 ) > "$PGDATA"/postgresql.conf || exit_nicely
 
 chmod 0600 "$PGDATA"/pg_hba.conf "$PGDATA"/pg_ident.conf \

src/include/utils/guc_tables.h

+/*-------------------------------------------------------------------------
+ *
+ * guc_tables.h
+ *		Declarations of tables used by GUC.
+ *
+ * See src/backend/utils/misc/README for design notes.
+ *
+ * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
+ *
+ *	  $Id: guc_tables.h,v 1.1 2003/07/04 16:41:22 tgl Exp $
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef GUC_TABLES
+#define GUC_TABLES 1
+
+/*
+ * Groupings to help organize all the run-time options for display.
+ *
+ * Keep this in sync with config_group_names[] in guc.c.
+ */
+enum config_group
+{
+	UNGROUPED,
+	CONN_AUTH,
+	CONN_AUTH_SETTINGS,
+	CONN_AUTH_SECURITY,
+	RESOURCES,
+	RESOURCES_MEM,
+	RESOURCES_FSM,
+	RESOURCES_KERNEL,
+	WAL,
+	WAL_SETTINGS,
+	WAL_CHECKPOINTS,
+	QUERY_TUNING,
+	QUERY_TUNING_METHOD,
+	QUERY_TUNING_COST,
+	QUERY_TUNING_GEQO,
+	QUERY_TUNING_OTHER,
+	LOGGING,
+	LOGGING_SYSLOG,
+	LOGGING_WHEN,
+	LOGGING_WHAT,
+	STATS,
+	STATS_MONITORING,
+	STATS_COLLECTOR,
+	CLIENT_CONN,
+	CLIENT_CONN_STATEMENT,
+	CLIENT_CONN_LOCALE,
+	CLIENT_CONN_OTHER,
+	LOCK_MANAGEMENT,
+	COMPAT_OPTIONS,
+	COMPAT_OPTIONS_PREVIOUS,
+	COMPAT_OPTIONS_CLIENT,
+	DEVELOPER_OPTIONS
+};
+
+
+/*
+ * GUC supports these types of variables:
+ */
+enum config_type
+{
+	PGC_BOOL,
+	PGC_INT,
+	PGC_REAL,
+	PGC_STRING
+};
+
+/*
+ * Generic fields applicable to all types of variables
+ *
+ * The short description should be less than 80 chars in length. Some
+ * applications may use the long description as well, and will append 
+ * it to the short description. (separated by a newline or '. ') 
+ */
+struct config_generic
+{
+	/* constant fields, must be set correctly in initial value: */
+	const char *name;			/* name of variable - MUST BE FIRST */
+	GucContext	context;		/* context required to set the variable */
+	enum config_group group;    /* to help organize variables by function */
+	const char *short_desc;     /* short desc. of this variable's purpose */
+	const char *long_desc;      /* long desc. of this variable's purpose */
+	int			flags;			/* flag bits, see below */
+	/* variable fields, initialized at runtime: */
+	enum config_type vartype;	/* type of variable (set only at startup) */
+	int			status;			/* status bits, see below */
+	GucSource	reset_source;	/* source of the reset_value */
+	GucSource	session_source; /* source of the session_value */
+	GucSource	tentative_source;		/* source of the tentative_value */
+	GucSource	source;			/* source of the current actual value */
+};
+
+/* bit values in flags field */
+#define GUC_LIST_INPUT			0x0001	/* input can be list format */
+#define GUC_LIST_QUOTE			0x0002	/* double-quote list elements */
+#define GUC_NO_SHOW_ALL			0x0004	/* exclude from SHOW ALL */
+#define GUC_NO_RESET_ALL		0x0008	/* exclude from RESET ALL */
+#define GUC_REPORT				0x0010	/* auto-report changes to client */
+#define GUC_NOT_IN_SAMPLE 		0x0020	/* not in postgresql.conf.sample */
+#define GUC_DISALLOW_IN_FILE	0x0040	/* can't set in postgresql.conf */ 
+
+/* bit values in status field */
+#define GUC_HAVE_TENTATIVE	0x0001		/* tentative value is defined */
+#define GUC_HAVE_LOCAL		0x0002		/* a SET LOCAL has been executed */
+
+
+/* GUC records for specific variable types */
+
+struct config_bool
+{
+	struct config_generic gen;
+	/* these fields must be set correctly in initial value: */
+	/* (all but reset_val are constants) */
+	bool	   *variable;
+	bool		reset_val;
+	bool		(*assign_hook) (bool newval, bool doit, bool interactive);
+	const char *(*show_hook) (void);
+	/* variable fields, initialized at runtime: */
+	bool		session_val;
+	bool		tentative_val;
+};
+
+struct config_int
+{
+	struct config_generic gen;
+	/* these fields must be set correctly in initial value: */
+	/* (all but reset_val are constants) */
+	int		   *variable;
+	int			reset_val;
+	int			min;
+	int			max;
+	bool		(*assign_hook) (int newval, bool doit, bool interactive);
+	const char *(*show_hook) (void);
+	/* variable fields, initialized at runtime: */
+	int			session_val;
+	int			tentative_val;
+};
+
+struct config_real
+{
+	struct config_generic gen;
+	/* these fields must be set correctly in initial value: */
+	/* (all but reset_val are constants) */
+	double	   *variable;
+	double		reset_val;
+	double		min;
+	double		max;
+	bool		(*assign_hook) (double newval, bool doit, bool interactive);
+	const char *(*show_hook) (void);
+	/* variable fields, initialized at runtime: */
+	double		session_val;
+	double		tentative_val;
+};
+
+struct config_string
+{
+	struct config_generic gen;
+	/* these fields must be set correctly in initial value: */
+	/* (all are constants) */
+	char	  **variable;
+	const char *boot_val;
+	const char *(*assign_hook) (const char *newval, bool doit, bool interactive);
+	const char *(*show_hook) (void);
+	/* variable fields, initialized at runtime: */
+	char	   *reset_val;
+	char	   *session_val;
+	char	   *tentative_val;
+};
+
+extern const char * const config_group_names[];
+extern struct config_generic **guc_variables;
+extern int	num_guc_variables;
+
+extern void build_guc_variables(void);
+
+#endif

src/include/utils/help_config.h

+/*-------------------------------------------------------------------------
+ *
+ * help_config.h
+ *		Interface to the --help-config option of main.c 
+ * 
+ * Portions Copyright (c) 1996-2002, PostgreSQL Global Development Group
+ *
+ *	  $Id: help_config.h,v 1.1 2003/07/04 16:41:22 tgl Exp $
+ *
+ *-------------------------------------------------------------------------
+ */
+#ifndef HELP_CONFIG_H
+#define HELP_CONFIG_H 1
+
+extern int	GucInfoMain(int argc, char *argv[]);
+
+#endif