Update and polish postmaster and postgres help output and man pages.

3 files changed, 492 insertions, 568 deletions

diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index 4f795665390..be0fa978de4 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,217 +1,159 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.14 2000/10/05 19:48:18 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.15 2000/11/14 18:11:31 petere Exp $
 Postgres documentation
 -->
 
 <refentry id="APP-POSTGRES">
+ <docinfo>
+  <date>2000-11-12</date>
+ </docinfo>
+
  <refmeta>
-  <refentrytitle id="APP-POSTGRES-TITLE">
-   <application>postgres</application>
-  </refentrytitle>
+  <refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
+  <manvolnum>1</manvolnum>
   <refmiscinfo>Application</refmiscinfo>
  </refmeta>
+
  <refnamediv>
-  <refname>
-   <application>postgres</application>
-  </refname>
-  <refpurpose>
-   Run a <productname>Postgres</productname> single-user backend
-  </refpurpose>
+  <refname>postgres</refname>
+  <refpurpose>Run a <productname>PostgreSQL</productname> single-user backend</refpurpose>
  </refnamediv>
+
  <refsynopsisdiv>
-  <refsynopsisdivinfo>
-   <date>1999-07-20</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 ] [ -P ] [ -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>
+  <cmdsynopsis>
+   <!-- standalone call -->
+   <command>postgres</command>
+   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
+   <arg>-B <replaceable>nbuffers</replaceable></arg>
+   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
+   <arg>-d <replaceable>debug-level</replaceable></arg>
+   <arg>-D <replaceable>datadir</replaceable></arg>
+   <arg>-e</arg>
+   <arg>-E</arg>
+   <arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
+   <arg>-F</arg>
+   <arg>-i</arg>
+   <arg>-L</arg>
+   <arg>-N</arg>
+   <arg>-o <replaceable>file-name</replaceable></arg>
+   <arg>-O</arg>
+   <arg>-P</arg>
+   <group>
+    <arg>-s</arg>
+    <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
+   </group>
+   <arg>-S <replaceable>sort-mem</replaceable></arg>
+   <arg>-W <replaceable>seconds</replaceable></arg>
+   <arg choice="plain"><replaceable>database</replaceable></arg>
+   <sbr>
+   <!-- postmaster fork -->
+   <command>postgres</command>
+   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
+   <arg>-B <replaceable>nbuffers</replaceable></arg>
+   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
+   <arg>-d <replaceable>debug-level</replaceable></arg>
+   <arg>-D <replaceable>datadir</replaceable></arg>
+   <arg>-e</arg>
+   <arg>-f<group choice="plain"><arg>s</arg><arg>i</arg><arg>t</arg><arg>n</arg><arg>m</arg><arg>h</arg></group></arg>
+   <arg>-F</arg>
+   <arg>-i</arg>
+   <arg>-L</arg>
+   <arg>-o <replaceable>file-name</replaceable></arg>
+   <arg>-O</arg>
+   <arg>-p <replaceable>database</replaceable></arg>
+   <arg>-P</arg>
+   <group>
+    <arg>-s</arg>
+    <arg>-t<group choice="plain"><arg>pa</arg><arg>pl</arg><arg>ex</arg></group></arg>
+   </group>
+   <arg>-S <replaceable>sort-mem</replaceable></arg>
+   <arg>-v <replaceable>protocol-version</replaceable></arg>
+   <arg>-W <replaceable>seconds</replaceable></arg>
+  </cmdsynopsis>
+ </refsynopsisdiv>
 
-     <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 stand-alone, 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>
+ <refsect1>
+  <title>Description</title>
 
-     <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>
+  <para>
+   The <filename>postgres</filename> executable is the actual
+   <productname>PostgreSQL</productname> server process that processes
+   queries.  The second form above is how
+   <application>postgres</application> is invoked by the <xref
+   linkend="app-postmaster" endterm="app-postmaster-title"> (only
+   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"
+   endterm="app-initdb-title">.
+  </para>
 
-     <varlistentry>
-      <term>-E</term>
-      <listitem>
-       <para>
-	Echo all queries.
-       </para>
-      </listitem>
-     </varlistentry>
+  <para>
+   When invoked in interactive mode from the shell, the user can enter
+   queries and the results will be printed to the screen, but in a
+   form that is more useful for developers than end users.  But note
+   that running a single-user backend is not truly suitable for
+   debugging the server since no realistic inter-process communication
+   and locking will happen.
+  </para>
 
-     <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>
+  <para>
+   When running a stand-alone backend the session user name will
+   automatically be set to the current effective Unix user name.  If
+   that user does not exist the server will not start.
+  </para>
 
-     <varlistentry>
-      <term>-O</term>
-      <listitem>
-       <para>
-	Override restrictions, so system table structures can be modified.
-	These tables are typically those with a leading
-	<literal>pg_</literal> in the table name.
-       </para>
-      </listitem>
-     </varlistentry>
+  <refsect2>
+   <title>Options</title>
 
-     <varlistentry>
-      <term>-P</term>
-      <listitem>
-       <para>
-	Ignore system indexes to scan/update system
-	tuples. The <command>REINDEX</command> for system tables/indexes
-	requires this option. System tables are
-	typically those with a leading <literal>pg_</literal> in the
-	table name.
-       </para>
-      </listitem>
-     </varlistentry>
+   <para>
+    When <application>postgres</application> is started by a <xref
+    linkend="app-postmaster" endterm="app-postmaster-title"> then it
+    inherits all options set by the latter.  Additionally,
+    <application>postgres</application>-specific options can be passed
+    from the <application>postmaster</application> with the
+    <option>-o</option> switch.
+   </para>
 
-     <varlistentry>
-      <term>-Q</term>
-      <listitem>
-       <para>
-	Specifies "quiet" mode.
-       </para>
-      </listitem>
-     </varlistentry>
+   <para>
+    You can avoid having to type these options by setting up a
+    configuration file.  See the <citetitle>Administrator's
+    Guide</citetitle> for details.  Some (safe) options can also be
+    set from the connecting client in an application-dependent way.
+    For example, if the environment variable <envar>PGOPTIONS</envar>
+    is set, then libpq-based clients will pass that string to the
+    server, which will interpret it as
+    <application>postgres</application> command-line options.
+   </para>
 
-     <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>
+   <refsect3>
+    <title>General Purpose</title>
 
-     <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>
+    <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" endterm="app-postmaster-title">.
+    </para>
 
+    <variablelist>
      <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 the <citetitle>PostgreSQL User's Guide</citetitle>
-	for more information.
+        Sets the default date style to <quote>European</quote>, which
+	means that the <quote>day before month</quote> (rather than
+	month before day) rule is used to interpret ambiguous date
+	input, and that the day is printed before the month in certain
+	date output formats.  See the <citetitle>PostgreSQL User's
+	Guide</citetitle> for more information.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-o <replaceable class="parameter">OutputFile</replaceable></term>
+      <term>-o <replaceable class="parameter">file-name</replaceable></term>
       <listitem>
        <para>
 	Sends all debugging and error output to 
@@ -227,6 +169,17 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
      </varlistentry>
 
      <varlistentry>
+      <term>-P</term>
+      <listitem>
+       <para>
+	Ignore system indexes to scan/update system tuples. The
+	<command>REINDEX</command> command for system tables/indexes
+	requires this option to be used.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term>-s</term>
       <listitem>
        <para>
@@ -238,43 +191,42 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
      </varlistentry>
 
      <varlistentry>
-      <term>-v <replaceable class="parameter">protocol</replaceable></term>
+      <term>-S <replaceable class="parameter">sort-mem</replaceable></term>
       <listitem>
        <para>
-	Specifies the number of the frontend/backend protocol to be used for this
-	particular session.
+	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">sort-mem</replaceable> kilobytes
+	before it starts to put data into temporary files.
        </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>
+    </variablelist>
+   </refsect3>
 
-   <para>
-    These special-case options are:
+   <refsect3>
+    <title>Options for stand-alone mode</title>
 
     <variablelist>
      <varlistentry>
-      <term>-A [ n | r | b | Q | X ]</term>
+      <term><replaceable class="parameter">database</replaceable></term>
       <listitem>
        <para>
-	This option generates a tremendous amount of output.
+	Specifies the name of the database to be accessed.  If it is
+	omitted it defaults to the user name.	
        </para>
-     </listitem>
-    </varlistentry>
+      </listitem>
+     </varlistentry>
 
      <varlistentry>
-      <term>-L</term>
+      <term>-E</term>
       <listitem>
        <para>
-	Turns off the locking system.
+	Echo all queries.
        </para>
       </listitem>
      </varlistentry>
@@ -287,6 +239,21 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
        </para>
       </listitem>
      </varlistentry>
+    </variablelist>
+   </refsect3>
+
+   <refsect3>
+    <title>Semi-internal Options</title>
+
+    <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>PostgreSQL</productname> system
+     developers.  <emphasis>Use of any of these options is highly
+     discouraged.</emphasis>  Furthermore, any of these options may
+     disappear or change in a future release without notice.
+   </para>
+    <variablelist>
 
      <varlistentry>
       <term>-f [ s | i | m | n | h ]</term>
@@ -320,123 +287,83 @@ postgres [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -C ] [ -
      </varlistentry>
 
      <varlistentry>
-      <term>-p <replaceable class="parameter">dbname</replaceable></term>
+      <term>-L</term>
       <listitem>
        <para>
-	Indicates to the backend server that it has been started by a 
-	<application>postmaster</application>
-	and makes different assumptions about buffer pool management, file
-	descriptors, etc.  Switches following -p are restricted to those
-	considered "secure".
+	Turns off the locking system.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-t pa[rser] | pl[anner] | e[xecutor]</term>
+      <term>-O</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>.
+	Allows the structure of system tables to be modified.  This is
+	used by <application>initdb</application>.
        </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:
+     <varlistentry>
+      <term>-p <replaceable class="parameter">database</replaceable></term>
+      <listitem>
+       <para>
+	Indicates that this server has been started by a
+	<application>postmaster</application> and makes different
+	assumptions about buffer pool management, file descriptors,
+	etc.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <variablelist>
      <varlistentry>
-      <term><computeroutput>
-semget: No space left on device
-       </computeroutput></term>
+      <term>-t pa[rser] | pl[anner] | e[xecutor]</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.
+	Print timing statistics for each query relating to each of the
+	major system modules.  This option cannot be used together
+	with the <option>-s</option> option.
+       </para>
+      </listitem>
+     </varlistentry>
 
-	<tip>
-	 <para>
-	  You may be able to postpone
-	  reconfiguring your kernel by decreasing -B to reduce
-	  <productname>Postgres</productname>' shared memory
-	  consumption.
-	 </para>
-	</tip>
+     <varlistentry>
+      <term>-v <replaceable class="parameter">protocol</replaceable></term>
+      <listitem>
+       <para>
+	Specifies the version number of the frontend/backend protocol
+	to be used for this particular session.
        </para>
       </listitem>
      </varlistentry>
-    </variablelist>
-   </para>
-  </refsect2>
- </refsynopsisdiv>
 
- <refsect1 id="R1-APP-POSTGRES-1">
-  <refsect1info>
-   <date>1999-05-19</date>
-  </refsect1info>
-  <title>
-   Description
-  </title>
+     <varlistentry>
+      <term>-W <replaceable class="parameter">seconds</replaceable></term>
+      <listitem>
+       <para>
+	As soon as this option is encountered, the process sleeps for
+	the specified amount of seconds.  This gives developers time
+	to attach a debugger to the backend process.
+       </para>
+      </listitem>
+     </varlistentry>
 
-  <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>
+    </variablelist>
+   </refsect3>
+  </refsect2>
+ </refsect1>
 
-  <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>
+ <refsect1>
+  <title>See also</title>
 
   <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.
+   <xref linkend="app-initdb" endterm="app-initdb-title">,
+   <xref linkend="app-ipcclean" endterm="app-ipcclean-title">,
+   <xref linkend="app-postmaster" endterm="app-postmaster-title">
   </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="app-postmaster" endterm="app-postmaster-title">.
-  </para>
- </refsect1>
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 38f3f8e2107..0c9d1eb32c7 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,155 +1,174 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.14 2000/11/13 23:57:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.15 2000/11/14 18:11:31 petere Exp $
 Postgres documentation
 -->
 
 <refentry id="APP-POSTMASTER">
+ <docinfo>
+  <date>2000-11-12</date>
+ </docinfo>
+
  <refmeta>
-  <refentrytitle id="APP-POSTMASTER-TITLE">
-   <application>postmaster</application>
-  </refentrytitle>
+  <refentrytitle id="APP-POSTMASTER-TITLE"><application>postmaster</application></refentrytitle>
+  <manvolnum>1</manvolnum>
   <refmiscinfo>Application</refmiscinfo>
  </refmeta>
+
  <refnamediv>
-  <refname id="postmaster-ref">
-   <application>postmaster</application>
-  </refname>
-  <refpurpose>
-   Run the <productname>Postgres</productname> multi-user backend
-  </refpurpose>
+  <refname id="postmaster-ref">postmaster</refname>
+  <refpurpose><productname>PostgreSQL</productname> multi-user database server</refpurpose>
  </refnamediv>
+
  <refsynopsisdiv>
-  <refsynopsisdivinfo>
-   <date>1999-07-20</date>
-  </refsynopsisdivinfo>
-  <synopsis>
-postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -N <replaceable class="parameter">maxBackends</replaceable> ] [ -S ]
-    [ -d <replaceable class="parameter">DebugLevel</replaceable> ]
-    [ -h <replaceable class="parameter">hostname</replaceable> ] [ -i ]
-    [ -k <replaceable class="parameter">path</replaceable> ] [ -l ]
-    [ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] [ -n | -s ]
-  </synopsis>
-
-  <refsect2 id="R2-APP-POSTMASTER-1">
-   <refsect2info>
-    <date>1999-05-19</date>
-   </refsect2info>
-   <title>
-    Inputs
-   </title>
+  <cmdsynopsis>
+   <command>postmaster</command>
+   <arg>-A <group choice="plain"><arg>0</arg><arg>1</arg></group></arg>
+   <arg>-B <replaceable>nbuffers</replaceable></arg>
+   <arg>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></arg>
+   <arg>-d <replaceable>debug-level</replaceable></arg>
+   <arg>-D <replaceable>datadir</replaceable></arg>
+   <arg>-F</arg>
+   <arg>-h <replaceable>hostname</replaceable></arg>
+   <arg>-i</arg>
+   <arg>-k <replaceable>filename</replaceable></arg>
+   <arg>-l</arg>
+   <arg>-N <replaceable>max-connections</replaceable></arg>
+   <arg>-o <replaceable>extra-options</replaceable></arg>
+   <arg>-p <replaceable>port</replaceable></arg>
+   <arg>-S</arg>
+   <group><arg>-n</arg><arg>-s</arg></group>
+  </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <application>postmaster</application> is the
+   <productname>PostgreSQL</productname> multi-user database server.
+   In order for a client application to access a database it connects
+   (over a network or locally) to a running
+   <application>postmaster</application>.  The
+   <application>postmaster</application> then starts a separate server
+   process (<quote><xref linkend="app-postgres"
+   endterm="app-postgres-title"></quote>) to handle the connection.
+   The postmaster also manages the communication among server
+   processes.
+  </para>
+
+  <para>
+   By default the postmaster starts in the foreground and prints log
+   messages to the standard output.  In practical applications the
+   postmaster should be started as a background process, perhaps at
+   boot time.
+  </para>
+
+  <para>
+   One postmaster always manages the data from exactly one database
+   cluster.  A database cluster is a collection of databases that is
+   stored at a common file system location.  When the postmaster
+   starts it needs to know the location of the database cluster files
+   (<quote>data area</quote>).  This is done with the
+   <option>-D</option> invocation option or the <envar>PGDATA</envar>
+   environment variable, there is no default.  More than one
+   postmaster process can run on a system at one time, as long as they
+   use different data areas and different port numbers (see below).  A
+   data area is created with <xref linkend="app-initdb"
+   endterm="app-initdb-title">.
+  </para>
+
+  <refsect2 id="app-postmaster-options">
+   <title>Options</title>
    <para>
-    <application>postmaster</application> accepts the following command line arguments:
+    <application>postmaster</application> accepts the following
+    command line arguments.  For a detailed discussion of the options
+    consult the <citetitle>Administrator's Guide</citetitle>.  You can
+    also save typing most of these options by setting up a
+    configuration file.
     
     <variablelist>
      <varlistentry>
-      <term>-B <replaceable class="parameter">nBuffers</replaceable></term>
+      <term>-A 0|1</term>
       <listitem>
        <para>
-	Sets the number of shared-memory disk buffers for the 
-	<application>postmaster</application>
-	to allocate for use by the backend server processes that it
-	starts.  This value defaults to 64 buffers, where each buffer is 8k bytes
-	(or whatever BLCKSZ is set to in src/include/config.h).
+        Enables run-time assert checks, which is a debugging aid to
+        detect programming mistakes.  This is only available if it was
+        enabled during compilation.  If so, the default is on.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-D <replaceable class="parameter">DataDir</replaceable></term>
+      <term>-B <replaceable class="parameter">nbuffers</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.
+	Sets the number of shared buffers for use by the server
+	processes.  This value defaults to 64 buffers, where each
+	buffer is 8 kB.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-N <replaceable class="parameter">maxBackends</replaceable></term>
+      <term>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></term>
       <listitem>
        <para>
-	Sets the maximum number of backend server processes that this postmaster
-	is allowed to start.  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 -B is required to be at least twice -N, so you'll need to
-	increase -B if you increase -N.)
-	Both the default and upper limit values for -N can be altered
-	when building <productname>Postgres</productname>
-	(see src/include/config.h).
+        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>
+        On some systems it is also possible to equivalently use
+        GNU-style long options in the form
+        <literal>--name=value</literal>.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-S</term>
+      <term>-d <replaceable>debug-level</replaceable></term>
       <listitem>
        <para>
-	Specifies that the <application>postmaster</application>
-	process should start up in silent mode.  That is, it will disassociate
-	from the user's (controlling) tty, start its own process group, and
-	redirect its standard output and standard error to
-	<filename>/dev/null</filename>.
-       </para>
-       <para>
-	<emphasis>Note</emphasis> that using this switch makes it very
-	difficult to troubleshoot problems, since all tracing and logging
-	output that would normally be generated by this postmaster and its
-	child backends will be discarded.
+        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.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-d <replaceable class="parameter">DebugLevel</replaceable></term>
+      <term>-D <replaceable class="parameter">datadir</replaceable></term>
       <listitem>
        <para>
-	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.
-	Levels two and higher turn on increasing amounts of debug output
-	from the backend processes, and the postmaster
-	displays more information
-	including the backend environment and process traffic.
-	Note that unless the postmaster's standard output and standard error
-	are redirected into a log file, all this output will appear on the
-	controlling tty of the <application>postmaster</application>.
+	Specifies the file system location of the data directory.  See
+	discussion above.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-h <replaceable class="parameter">hostName</replaceable></term>
+      <term>-F</term>
       <listitem>
        <para>
-	Specifies the TCP/IP hostname or address
-	on which the <application>postmaster</application>
-	is to listen for connections from frontend applications.  Defaults to
-	the value of the <envar>PGHOST</envar> 
-	environment variable, or if <envar>PGHOST</envar>
-	is not set, it defaults to listening on all configured addresses
-	(including localhost).
-       </para>
-       <para>
-	If you use a hostname do not try to run
-	multiple instances of <application>postmaster</application> on the
-	same IP address but different ports.  Doing so will result in them
-	attempting (incorrectly) to use the same shared memory segments.
-	Also, if you use a hostname, all of the host's IP addresses
-	on which <application>postmaster</application> instances are
-	listening must be distinct in the two last octets.
+        Disables <function>fsync</function> calls for performance
+        improvement at the risk of data corruption.  Read the detailed
+        documentation before using this!
        </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>-h <replaceable class="parameter">hostname</replaceable></term>
+      <listitem>
        <para>
-	If you don't use this option, each instance must listen on a
-	different port (via -p or <envar>PGPORT</envar>).  And, of course, do
-	not try to use both approaches on one host.
+	Specifies the TCP/IP hostname or address on which the
+	<application>postmaster</application> is to listen for
+	connections from client applications.  Defaults to the value
+	of the <envar>PGHOST</envar> environment variable, or if
+	<envar>PGHOST</envar> is not set, it defaults to listening on
+	all configured addresses (including localhost).
        </para>
       </listitem>
      </varlistentry>
@@ -158,65 +177,63 @@ postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <re
       <term>-i</term>
       <listitem>
        <para>
-        Allows clients to connect via TCP/IP (Internet domain) connections.
-	Without this option, only local Unix domain socket connections are
-	accepted.
+        Allows clients to connect via TCP/IP (Internet domain)
+	connections.  Without this option, only local Unix domain
+	socket connections are accepted.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-k <replaceable class="parameter">path</replaceable></term>
+      <term>-k <replaceable class="parameter">filename</replaceable></term>
       <listitem>
        <para>
-	Specifies the local Unix domain socket path name
-	on which the <application>postmaster</application>
-	is to listen for connections from frontend applications.  Defaults to
-	the value of the 
-	<envar>PGUNIXSOCKET</envar> 
-	environment variable, or if <envar>PGUNIXSOCKET</envar>
-	is not set, then defaults to a file in <filename>/tmp</filename>
-	constructed from the port number.
+	Specifies the Unix domain socket file name on which the
+	<application>postmaster</application> is to listen for
+	connections from client applications.  Defaults to the value
+	of the <envar>PGUNIXSOCKET</envar> environment variable, or if
+	<envar>PGUNIXSOCKET</envar> is not set, then defaults to a
+	file in <filename>/tmp</filename> constructed from the port
+	number.
        </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>-l</term>
+      <listitem>
        <para>
-        You can use this option to put the Unix-domain socket in a
-        directory that is private to one or more users using Unix
-	directory permissions.  This is necessary for securely
-	creating databases automatically on shared machines.
-        In that situation, also disallow all TCP/IP connections
-	initially in <filename>pg_hba.conf</filename>.
-	If you specify a socket path other than the
-	default then all frontend applications (including
-	<application>psql</application>) must specify the same
-	socket path using either command-line options or
-	<envar>PGUNIXSOCKET</envar>.
+	Enables secure connections using SSL.  The <option>-i</option>
+	option is also required.  You must have compiled with SSL
+	enabled to use this option.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-l</term>
+      <term>-N <replaceable class="parameter">max-connections</replaceable></term>
       <listitem>
        <para>
-	Enables secure connections using SSL.  The <option>-i</option> option
-	is also required.
-	You must have compiled with SSL enabled to use this option.
+	Sets the maximum number of client connections that this
+	postmaster 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 <option>-B</option> is required to
+	be at least twice <option>-N</option>.)
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-o <replaceable class="parameter">BackendOptions</replaceable></term>
+      <term>-o <replaceable class="parameter">extra-options</replaceable></term>
       <listitem>
        <para>
-	The 
-	<literal>postgres</literal>
-	option(s) specified in
-	<replaceable class="parameter">BackendOptions</replaceable>
-	are passed to all backend server processes started by this
-	<application>postmaster</application>.
-	If the option string contains any spaces, the entire string must be
-	quoted.
+	The command line-style options specified in <replaceable
+	class="parameter">EXTRA-OPTIONS</replaceable> are passed to
+	all backend server processes started by this
+	<application>postmaster</application>.  See <xref
+	linkend="app-postgres" endterm="app-postgres-title"> for
+	possibilities.  If the option string contains any spaces, the
+	entire string must be quoted.
        </para>
       </listitem>
      </varlistentry>
@@ -225,38 +242,54 @@ postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <re
       <term>-p <replaceable class="parameter">port</replaceable></term>
       <listitem>
        <para>
-	Specifies the TCP/IP port or local Unix domain socket file extension
-	on which the <application>postmaster</application>
-	is to listen for connections from frontend applications.  Defaults to
-	the value of the 
-	<envar>PGPORT</envar> 
-	environment variable, or if <envar>PGPORT</envar>
-	is not set, then defaults to the value established when Postgres was
-	compiled (normally 5432).  If you specify a port other than the
-	default port, then all frontend applications (including
-	<application>psql</application>) must specify the same
-	port using either command-line options or
-	<envar>PGPORT</envar>.
+	Specifies the TCP/IP port or local Unix domain socket file
+	extension on which the <application>postmaster</application>
+	is to listen for connections from client applications.
+	Defaults to the value of the <envar>PGPORT</envar> environment
+	variable, or if <envar>PGPORT</envar> is not set, then
+	defaults to the value established during compilation (normally
+	5432).  If you specify a port other than the default port,
+	then all client applications must specify the same port using
+	either command-line options or <envar>PGPORT</envar>.
        </para>
       </listitem>
      </varlistentry>
+
+     <varlistentry>
+      <term>-S</term>
+      <listitem>
+       <para>
+	Specifies that the <application>postmaster</application>
+	process should start up in silent mode.  That is, it will
+	disassociate from the user's (controlling) terminal, start its
+	own process group, and redirect its standard output and
+	standard error to <filename>/dev/null</filename>.
+       </para>
+       <para>
+        Using this switch discards all logging output, which is
+	probably not what you want, since it makes it very difficult
+	to troubleshoot problems.  See below for a better way to start
+	the postmaster in the background.
+       </para>
+      </listitem>
+     </varlistentry>
+
     </variablelist>
    </para>
 
    <para>
-    Two additional command line options are available for debugging problems
-    that cause a backend to die abnormally.
-    These options control the behavior of the
-    <application>postmaster</application> in this situation, and
-    <emphasis>neither option is intended for use in
-     ordinary operation</emphasis>.
+    Two additional command line options are available for debugging
+    problems that cause a backend to die abnormally.  These options
+    control the behavior of the <application>postmaster</application>
+    in this situation, and <emphasis>neither option is intended for
+    use in ordinary operation</emphasis>.
    </para>
 
    <para>
     The ordinary strategy for this situation is to notify all other
     backends that they must terminate and then reinitialize the shared
-    memory and semaphores.  This is because an errant backend could have
-    corrupted some shared state before terminating.
+    memory and semaphores.  This is because an errant backend could
+    have corrupted some shared state before terminating.
    </para>
 
    <para>
@@ -292,31 +325,12 @@ postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <re
   </refsect2>
 
   <refsect2 id="R2-APP-POSTMASTER-2">
-   <refsect2info>
-    <date>1999-05-19</date>
-   </refsect2info>
    <title>
     Outputs
    </title>
    <para>
 
     <variablelist>
-     <!--
-     <varlistentry>
-      <term>
-       FindBackend: could not find a backend to execute...
-      </term>
-      <listitem>
-       <para>
-	If you see this message, you do not have the 
-	<application>postgres</application>
-     executable in your path.  Add the directory in which
-    <application>postgres</application> resides to
-	your path.
-       </para>
-      </listitem>
-     </varlistentry>
-     -->
      <varlistentry>
       <term><computeroutput>
 semget: No space left on device
@@ -416,124 +430,65 @@ IpcMemoryAttach: shmat() failed: Permission denied
     </variablelist>
    </para>
   </refsect2>
- </refsynopsisdiv>
-
- <refsect1 id="R1-APP-POSTMASTER-1">
-  <refsect1info>
-   <date>1999-05-19</date>
-  </refsect1info>
-  <title>
-   Description
-  </title>
-
-  <para>
-   <application>postmaster</application>
-   manages the communication between frontend and backend processes, as
-   well as allocating the shared buffer pool and SysV semaphores
-   (on machines without a test-and-set instruction).
-   <application>postmaster</application>
-   does not itself interact with the user and should be started as a
-   background process.
-  </para>
+ </refsect1>
 
+ <refsect1>
+  <title>Notes</title>
+  
   <para>
-   <emphasis>Only one postmaster should be running at a time in a given
-    <productname>Postgres</productname> installation.</emphasis>
-   Here, an installation means a database directory and
-   <application>postmaster</application> port number.
-   You can run more than one postmaster on a machine only if each one has a
-   separate directory and port number.
+   If at all possible, <emphasis>do not</emphasis> use
+   <literal>SIGKILL</literal> to kill the
+   <application>postmaster</application>.  This will prevent
+   <application>postmaster</application> from freeing the system
+   resources (e.g., shared memory and semaphores) that it holds before
+   terminating.
   </para>
- </refsect1>
 
- <refsect1 id="R1-APP-POSTMASTER-2">
-  <refsect1info>
-   <date>1998-10-04</date>
-  </refsect1info>
-  <title>
-   Notes
-  </title>
-  
   <para>
-   If at all possible,
-   <emphasis>do not</emphasis>
-   use <literal>SIGKILL</literal>
-   when killing the <application>postmaster</application>.
-   <literal>SIGHUP</literal>,
-   <literal>SIGINT</literal>,
-   or
-   <literal>SIGTERM</literal>
-   (the default signal for 
-   <application>kill</application>(1))"
-   should be used instead. Using
-
-   <programlisting>
-$ kill -KILL
-   </programlisting>
-
-or its alternative form
-
-   <programlisting>
-$ kill -9
-   </programlisting>
-
-   will prevent <application>postmaster</application>
-   from freeing the system resources (e.g., shared memory and semaphores)
-   that it holds before dying.  Use <literal>SIGTERM</literal> instead
-   to avoid having to clean up manually (as described earlier).
+   To terminate the postmaster normally, the signals
+   <literal>SIGTERM</literal>, <literal>SIGINT</literal>, 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
+   during restart.
   </para>
 
   <para>
-   Useful utilities for dealing with shared memory problems include
-   <application>ipcs(1)</application>,
-   <application>ipcrm(1</application>), and
-   <application>ipcclean(1)</application>.
+   The utility command <xref linkend="app-pg-ctl"> can be used to
+   start and shut down the postmaster safely and comfortably.
   </para>
  </refsect1>
- 
- <refsect1 id="R1-APP-POSTMASTER-3">
-  <refsect1info>
-   <date>1998-10-04</date>
-  </refsect1info>
-  <title>
-   Usage
-  </title>
-  <para>
-   To start <application>postmaster</application> using default
-   values, type:
 
-   <programlisting>
-$ nohup postmaster >logfile 2>&1 &
-   </programlisting>
+ <refsect1 id="app-postmaster-usage">
+  <title>Usage</title>
+  <para>
+   To start <application>postmaster</application> in the background
+   using default values, type:
 
-   This command will start up <application>postmaster</application>
-   on the default port (5432). This is the
-   simplest and most common way to start the
-   <application>postmaster</application>.
+<screen>
+<prompt>$</prompt> <userinput>nohup postmaster &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</userinput>
+</screen>
   </para>
 
   <para>
-   To start <application>postmaster</application> with a specific port:
-
-   <programlisting>
-$ nohup postmaster -p 1234 &
-   </programlisting>
-
+   To start <application>postmaster</application> with a specific
+   port:
+<screen>
+<prompt>$</prompt> <userinput>postmaster -p 1234</userinput>
+</screen>
    This command will start up <application>postmaster</application>
-   communicating through the port 1234. In order to
-   connect to this <application>postmaster</application>
-   using psql, you would need to run it as
-
-   <programlisting>
-$ psql -p 1234
-   </programlisting>
-
+   communicating through the port 1234. In order to connect to this
+   <application>postmaster</application> using psql, you would need to
+   run it as
+<screen>
+<prompt>$</prompt> <userinput>psql -p 1234</userinput>
+</screen>
    or set the environment variable <envar>PGPORT</envar>:
-
-   <programlisting>
-$ export PGPORT 1234
-$ psql
-   </programlisting>
+<screen>
+<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
+<prompt>$</prompt> <userinput>psql</userinput>
+</screen>
   </para>
  </refsect1>
 </refentry>
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 01093c57e02..f7eff6da821 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.34 2000/11/13 21:35:02 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.35 2000/11/14 18:11:30 petere Exp $
 -->
 
 <Chapter Id="runtime">
@@ -930,7 +930,34 @@ env PGOPTIONS='-c geqo=off' psql
      </varlistentry>
 
      <varlistentry>
-      <term>KRB_SERVER_KEYFILE</>
+      <term>HOSTNAME (<type>string</type>)</term>
+      <listitem>
+       <para>
+	Specifies the TCP/IP hostname or address on which the
+	<application>postmaster</application> is to listen for
+	connections from client applications.  Defaults to the value
+	of the <envar>PGHOST</envar> environment variable, or if
+	<envar>PGHOST</envar> is not set, it defaults to listening on
+	all configured addresses (including localhost).
+       </para>
+       <para>
+	If you use a hostname do not try to run multiple instances of
+	<application>postmaster</application> on the same IP address
+	but different ports.  Doing so will result in them attempting
+	(incorrectly) to use the same shared memory segments.  Also,
+	if you use a hostname, all of the host's IP addresses on which
+	<application>postmaster</application> instances are listening
+	must be distinct in the two last octets.
+       </para>
+       <para>
+	If you do not use this option, then each instance must listen
+	on a different port.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>KRB_SERVER_KEYFILE (<type>string</type>)</term>
       <listitem>
        <para>
         Sets the location of the Kerberos server key file. See
@@ -1057,6 +1084,21 @@ env PGOPTIONS='-c geqo=off' psql
      </varlistentry>
 
      <varlistentry>
+      <term>UNIXSOCKET (<type>string</type>)</term>
+      <listitem>
+       <para>
+	Specifies the Unix domain socket file name on which the
+	<application>postmaster</application> is to listen for
+	connections from client applications.  Defaults to the value
+	of the <envar>PGUNIXSOCKET</envar> environment variable, or if
+	<envar>PGUNIXSOCKET</envar> is not set, then defaults to a
+	file in <filename>/tmp</filename> constructed from the port
+	number.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term>UNIX_SOCKET_GROUP (<type>string</type>)</term>
       <listitem>
        <para>