David, Peter, > > The actual parameter is "config_file", so apparently we are supposed to > > either convert underscores to hyphens or we have a typo. > > We convert '-' to '_' when parsing long options (see ParseLongOption() > in guc.c). So writing the long options with hyphens should generally be > preferred in documentation.
Thanks for all your great input. Here is the updated patch. -- Best regards, Aleksander Alekseev
From 1d55400adba93381d8a08249c95e4e16fb9a5945 Mon Sep 17 00:00:00 2001 From: "David G. Johnston" <david.g.johnston@gmail.com> Date: Fri, 2 Feb 2024 14:16:24 -0700 Subject: [PATCH v3] Clarify error message about specifying --config-file When running without any arguments 'postgres' suggests to specify either --config-file or -D option. This is somewhat confusing since --config-file is a GUC and thus not directly described in the --help message. This patch reduces the amount of confusion. Besides affecting the error message the patch clarifies corresponding articles in the documentation. David Johnston, Aleksander Alekseev. Reviewed by Nathan Bossart and Peter Eisentraut. Reported by Alexey Palazhchenko. Discussion: https://postgr.es/m/CAJ7c6TMkuLiLfrA%2BEFCPYfhXoMKRxxssB5c86%2Bibxfaz6%2B%3DSdg%40mail.gmail.com --- doc/src/sgml/config.sgml | 11 ++++++----- doc/src/sgml/libpq.sgml | 7 ++++--- doc/src/sgml/ref/postgres-ref.sgml | 8 +++++--- src/backend/main/main.c | 4 ++-- src/backend/utils/misc/guc.c | 2 +- 5 files changed, 18 insertions(+), 14 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index e93208b2e6..3777cfa52a 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -334,9 +334,10 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter <para> During server startup, parameter settings can be passed to the <command>postgres</command> command via the - <option>-c</option> command-line parameter. For example, + <option>-c name=value</option> command-line parameter, or its equivalent + <option>--name=value</option> variation. For example, <programlisting> -postgres -c log_connections=yes -c log_destination='syslog' +postgres -c log_connections=yes --log-destination='syslog' </programlisting> Settings provided in this way override those set via <filename>postgresql.conf</filename> or <command>ALTER SYSTEM</command>, @@ -353,10 +354,10 @@ postgres -c log_connections=yes -c log_destination='syslog' of the session, but do not affect other sessions. For historical reasons, the format of <envar>PGOPTIONS</envar> is similar to that used when launching the <command>postgres</command> - command; specifically, the <option>-c</option> flag must be specified. - For example, + command; specifically, the <option>-c</option>, or prepended + <literal>--</literal>, before the name must be specified. For example, <programlisting> -env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql +env PGOPTIONS="-c geqo=off --statement-timeout=5min" psql </programlisting> </para> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 1d32c226d8..a445e4f280 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1421,9 +1421,10 @@ postgresql://%2Fvar%2Flib%2Fpostgresql/dbname <listitem> <para> Specifies command-line options to send to the server at connection - start. For example, setting this to <literal>-c geqo=off</literal> sets the - session's value of the <varname>geqo</varname> parameter to - <literal>off</literal>. Spaces within this string are considered to + start. For example, setting this to <literal>-c geqo=off</literal> + or <literal>--geoq=off</literal> sets the session's value of the + <varname>geqo</varname> parameter to <literal>off</literal>. + Spaces within this string are considered to separate command-line arguments, unless escaped with a backslash (<literal>\</literal>); write <literal>\\</literal> to represent a literal backslash. For a detailed discussion of the available diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml index b13a16a117..cbf06d86cb 100644 --- a/doc/src/sgml/ref/postgres-ref.sgml +++ b/doc/src/sgml/ref/postgres-ref.sgml @@ -123,7 +123,8 @@ PostgreSQL documentation described in <xref linkend="runtime-config"/>. Most of the other command line options are in fact short forms of such a parameter assignment. <option>-c</option> can appear multiple times - to set multiple parameters. + to set multiple parameters. See the <option>--name</option> + option below for an alternate syntax. </para> </listitem> </varlistentry> @@ -342,8 +343,9 @@ PostgreSQL documentation <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term> <listitem> <para> - Sets a named run-time parameter; a shorter form of - <option>-c</option>. + Sets the named run-time parameter; a shorter form of + <option>-c</option>. See <xref linkend="runtime-config"/> + for a listing of parameters. </para> </listitem> </varlistentry> diff --git a/src/backend/main/main.c b/src/backend/main/main.c index bfd0c5ed65..22ffcb1516 100644 --- a/src/backend/main/main.c +++ b/src/backend/main/main.c @@ -323,7 +323,7 @@ help(const char *progname) printf(_("Usage:\n %s [OPTION]...\n\n"), progname); printf(_("Options:\n")); printf(_(" -B NBUFFERS number of shared buffers\n")); - printf(_(" -c NAME=VALUE set run-time parameter\n")); + printf(_(" -c NAME=VALUE set run-time parameter (see also --NAME)\n")); printf(_(" -C NAME print value of run-time parameter, then exit\n")); printf(_(" -d 1-5 debugging level\n")); printf(_(" -D DATADIR database directory\n")); @@ -340,7 +340,7 @@ help(const char *progname) printf(_(" -s show statistics after each query\n")); printf(_(" -S WORK-MEM set amount of memory for sorts (in kB)\n")); printf(_(" -V, --version output version information, then exit\n")); - printf(_(" --NAME=VALUE set run-time parameter\n")); + printf(_(" --NAME=VALUE set run-time parameter, a shorter form of -c\n")); printf(_(" --describe-config describe configuration parameters, then exit\n")); printf(_(" -?, --help show this help, then exit\n")); diff --git a/src/backend/utils/misc/guc.c b/src/backend/utils/misc/guc.c index 3fb6803998..e5ae0784d2 100644 --- a/src/backend/utils/misc/guc.c +++ b/src/backend/utils/misc/guc.c @@ -1828,7 +1828,7 @@ SelectConfigFiles(const char *userDoption, const char *progname) else { write_stderr("%s does not know where to find the server configuration file.\n" - "You must specify the --config-file or -D invocation " + "You must specify the --config-file (or equivalent -c) or -D invocation " "option or set the PGDATA environment variable.\n", progname); return false; -- 2.45.0
