diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index 9c4266d7d62a70dda132936a9f27f3f1a72a8620..00207b20f797c62a225235c481b76e992d6be0ed 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.20 2001/09/27 16:29:12 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.21 2001/11/25 01:11:36 tgl Exp $
Postgres documentation
-->
@@ -43,6 +43,7 @@ Postgres documentation
</group>
<arg>-S <replaceable>sort-mem</replaceable></arg>
<arg>-W <replaceable>seconds</replaceable></arg>
+ <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
<arg choice="plain"><replaceable>database</replaceable></arg>
<sbr>
<!-- postmaster fork -->
@@ -67,6 +68,7 @@ Postgres documentation
<arg>-S <replaceable>sort-mem</replaceable></arg>
<arg>-v <replaceable>protocol-version</replaceable></arg>
<arg>-W <replaceable>seconds</replaceable></arg>
+ <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
@@ -87,8 +89,9 @@ Postgres documentation
conceptually, since both <filename>postmaster</filename> and
<filename>postgres</filename> are in fact the same program); it
should not be invoked directly this way. The first form invokes
- the server directly in interactive mode. The primary use for this
- mode is for bootstrapping by <xref linkend="app-initdb">.
+ the server directly in interactive single-user mode. The primary use
+ for this mode is during bootstrapping by <xref linkend="app-initdb">.
+ Sometimes it is used for debugging or disaster recovery.
</para>
<para>
@@ -138,8 +141,8 @@ Postgres documentation
<para>
The options <option>-A</option>, <option>-B</option>,
<option>-c</option>, <option>-d</option>, <option>-D</option>,
- and <option>-F</option> have the same meaning as with the <xref
- linkend="app-postmaster">.
+ <option>-F</option>, and <option>--name</> have the same meanings as
+ for the <xref linkend="app-postmaster">.
</para>
<variablelist>
@@ -163,12 +166,10 @@ Postgres documentation
<para>
Sends all debugging and error output to
<replaceable class="parameter">filename</replaceable>.
- If the backend is running under the <application>postmaster</application>,
- error messages are still sent to the frontend process as well as to
- <replaceable class="parameter">filename</replaceable>,
- but debugging output is sent to the controlling tty of the
- <application>postmaster</application>
- (since only one file descriptor can be sent to an actual file).
+ If the backend is running under the
+ <application>postmaster</application>, this option is ignored,
+ and the stderr inherited from the
+ <application>postmaster</application> is used.
</para>
</listitem>
</varlistentry>
@@ -177,7 +178,7 @@ Postgres documentation
<term>-P</term>
<listitem>
<para>
- Ignore system indexes to scan/update system tuples. The
+ Ignore system indexes while scanning/updating system tuples. The
<command>REINDEX</command> command for system tables/indexes
requires this option to be used.
</para>
@@ -350,6 +351,46 @@ Postgres documentation
</refsect2>
</refsect1>
+ <refsect1>
+ <title>Usage</title>
+
+ <para>
+ Start a standalone backend with a command like
+<screen>
+<userinput>postgres -D $PGDATA <replaceable>other-options</> my_database</userinput>
+</screen>
+ Provide the correct path to the database area with <option>-D</>, or
+ make sure that the environment variable <envar>PGDATA</> is set.
+ Also specify the name of the particular database you want to work in.
+ </para>
+
+ <para>
+ Normally, the standalone backend treats newline as the command
+ entry terminator; there is no intelligence about semicolons,
+ as there is in <application>psql</>. To continue a command
+ across multiple lines, you must type backslash just before each
+ newline except the last one.
+ </para>
+
+ <para>
+ But if you use the <option>-N</> command line switch, then newline does
+ not terminate command entry. The backend will read stdin until EOF, then
+ process the input as a single query string. Backslash-newline is not
+ treated specially in this case.
+ </para>
+
+ <para>
+ The standalone backend does not have readline input processing
+ (no command history, for example).
+ </para>
+
+ <para>
+ To quit the backend, type EOF (control-D, usually). If you've
+ used <option>-N</>, two consecutive EOFs are needed to exit.
+ </para>
+
+ </refsect1>
+
<refsect1>
<title>See Also</title>
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 39fff15e532d1206c433b940fe95b6126d50d553..386434c2fadaab5ba72ab021e691461f42c2272a 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.22 2001/11/25 01:05:37 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.23 2001/11/25 01:11:36 tgl Exp $
Postgres documentation
-->
@@ -36,6 +36,7 @@ Postgres documentation
<arg>-o <replaceable>extra-options</replaceable></arg>
<arg>-p <replaceable>port</replaceable></arg>
<arg>-S</arg>
+ <arg>--<replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
<group><arg>-n</arg><arg>-s</arg></group>
</cmdsynopsis>
</refsynopsisdiv>
@@ -115,12 +116,8 @@ Postgres documentation
Sets a named run-time parameter. Consult the
<citetitle>Administrator's Guide</citetitle> for a list and
descriptions. Most of the other command line options are in
- fact short forms of such a parameter assignment.
- </para>
-
- <para>
- These options may also be specified using the GNU-style long option
- format, <option>--name=value</option>.
+ fact short forms of such a parameter assignment. <option>-c</>
+ can appear multiple times to set multiple parameters.
</para>
</listitem>
</varlistentry>
@@ -131,7 +128,8 @@ Postgres documentation
<para>
Sets the debug level. The higher this value is set, the more
debugging output is written to the server log. The default is
- 0, which means no debugging. Values up to 4 make sense.
+ 0, which means no debugging. Values up to 4 are useful; higher
+ numbers produce no additional output.
</para>
</listitem>
</varlistentry>
@@ -151,8 +149,8 @@ Postgres documentation
<listitem>
<para>
Disables <function>fsync</function> calls for performance
- improvement at the risk of data corruption. Read the detailed
- documentation before using this!
+ improvement, at the risk of data corruption in event of a
+ system crash. Read the detailed documentation before using this!
</para>
</listitem>
</varlistentry>
@@ -209,10 +207,12 @@ Postgres documentation
<para>
Sets the maximum number of client connections that this
<application>postmaster</application> will accept. By
- default, this value is 32, but it can be set as high as 1024
- if your system will support that many processes. (Note that
+ default, this value is 32, but it can be set as high as your
+ system will support. (Note that
<option>-B</option> is required to be at least twice
- <option>-N</option>.)
+ <option>-N</option>. See the <citetitle>Administrator's
+ Guide</citetitle> for a discussion of system resource requirements
+ for large numbers of client connections.)
</para>
</listitem>
</varlistentry>
@@ -267,6 +267,15 @@ Postgres documentation
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>--<replaceable>name</replaceable>=<replaceable>value</replaceable></term>
+ <listitem>
+ <para>
+ Sets a named run-time parameter; a shorter form of <option>-c</>.
+ </para>
+ </listitem>
+ </varlistentry>
+
</variablelist>
</para>
@@ -417,7 +426,7 @@ StreamServerPort: cannot bind to port
or <literal>SIGQUIT</literal> can be used. The first will wait for
all clients to terminate before quitting, the second will
forcefully disconnect all clients, and the third will quit
- immediately without lengthy shutdown, resulting in a recovery run
+ immediately without proper shutdown, resulting in a recovery run
during restart.
</para>
@@ -458,6 +467,26 @@ StreamServerPort: cannot bind to port
<prompt>$</prompt> <userinput>psql</userinput>
</screen>
</para>
+
+ <para>
+ Named runtime parameters can be set in either of these styles:
+<screen>
+<prompt>$</prompt> <userinput>postmaster -c sort_mem=1234</userinput>
+<prompt>$</prompt> <userinput>postmaster --sort-mem=1234</userinput>
+</screen>
+ Either form overrides whatever setting might exist for <literal>sort_mem</>
+ in <filename>postgresql.conf</>. Notice that underscores in parameter
+ names can be written as either underscore or dash on the command line.
+ </para>
+
+ <tip>
+ <para>
+ Except for short-term experiments,
+ it's probably better practice to edit the setting in
+ <filename>postgresql.conf</> than to rely on a command-line switch
+ to set a parameter.
+ </para>
+ </tip>
</refsect1>
</refentry>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index 5ed857f74247da29029490b015ede5afd01626c4..67ba9a60116a6443c57f5da8600f9c25b4082572 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.6 2001/11/25 00:18:48 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/reindex.sgml,v 1.7 2001/11/25 01:11:36 tgl Exp $
Postgres documentation
-->
@@ -183,8 +183,10 @@ REINDEX
<listitem>
<para>
Be aware that the standalone backend treats newline as the command
- entry terminator, not semicolon; you can't continue commands across
- lines, as you can in <application>psql</>.
+ entry terminator; there is no intelligence about semicolons,
+ as there is in <application>psql</>. To continue a command
+ across multiple lines, you must type backslash just before each
+ newline except the last one.
Also, you won't have any of the conveniences of readline processing
(no command history, for example).
</para>