diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index ff3b3329524fa3cf68580c6bf474d3acfff416ad..b32ec49af5f3924ea235e4f1dba5513c55683643 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,220 +1,479 @@
-.\" This is -*-nroff-*-
-.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.1 1999/05/26 17:25:38 thomas Exp $
-.TH POSTGRESQL UNIX 05/19/99 PostgreSQL PostgreSQL
-.SH NAME
-postgres - the Postgres backend server
-.SH SYNOPSIS
-.BR "postgres"
-[\c
-.BR "-B"
-n_buffers]
-[\c
-.BR "-C"
-]
-[\c
-.BR "-D"
-data_directory]
-[\c
-.BR "-E"
-]
-[\c
-.BR "-F"
-]
-[\c
-.BR "-O"
-]
-[\c
-.BR "-Q"
-]
-[\c
-.BR "-S kbytes"
-]
-[\c
-.BR "-d"
-debug_level]
-[\c
-.BR "-e"
-]
-[\c
-.BR "-o"
-output_file]
-[\c
-.BR "-s"
-]
-[\c
-.BR "-v protocol"
-]
-[dbname]
-.in -5n
-.SH DESCRIPTION
-The Postgres backend server can be executed directly from the user shell.
-This should be done only while debugging by the DBA, and should not be
-done while other Postgres backends are being managed by a
-.IR postmaster
-on this set of databases.
-.PP
-Some of the switches explained in this man page can be passed to the backend
-through the "database options" field of a connection request, and thus can be
-set for a particular backend without going to the trouble of restarting the
-postmaster. This is particularly handy for debugging-related switches.
-.PP
-The optional argument
-.IR dbname
-specifies the name of the database to be accessed.
-.IR Dbname
-defaults to the value of the
-.SM USER
-environment variable.
-.PP
-The
-.IR postgres
-server understands the following command-line options:
-.TP
-.BR "-B" " n_buffers"
-If the backend is running under the
-.IR postmaster ,
-.IR "n_buffers"
-is the number of shared-memory buffers that the
-.IR "postmaster"
-has allocated for the backend server processes that it starts. If the
-backend is running standalone, this specifies the number of buffers to
-allocate. This value defaults to 64 buffers, where each buffer is 8k bytes
-(or whatever BLCKSZ is set to in config.h).
-.TP
-.BR "-C"
-Do not show server version number.
-.TP
-.BR "-D" " data_directory"
-This option specifies the pathname of the directory that contains the
-database system data (the tables, the catalogs, etc.). If you don't
-specify this option, Postgres uses the value of the PGDATA environment
-variable. You must either specify a -D option or set PGDATA.
-
-The data directory pathname for a database system is normally determined when
-the database system is created with
-.IR initdb ,
-with a --pgdata option to
-.IR initdb .
-.TP
-.BR "-E"
-Echo all queries.
-.TP
-.BR "-F"
-Disable automatic fsync() call after each transaction.
-This option improves performance, but an operating system crash
-while a transaction is in progress will probably cause data loss.
-.TP
-.BR "-O"
-Override restrictions, so system table structures can be modified(pg_*).
-.TP
-.BR "-Q"
-Specifies \*(lqquiet\*(rq mode.
-.TP
-.BR "-S" " kbytes"
-Specifies the amount of memory to be used by internal sorts and hashes
-before resorting to temporary disk files. The value is specified in
-kilobytes, and defaults to 512 kilobytes. Note that for a complex query,
-several sorts and/or hashes might be running in parallel, and each one
-will be allowed to use as much as -S kilobytes before it starts to put
-data into temporary files.
-.TP
-.BR "-e"
-The
-.IR "-e"
-option controls how dates are input to and output from the database.
-.IP
-If the
-.IR "-e"
-option is supplied, then all dates passed to and from the frontend
-processes will be assumed to be in
-.IR "European"
-format ie.
-.IR "DD-MM-YYYY"
-otherwise dates are input and output in
-.IR "American"
-format ie.
-.IR "MM-DD-YYYY"
-.TP
-.BR "-d" " debug_level"
-Turns on debugging at the numeric level
-.IR "debug_level" .
-Turning on debugging will cause query, parse trees, and query plans to
-be displayed.
-.TP
-.BR "-o" " output_file"
-Sends all debugging and error output to
-.IR output_file .
-If the backend is running under the
-.IR postmaster ,
-error messages are still sent to the frontend process as well as to
-.IR output_file ,
-but debugging output is sent to the controlling tty of the
-.IR postmaster
-(since only one file descriptor can be sent to an actual file).
-.TP
-.BR "-s"
-Print time information and other statistics at the end of each query.
-This is useful for benchmarking or for use in tuning the number of
-buffers.
-.TP
-.BR "-v" " protocol"
-Specifies the number of the frontend/backend protocol to be used for this
-particular session.
-.SH "DEVELOPER COMMAND OPTIONS"
-There are several other options that may be specified, used mainly
-for debugging purposes. These are listed here only for the use by
-Postgres system developers.
-.BR "Use of any of these options is highly discouraged" .
-Furthermore, any of these options may disappear or change at any time.
-.TP
-.BR "-A" "n|r|b|Q\fIn\fP|X\fIn\fP"
-.IP
-This option generates a tremendous amount of output.
-.TP
-.BR "-L"
-Turns off the locking system.
-.TP
-.BR "-N"
-Disables use of newline as a query delimiter.
-.TP
-.BR "-f"
-Forbids the use of particular scan and join methods:
-.IR s " and " i
-disable sequential and index scans respectively, while
-.IR n ", " m " and " h
-disable nested-loop, merge and hash joins respectively.
-(Neither sequential scans nor nested-loop joins can be disabled completely;
-the -fs and -fn options simply discourage the optimizer from using those
-plan types if it has any other alternative.)
-.TP
-.BR "-i"
-Prevents query execution, but shows the plan tree.
-.TP
-.BR "-p" " databasename"
-Indicates to the backend server that it has been started by a
-.IR postmaster
-and make different assumptions about buffer pool management, file
-descriptors, etc. Switches following -p are restricted to those
-considered "secure".
-.TP
-.BR "-t" "pa[rser]|pl[anner]|e[xecutor]"
-Print timing statistics for each query relating to each of the major
-system modules. This option cannot be used with
-.BR "-s" .
-.SH "SEE ALSO"
-ipcclean(1),
-psql(1),
-postmaster(1).
-.SH "DIAGNOSTICS"
-Of the nigh-infinite number of error messages you may see when you
-execute the backend server directly, the most common will probably be:
-.TP
-.BR "semget: No space left on device"
-If you see this message, you should run the
-.IR ipcclean
-command. After doing this, try starting
-.IR postgres
-again. If this still doesn't work, you probably need to configure
-your kernel for shared memory and semaphores as described in the
-installation notes.
+<refentry id="APP-POSTGRES">
+ <refmeta>
+ <refentrytitle>
+ <application>postgres</application>
+ </refentrytitle>
+ <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+ <refname id="postgres-ref">
+ <application>postgres</application>
+ </refname>
+ <refpurpose>
+ Run a <productname>Postgres</productname> single-user backend
+ </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+ <refsynopsisdivinfo>
+ <date>1999-05-19</date>
+ </refsynopsisdivinfo>
+ <synopsis>
+postgres [ <replaceable class="parameter">dbname</replaceable> ]
+postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -E ] [ -F ]
+ [ -O ] [ -Q ] [ -S <replaceable class="parameter">SortSize</replaceable> ] [ -d [ <replaceable class="parameter">DebugLevel</replaceable> ] ] [ -e ]
+ [ -o ] [ <replaceable class="parameter">OutputFile</replaceable> ] [ -s ] [ -v <replaceable class="parameter">protocol</replaceable> ] [ <replaceable class="parameter">dbname</replaceable> ]
+ </synopsis>
+
+ <refsect2 id="R2-APP-POSTGRES-1">
+ <refsect2info>
+ <date>1999-05-19</date>
+ </refsect2info>
+ <title>
+ Inputs
+ </title>
+ <para>
+ <application>postgres</application> accepts the following command line arguments:
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ <replaceable class="parameter">dbname</replaceable>
+ </term>
+ <listitem>
+ <para>
+ The optional argument
+ <replaceable class="parameter">dbname</replaceable>
+ specifies the name of the database to be accessed.
+ <replaceable class="parameter">dbname</replaceable>
+ defaults to the value of the
+ <envar>USER</envar>
+ environment variable.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -B <replaceable class="parameter">nBuffers</replaceable>
+ </term>
+ <listitem>
+ <para>
+ If the backend is running under the
+ <application>postmaster</application>,
+ <replaceable class="parameter">nBuffers</replaceable>
+ is the number of shared-memory buffers that the
+ <application>postmaster</application>
+ has allocated for the backend server processes that it starts. If the
+ backend is running standalone, this specifies the number of buffers to
+ allocate. This value defaults to 64 buffers, where each buffer is 8k bytes
+ (or whatever BLCKSZ is set to in config.h).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -C
+ </term>
+ <listitem>
+ <para>
+ Do not show the server version number.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -D <replaceable class="parameter">DataDir</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Specifies the directory to use as the root of the tree of database
+ directories. If -D is not given, the default data directory name is
+ the value of the environment variable
+ <envar>PGDATA</envar>.
+ If <envar>PGDATA</envar> is not set, then the directory used is
+ <filename>$POSTGRESHOME/data</filename>.
+ If neither environment variable is set and this command-line
+ option is not specified, the default directory that was
+ set at compile-time is used.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -E
+ </term>
+ <listitem>
+ <para>
+ Echo all queries.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -F
+ </term>
+ <listitem>
+ <para>
+ Disable an automatic <function>fsync()</function> call after each transaction.
+ This option improves performance, but an operating system crash
+ while a transaction is in progress may cause the loss of
+ the most recently entered data. Without the <function>fsync()</function> call
+ the data is buffered by the operating system, and written to disk sometime later.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -O
+ </term>
+ <listitem>
+ <para>
+ Override restrictions, so system table structures can be modified.
+ These tables are typically those with a leading "pg_" in the table name.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -Q
+ </term>
+ <listitem>
+ <para>
+ Specifies "quiet" mode.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -S <replaceable class="parameter">SortSize</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Specifies the amount of memory to be used by internal sorts and hashes
+ before resorting to temporary disk files. The value is specified in
+ kilobytes, and defaults to 512 kilobytes. Note that for a complex query,
+ several sorts and/or hashes might be running in parallel, and each one
+ will be allowed to use as much as
+ <replaceable class="parameter">SortSize</replaceable> kilobytes
+ before it starts to put data into temporary files.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -d [ <replaceable class="parameter">DebugLevel</replaceable> ]
+ </term>
+ <listitem>
+ <para>
+ The optional argument <replaceable class="parameter">DebugLevel</replaceable>
+ determines the amount of debugging output the backend servers will
+ produce.
+ If <replaceable class="parameter">DebugLevel</replaceable>
+ is one, the postmaster will trace all connection traffic,
+ and nothing else.
+ For levels two and higher,
+ debugging is turned on in the backend process and the postmaster
+ displays more information,
+ including the backend environment and process traffic.
+ Note that if no file is specified for backend servers to
+ send their debugging output then this output will appear on the
+ controlling tty of their parent <application>postmaster</application>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -e
+ </term>
+ <listitem>
+ <para>
+ This option controls how dates are interpreted upon
+ input to and output from the database.
+ If the <option>-e</option>
+ option is supplied, then dates passed to and from the frontend
+ processes will be assumed to be in "European"
+ format (<literal>DD-MM-YYYY</literal>),
+ otherwise dates are assumed to be in
+ "American" format (<literal>MM-DD-YYYY</literal>).
+ Dates are accepted by the backend in a wide variety of formats,
+ and for input dates this switch mostly affects the interpretation
+ for ambiguous cases. See <xref linkend="datatype" endterm="datatype">
+ for more information.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -o <replaceable class="parameter">OutputFile</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Sends all debugging and error output to
+ <replaceable class="parameter">OutputFile</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">OutputFile</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).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -s
+ </term>
+ <listitem>
+ <para>
+ Print time information and other statistics at the end of each query.
+ This is useful for benchmarking or for use in tuning the number of
+ buffers.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -v <replaceable class="parameter">protocol</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Specifies the number of the frontend/backend protocol to be used for this
+ particular session.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+
+ <para>
+ There are several other options that may be specified, used mainly
+ for debugging purposes. These are listed here only for the use by
+ <productname>Postgres</productname> system developers.
+ <emphasis>Use of any of these options is highly discouraged.</emphasis>
+ Furthermore, any of these options may disappear or change at any time.
+ </para>
+
+ <para>
+ These special-case options are:
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ -A n|r|b|Q\fIn\fP|X\fIn\fP
+ </term>
+ <listitem>
+ <para>
+ This option generates a tremendous amount of output.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -L
+ </term>
+ <listitem>
+ <para>
+ Turns off the locking system.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -N
+ </term>
+ <listitem>
+ <para>
+ Disables use of newline as a query delimiter.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -f [ s | i | m | n | h ]
+ </term>
+ <listitem>
+ <para>
+ Forbids the use of particular scan and join methods:
+ <literal>s</literal> and <literal>i</literal>
+ disable sequential and index scans respectively, while
+ <literal>n</literal>, <literal>m</literal>, and <literal>h</literal>
+ disable nested-loop, merge and hash joins respectively.
+
+ <note>
+ <para>
+ Neither sequential scans nor nested-loop joins can be disabled completely;
+ the <literal>-fs</literal> and <literal>-fn</literal>
+ options simply discourage the optimizer from using those
+ plan types if it has any other alternative.
+ </para>
+ </note>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -i
+ </term>
+ <listitem>
+ <para>
+ Prevents query execution, but shows the plan tree.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -p <replaceable class="parameter">dbname</replaceable>
+ </term>
+ <listitem>
+ <para>
+ Indicates to the backend server that it has been started by a
+ <application>postmaster</application>
+ and make different assumptions about buffer pool management, file
+ descriptors, etc. Switches following -p are restricted to those
+ considered "secure".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ -t pa[rser] | pl[anner] | e[xecutor]
+ </term>
+ <listitem>
+ <para>
+ Print timing statistics for each query relating to each of the major
+ system modules. This option cannot be used with <option>-s</option>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect2>
+
+ <refsect2 id="R2-APP-POSTGRES-2">
+ <refsect2info>
+ <date>1999-05-19</date>
+ </refsect2info>
+ <title>
+ Outputs
+ </title>
+ <para>
+ Of the nigh-infinite number of error messages you may see when you
+ execute the backend server directly, the most common will probably be:
+
+ <variablelist>
+ <varlistentry>
+ <term>
+ semget: No space left on device
+ </term>
+ <listitem>
+ <para>
+ If you see this message, you should run the
+ <application>ipcclean</application>
+ command. After doing this, try starting
+ <application>postmaster</application>
+ again. If this still doesn't work, you probably need to configure
+ your kernel for shared memory and semaphores as described in the
+ installation notes. If you have a kernel with particularly small shared memory
+ and/or semaphore limits, you may have to reconfigure your kernel to increase
+ its shared memory or semaphore parameters.
+
+ <tip>
+ <para>
+ You may be able to postpone
+ reconfiguring your kernel by decreasing -B to reduce
+ <productname>Postgres</productname>' shared memory
+ consumption.
+ </para>
+ </tip>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect2>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-APP-POSTGRES-1">
+ <refsect1info>
+ <date>1999-05-19</date>
+ </refsect1info>
+ <title>
+ Description
+ </title>
+
+ <para>
+ The Postgres backend server can be executed directly from the user shell.
+ This should be done only while debugging by the DBA, and should not be
+ done while other Postgres backends are being managed by a
+ <application>postmaster</application>
+ on this set of databases.
+ </para>
+
+ <para>
+ Some of the switches explained here can be passed to the backend
+ through the "database options" field of a connection request, and thus can be
+ set for a particular backend without going to the trouble of restarting the
+ postmaster. This is particularly handy for debugging-related switches.
+ </para>
+
+ <para>
+ The optional argument <replaceable class="parameter">dbname</replaceable>
+ specifies the name of the database to be accessed.
+ <replaceable class="parameter">dbname</replaceable>
+ defaults to the value of the
+ <envar>USER</envar> environment variable.
+ </para>
+ </refsect1>
+
+ <refsect1 id="R1-APP-POSTGRES-2">
+ <refsect1info>
+ <date>1998-10-04</date>
+ </refsect1info>
+ <title>
+ Notes
+ </title>
+
+ <para>
+ Useful utilities for dealing with shared memory problems include
+ <application>ipcs(1)</application>,
+ <application>ipcrm(1</application>), and
+ <application>ipcclean(1)</application>.
+ See also <xref linkend="postmaster-ref" endterm="postmaster-ref">.
+ </para>
+ </refsect1>
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"../reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/catalog"
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 16f318c814337a03dd8a3a081bafabd9b15aaf27..3d628f5311a4c386b470dcf91f675ed4de628bf1 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -6,7 +6,7 @@
<refmiscinfo>Application</refmiscinfo>
</refmeta>
<refnamediv>
- <refname id="postmaster">
+ <refname id="postmaster-ref">
<application>postmaster</application>
</refname>
<refpurpose>
@@ -18,10 +18,9 @@
<date>1999-05-19</date>
</refsynopsisdivinfo>
<synopsis>
-postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ]
- [ -D <replaceable class="parameter">DataDir</replaceable> ] [-N <replaceable class="parameter">nBackends</replaceable> ] [ -S ]
- [ -d [ <replaceable class="parameter">DebugLevel</replaceable> ] ]
- [ -i ] [ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -i ]
+postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -N <replaceable class="parameter">nBackends</replaceable> ] [ -S ]
+ [ -d [ <replaceable class="parameter">DebugLevel</replaceable> ] [ -i ] [ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
postmaster [ -n | -s ] ...
</synopsis>
@@ -206,10 +205,8 @@ postmaster [ -n | -s ] ...
</term>
<listitem>
<para>
- If the <literal>-n</literal>
- option is supplied, then the
<application>postmaster</application>
- does not reinitialize shared data structures. A knowledgable system
+ will not reinitialize shared data structures. A knowledgable system
programmer can then use the
<application>shmemdoc</application>
program to examine shared memory and semaphore state.
@@ -235,7 +232,7 @@ postmaster [ -n | -s ] ...
</para>
</refsect2>
- <refsect2 id="R2-APP-POSTMASTER-1">
+ <refsect2 id="R2-APP-POSTMASTER-2">
<refsect2info>
<date>1999-05-19</date>
</refsect2info>
@@ -388,8 +385,9 @@ on BSD-based systems, or
You can run more than one postmaster on a machine only if each one has a
separate directory and port number.
</para>
+ </refsect1>
- <refsect1 id="R1-APP-VACUUMDB-2">
+ <refsect1 id="R1-APP-POSTMASTER-2">
<refsect1info>
<date>1998-10-04</date>
</refsect1info>
@@ -434,7 +432,7 @@ or its alternative form
</para>
</refsect1>
- <refsect1 id="R1-APP-VACUUMDB-3">
+ <refsect1 id="R1-APP-POSTMASTER-3">
<refsect1info>
<date>1998-10-04</date>
</refsect1info>
@@ -478,7 +476,7 @@ or its alternative form
% setenv PGPORT 1234
% psql
</programlisting>.
-
+ </para>
</refsect1>
</refentry>