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

1 files changed, 219 insertions, 292 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