Merge postmaster and postgres command into just postgres. postmaster

symlink is kept for now for compatibility.  To call single-user mode, use
postgres --single.

1 files changed, 644 insertions, 131 deletions

diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
index 1cf8521bebb..bbc3d29e5d6 100644
--- a/doc/src/sgml/ref/postgres-ref.sgml
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -1,29 +1,28 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.46 2006/01/05 10:07:44 petere Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.47 2006/06/18 15:38:36 petere Exp $
 PostgreSQL documentation
 -->
 
-<refentry id="APP-POSTGRES">
+<refentry id="app-postgres">
  <refmeta>
-  <refentrytitle id="APP-POSTGRES-TITLE"><application>postgres</application></refentrytitle>
+  <refentrytitle><application>postgres</application></refentrytitle>
   <manvolnum>1</manvolnum>
   <refmiscinfo>Application</refmiscinfo>
  </refmeta>
 
  <refnamediv>
   <refname>postgres</refname>
-  <refpurpose>run a <productname>PostgreSQL</productname> server in single-user mode</refpurpose>
+  <refpurpose><productname>PostgreSQL</productname> database server</refpurpose>
  </refnamediv>
 
  <indexterm zone="app-postgres">
-  <primary>postgres (the program)</primary>
+  <primary>postgres</primary>
  </indexterm>
 
  <refsynopsisdiv>
   <cmdsynopsis>
    <command>postgres</command>
    <arg rep="repeat"><replaceable>option</></arg>
-   <arg choice="plain"><replaceable>database</replaceable></arg>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -31,123 +30,337 @@ PostgreSQL documentation
   <title>Description</title>
 
   <para>
-   The <command>postgres</command> executable is the actual
-   <productname>PostgreSQL</productname> server process that processes
-   SQL statements.  It is normally not called directly; instead a
-   <xref linkend="app-postmaster"> multiuser server is started.
-   Conceptually, the <command>postmaster</command> starts a new
-   <command>postgres</command> process for each connection.
-   (<filename>postmaster</filename> and <filename>postgres</filename>
-   are in fact the same program, and on most platforms the connection
-   process is forked).
+   <command>postgres</command> is the
+   <productname>PostgreSQL</productname> database server.  In order
+   for a client application to access a database it connects (over a
+   network or locally) to a running <command>postgres</command> process.
+   The <command>postgres</command> instance then starts a separate server
+   process to handle the connection.
   </para>
 
   <para>
-   If the <command>postgres</command> command is called directly, it
-   invokes the server in interactive single-user mode.  The primary
-   use for this mode is during bootstrapping by <xref
-   linkend="app-initdb">.  Sometimes it is used for debugging or
-   disaster recovery.
-   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 server is not truly suitable for
-   debugging the server since no realistic interprocess communication
-   and locking will happen.
+   One <command>postgres</command> instance 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 (the
+   <quote>data area</quote>).  More than one
+   <command>postgres</command> process can run on a system at one
+   time, so long as they use different data areas and different
+   communication ports (see below).  When
+   <command>postgres</command> starts it needs to know the location
+   of the data area.  The location must be specified by the
+   <option>-D</option> option or the <envar>PGDATA</envar> environment
+   variable; there is no default.  Typically, <option>-D</option> or
+   <envar>PGDATA</envar> points directly to the data area directory
+   created by <application>initdb</>.  Other possible file layouts are
+   discussed in <xref linkend="runtime-config-file-locations">.  A
+   data area is created with <xref linkend="app-initdb">.
   </para>
 
   <para>
-   When running a stand-alone server, the session user will be set to
-   the user with ID 1.  This user does not actually have to exist, so
-   a stand-alone server can be used to manually recover from certain
+   By default <command>postgres</command> starts in the
+   foreground and prints log messages to the standard error stream.  In
+   practical applications the <command>postgres</command>
+   should be started as a background process, perhaps at boot time.
+  </para>
+
+  <para>
+   The <command>postgres</command> command can also be called in
+   single-user mode.  The primary use for this mode is during
+   bootstrapping by <xref linkend="app-initdb">.  Sometimes it is used
+   for debugging or disaster recovery.  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
+   server is not truly suitable for debugging the server since no
+   realistic interprocess communication and locking will happen.  When
+   running a stand-alone server, the session user will be set to the
+   user with ID 1.  This user does not actually have to exist, so a
+   stand-alone server can be used to manually recover from certain
    kinds of accidental damage to the system catalogs.  Implicit
-   superuser powers are granted to the user with ID 1 in stand-alone
+   superuser powers are granted to the user with ID 1 in single-user
    mode.
   </para>
  </refsect1>
 
- <refsect1>
+ <refsect1 id="app-postgres-options">
   <title>Options</title>
 
    <para>
-    When <command>postgres</command> is started by a <xref
-    linkend="app-postmaster"> then it inherits all options set by the
-    latter.  In single-user mode, <command>postgres</command> accepts
-    all the options that <command>postmaster</command> would accept.
-   </para>
-
-   <para>
-    You can avoid having to type these options by setting up a
-    configuration file.  See <xref linkend="runtime-config"> 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
-    <application>libpq</>-based clients will pass that string to the
-    server, which will interpret it as
+    <command>postgres</command> accepts the following command-line
+    arguments.  For a detailed discussion of the options consult <xref
+    linkend="runtime-config">.  You can save typing most of these
+    options by setting up a configuration file.  Some (safe) options
+    can also be set from the connecting client in an
+    application-dependent way to apply only for that session.  For
+    example, if the environment variable <envar>PGOPTIONS</envar> is
+    set, then <application>libpq</>-based clients will pass that
+    string to the server, which will interpret it as
     <command>postgres</command> command-line options.
    </para>
 
    <refsect2>
     <title>General Purpose</title>
+    
+    <variablelist>
+     <varlistentry>
+      <term><option>-A 0|1</option></term>
+      <listitem>
+       <para>
+        Enables run-time assertion checks, which is a debugging aid to
+        detect programming mistakes.  This option is only available if
+        assertions were enabled when <productname>PostgreSQL</> was
+        compiled. If so, the default is on.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <para>
-     The options <option>-A</option>, <option>-B</option>,
-     <option>-c</option>, <option>-d</option>, <option>-D</option>,
-     <option>-e</option>, <option>-F</option>, <option>-s</option>,
-     <option>-S</option>, and <option>--<replaceable>name</></option>
-     have the same meanings as with the <xref linkend="app-postmaster">
-     except that <literal>-d 0</> prevents the server log level of the
-     <command>postmaster</> from being propagated to
-     <command>postgres</>.  Other <command>postmaster</command>
-     options are also accepted but will have no noticeable effect
-     because they only apply to the multiuser server mode, namely
-     <option>-h</option>, <option>-i</option>, <option>-k</option>,
-     <option>-l</option>, and <option>-n</option>.
-    </para>
-   </refsect2>
+     <varlistentry>
+      <term><option>-B <replaceable class="parameter">nbuffers</replaceable></option></term>
+      <listitem>
+       <para>
+	Sets the number of shared buffers for use by the server
+	processes.  The default value of this parameter is chosen
+	automatically by <application>initdb</application>; refer to <xref
+	linkend="runtime-config-resource-memory"> for more information.
+       </para>
+      </listitem>
+     </varlistentry>
 
-   <refsect2>
-    <title>Options for stand-alone mode</title>
+     <varlistentry>
+      <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
+      <listitem>
+       <para>
+        Sets a named run-time parameter. The configuration parameters
+        supported by <productname>PostgreSQL</productname> are
+        described in <xref linkend="runtime-config">. Most of the
+        other command line options are in fact short forms of such a
+        parameter assignment.  <option>-c</> can appear multiple times
+        to set multiple parameters.
+       </para>
+      </listitem>
+     </varlistentry>
 
-    <variablelist>
      <varlistentry>
-      <term><replaceable class="parameter">database</replaceable></term>
+      <term><option>-d <replaceable>debug-level</replaceable></option></term>
       <listitem>
        <para>
-	Specifies the name of the database to be accessed.  If it is
-	omitted it defaults to the user name.	
+        Sets the debug level.  The higher this value is set, the more
+        debugging output is written to the server log.  Values are
+        from 1 to 5.  It is also possible to pass <literal>-d
+        0</literal> for a specific session, which will prevent the
+        server log level of the <command>postgres</> from being
+        propagated to this session.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-E</option></term>
+      <term><option>-D <replaceable class="parameter">datadir</replaceable></option></term>
       <listitem>
        <para>
-	Echo all commands.
+        Specifies the file system location of the data directory or
+        configuration file(s).  See
+        <xref linkend="runtime-config-file-locations"> for details.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-j</option></term>
+      <term><option>-e</option></term>
       <listitem>
        <para>
-	Disables use of newline as a statement delimiter.
+        Sets the default date style to <quote>European</quote>, that is
+	<literal>DMY</> ordering of input date fields.  This also causes
+	the day to be printed before the month in certain date output formats.
+	See <xref linkend="datatype-datetime"> for more information.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-r</option> <replaceable class="parameter">filename</replaceable></term>
+      <term><option>-F</option></term>
+      <listitem>
+       <para>
+        Disables <function>fsync</function> calls for improved
+        performance, at the risk of data corruption in the event of a
+        system crash.  Specifying this option is equivalent to
+        disabling the <xref linkend="guc-fsync"> configuration
+        parameter. Read the detailed documentation before using this!
+       </para>
+
+       <para>
+        <option>--fsync=true</option> has the opposite effect
+        of this option.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-h <replaceable class="parameter">hostname</replaceable></option></term>
+      <listitem>
+       <para>
+        Specifies the IP host name or address on which
+        <command>postgres</command> is to listen for TCP/IP
+        connections from client applications.  The value can also be a
+        comma-separated list of addresses, or <literal>*</> to specify
+        listening on all available interfaces.  An empty value
+        specifies not listening on any IP addresses, in which case
+        only Unix-domain sockets can be used to connect to the
+        <command>postgres</command>.  Defaults to listening only on
+        <systemitem class="systemname">localhost</systemitem>.
+        Specifying this option is equivalent to setting the <xref
+        linkend="guc-listen-addresses"> configuration parameter.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-i</option></term>
+      <listitem>
+       <para>
+        Allows remote clients to connect via TCP/IP (Internet domain)
+        connections.  Without this option, only local connections are
+        accepted.  This option is equivalent to setting
+        <varname>listen_addresses</> to <literal>*</> in
+        <filename>postgresql.conf</> or via <option>-h</>.
+       </para>
+       <para>
+        This option is deprecated since it does not allow access to the
+        full functionality of <xref linkend="guc-listen-addresses">.
+        It's usually better to set <varname>listen_addresses</> directly.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-k <replaceable class="parameter">directory</replaceable></option></term>
+      <listitem>
+       <para>
+	Specifies the directory of the Unix-domain socket on which
+	<command>postgres</command> is to listen for
+	connections from client applications.  The default is normally
+	<filename>/tmp</filename>, but can be changed at build time.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-l</option></term>
+      <listitem>
+       <para>
+	Enables secure connections using <acronym>SSL</acronym>.
+	<productname>PostgreSQL</productname> must have been compiled with
+	support for <acronym>SSL</acronym> for this option to be
+	available. For more information on using <acronym>SSL</acronym>,
+	refer to <xref linkend="ssl-tcp">.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-N <replaceable class="parameter">max-connections</replaceable></option></term>
       <listitem>
        <para>
-	Send all server log output to 
-	<replaceable class="parameter">filename</replaceable>.
-	If <command>postgres</command> is running under the
-	<command>postmaster</command>, this option is ignored,
-	and the <systemitem>stderr</> inherited from the
-	<command>postmaster</command> is used.
+	Sets the maximum number of client connections that this
+	<command>postgres</command> will accept.  By
+	default, this value is 32, but it can be set as high as your
+	system will support.  (Note that
+	<option>-B</option> is required to be at least twice
+	<option>-N</option>.  See <xref linkend="kernel-resources"> for a discussion of
+	system resource requirements for large numbers of client
+	connections.) Specifying this option is equivalent to setting the
+	<xref linkend="guc-max-connections"> configuration parameter.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-o <replaceable class="parameter">extra-options</replaceable></option></term>
+      <listitem>
+       <para>
+	The command line-style options specified in <replaceable
+	class="parameter">extra-options</replaceable> are passed to
+	all server processes started by this
+	<command>postgres</command>.  If the option string contains
+	any spaces, the entire string must be quoted.
+       </para>
+
+       <para>
+        The use of this option is obsolete; all command-line options
+        for server processes can be specified directly on the
+        <command>postgres</command> command line
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-p <replaceable class="parameter">port</replaceable></option></term>
+      <listitem>
+       <para>
+	Specifies the TCP/IP port or local Unix domain socket file
+	extension on which <command>postgres</command>
+	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><option>-s</option></term>
+      <listitem>
+       <para>
+	Print time information and other statistics at the end of each command.
+	This is useful for benchmarking or for use in tuning the number of
+	buffers.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-S</option></term>
+      <listitem>
+       <para>
+	Specifies that the <command>postgres</command>
+	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
+	<command>postgres</command> in the background.
+       </para>
+       <para>
+        <option>--silent-mode=false</option> has the opposite effect
+        of this option.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--<replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
+      <listitem>
+       <para>
+        Sets a named run-time parameter; a shorter form of
+        <option>-c</>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>--describe-config</option></term>
+      <listitem>
+       <para>
+        This option dumps out the server's internal configuration variables, 
+        descriptions, and defaults in tab-delimited <command>COPY</> format.
+        It is designed primarily for use by administration tools.
        </para>
       </listitem>
      </varlistentry>
@@ -158,46 +371,199 @@ PostgreSQL documentation
     <title>Semi-internal Options</title>
 
     <para>
-     The options <option>-f</option>, <option>-O</option>,
-     <option>-P</option>, <option>-t</option>, and <option>-W</option>
-     have the same meanings as with the <xref
-     linkend="app-postmaster"> and are reserved for debugging and
-     disaster recovery.  Further options for internal use are:
+     There are several other options that may be specified, used
+     mainly for debugging purposes and in some cases to assist with
+     recovery of severely damaged databases. There should be no reason
+     to use them in a production database setup.  These are listed
+     here only for the use by <productname>PostgreSQL</productname>
+     system developers.  Furthermore, any of these options may
+     disappear or change in a future release without notice.
+    </para>
 
     <variablelist>
      <varlistentry>
+      <term><option>-f</option> <literal>{ s | i | m | n | h }</literal></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.
+       </para>
+	
+       <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>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-n</option></term>
+      <listitem>
+       <para>
+        This option is for debugging problems that cause a server
+        process to die abnormally.  The ordinary strategy in this
+        situation is to notify all other server processes that they
+        must terminate and then reinitialize the shared memory and
+        semaphores.  This is because an errant server process could
+        have corrupted some shared state before terminating.  This
+        option specifies that <command>postgres</command> will
+        not reinitialize shared data structures.  A knowledgeable
+        system programmer can then use a debugger to examine shared
+        memory and semaphore state.
+       </para>
+     </listitem>
+    </varlistentry>
+
+     <varlistentry>
+      <term><option>-O</option></term>
+      <listitem>
+       <para>
+	Allows the structure of system tables to be modified.  This is
+	used by <command>initdb</command>.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-P</option></term>
+      <listitem>
+       <para>
+	Ignore system indexes when reading system tables (but still update
+	the indexes when modifying the tables).  This is useful when
+	recovering from damaged system indexes.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-t</option> <literal>pa[rser] | pl[anner] | e[xecutor]</literal></term>
+      <listitem>
+       <para>
+	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>
+
+     <varlistentry>
+      <term><option>-T</option></term>
+      <listitem>
+       <para>
+        This option is for debugging problems that cause a server
+        process to die abnormally.  The ordinary strategy in this
+        situation is to notify all other server processes that they
+        must terminate and then reinitialize the shared memory and
+        semaphores.  This is because an errant server process could
+        have corrupted some shared state before terminating.  This
+        option specifies that <command>postgres</command> will
+        stop all other server processes by sending the signal
+        <literal>SIGSTOP</literal>, but will not cause them to
+        terminate.  This permits system programmers to collect core
+        dumps from all server processes by hand.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>-v</option> <replaceable class="parameter">protocol</replaceable></term>
       <listitem>
        <para>
 	Specifies the version number of the frontend/backend protocol
-	to be used for this particular session.
+	to be used for a particular session.  This option is for
+	internal use only.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-y</option> <replaceable class="parameter">database</replaceable></term>
+      <term><option>-W</option> <replaceable class="parameter">seconds</replaceable></term>
       <listitem>
        <para>
-	Indicates that this process has been started by a
-	<command>postmaster</command> and specifies the database to use.
-	etc.
+        A delay of this many seconds occurs when a new server process
+        is started, after it conducts the authentication procedure.
+        This is intended to give an opportunity to attach to the
+        server process with a debugger.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>--describe-config</option></term>
+      <term><option>-y</option> <replaceable class="parameter">database</replaceable></term>
       <listitem>
        <para>
-        This option dumps out the server's internal configuration variables, 
-        descriptions, and defaults in tab-delimited <command>COPY</> format.
-        It is designed primarily for use by administration tools.
+	Indicates that this is a subprocess started by
+	<command>postgres</command> and specifies the database to
+	use.  This option is for internal use only.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
+   </refsect2>
+
+   <refsect2>
+    <title>Options for single-user mode</title>
+
+    <para>
+     The following options only apply to the single-user mode.
     </para>
+
+    <variablelist>
+     <varlistentry>
+      <term><option>--single</option></term>
+      <listitem>
+       <para>
+	Selects the single-user mode.  This must be the first argument
+	on the command line.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><replaceable class="parameter">database</replaceable></term>
+      <listitem>
+       <para>
+	Specifies the name of the database to be accessed.  If it is
+	omitted it defaults to the user name.	
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-E</option></term>
+      <listitem>
+       <para>
+	Echo all commands.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-j</option></term>
+      <listitem>
+       <para>
+	Disables use of newline as a statement delimiter.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-r</option> <replaceable class="parameter">filename</replaceable></term>
+      <listitem>
+       <para>
+	Send all server log output to <replaceable
+	class="parameter">filename</replaceable>.  In normal multiuser
+	mode, this option is ignored, and <systemitem>stderr</> is
+	used by all processes.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
    </refsect2>
  </refsect1>
 
@@ -206,6 +572,18 @@ PostgreSQL documentation
 
   <variablelist>
    <varlistentry>
+    <term><envar>PGCLIENTENCODING</envar></term>
+
+    <listitem>
+     <para>
+      Default character encoding used by clients.  (The clients may
+      override this individually.)  This value can also be set in the
+      configuration file.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
     <term><envar>PGDATA</envar></term>
 
     <listitem>
@@ -214,47 +592,154 @@ PostgreSQL documentation
      </para>
     </listitem>
    </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGDATESTYLE</envar></term>
+
+    <listitem>
+     <para>
+      Default value of the <xref linkend="guc-datestyle"> run-time
+      parameter.  (The use of this environment variable is deprecated.)
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>PGPORT</envar></term>
+
+    <listitem>
+     <para>
+      Default port (preferably set in the configuration file)
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><envar>TZ</envar></term>
+
+    <listitem>
+     <para>
+      Server time zone
+     </para>
+    </listitem>
+   </varlistentry>
+
   </variablelist>
  </refsect1>
 
  <refsect1>
+   <title>Diagnostics</title>
+
+   <para>
+    A failure message mentioning <literal>semget</> or
+    <literal>shmget</> probably indicates you need to configure your
+    kernel to provide adequate shared memory and semaphores.  For more
+    discussion see <xref linkend="kernel-resources">.  You may be able
+    to postpone reconfiguring your kernel by decreasing <xref
+    linkend="guc-shared-buffers"> to reduce the shared memory
+    consumption of <productname>PostgreSQL</>, and/or by reducing
+    <xref linkend="guc-max-connections"> to reduce the semaphore
+    consumption.
+   </para>
+
+   <para>
+    A failure message suggesting that another server is already running
+    should be checked carefully, for example by using the command
+<screen>
+<prompt>$</prompt> <userinput>ps ax | grep postgres</userinput>
+</screen>
+        or
+<screen>
+<prompt>$</prompt> <userinput>ps -ef | grep postgres</userinput>
+</screen>
+    depending on your system.  If you are certain that no conflicting
+    server is running, you may remove the lock file mentioned in the
+    message and try again.
+   </para>
+
+   <para>
+    A failure message indicating inability to bind to a port may
+    indicate that that port is already in use by some
+    non-<productname>PostgreSQL</productname> process.  You may also
+    get this error if you terminate <command>postgres</command>
+    and immediately restart it using the same port; in this case, you
+    must simply wait a few seconds until the operating system closes
+    the port before trying again.  Finally, you may get this error if
+    you specify a port number that your operating system considers to
+    be reserved.  For example, many versions of Unix consider port
+    numbers under 1024 to be <quote>trusted</quote> and only permit
+    the Unix superuser to access them.
+   </para>
+
+ </refsect1>
+
+ <refsect1>
   <title>Notes</title>
+  
+  <para>
+   If at all possible, <emphasis>do not</emphasis> use
+   <literal>SIGKILL</literal> to kill the main
+   <command>postgres</command> server.  Doing so will prevent
+   <command>postgres</command> from freeing the system
+   resources (e.g., shared memory and semaphores) that it holds before
+   terminating.  This may cause problems for starting a fresh
+   <command>postgres</command> run.
+  </para>
 
   <para>
-   To cancel a running query, send the <literal>SIGINT</literal> signal
-   to the <command>postgres</command> process running that command.
+   To terminate the <command>postgres</command> server 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 proper shutdown, resulting in a recovery run
+   during restart.  The <literal>SIGHUP</literal> signal will reload
+   the server configuration files.  It is also possible to send
+   <literal>SIGHUP</literal> to an individual server process, but that
+   is usually not sensible.
+  </para>
+
+  <para>
+   The utility command <xref linkend="app-pg-ctl"> can be used to
+   start and shut down the <command>postgres</command> server
+   safely and comfortably.
   </para>
 
   <para>
-   To tell <command>postgres</command> to reload the configuration files,
-   send a <literal>SIGHUP</literal> signal.  Normally it's best to
-   <literal>SIGHUP</literal> the <command>postmaster</command> instead;
-   the <command>postmaster</command> will in turn <literal>SIGHUP</literal>
-   each of its children.  But in some cases it might be desirable to have only
-   one <command>postgres</command> process reload the configuration files.
+   To cancel a running query, send the <literal>SIGINT</literal> signal
+   to the process running that command.
   </para>
 
   <para>
-   The <command>postmaster</command> uses <literal>SIGTERM</literal>
-   to tell a <command>postgres</command> process to quit normally and
+   The <command>postgres</command> server uses <literal>SIGTERM</literal>
+   to tell subordinate server processes to quit normally and
    <literal>SIGQUIT</literal> to terminate without the normal cleanup.
-   These signals <emphasis>should not</emphasis> be used by users.  It is also
-   unwise to send <literal>SIGKILL</literal> to a <command>postgres</command>
-   process &mdash; the <command>postmaster</command> will interpret this as
-   a crash in <command>postgres</command>, and will force all the sibling
-   <command>postgres</command> processes to quit as part of its standard
-   crash-recovery procedure.
+   These signals <emphasis>should not</emphasis> be used by users.  It
+   is also unwise to send <literal>SIGKILL</literal> to a server
+   process &mdash; the main <command>postgres</command> process will
+   interpret this as a crash and will force all the sibling processes
+   to quit as part of its standard crash-recovery procedure.
   </para>
+ </refsect1>
 
+ <refsect1 id="app-postgres-bugs">
+  <title>Bugs</title>
+  <para>
+   The <option>--</> options will not work on <systemitem
+   class="osname">FreeBSD</> or <systemitem class="osname">OpenBSD</>.
+   Use <option>-c</> instead. This is a bug in the affected operating
+   systems; a future release of <productname>PostgreSQL</productname>
+   will provide a workaround if this is not fixed.
+  </para>
  </refsect1>
 
  <refsect1>
   <title>Usage</title>
 
    <para>
-    Start a stand-alone server with a command like
+    To start a single-user mode server, use a command like
 <screen>
-<userinput>postgres -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
+<userinput>postgres --single -D /usr/local/pgsql/data <replaceable>other-options</> my_database</userinput>
 </screen>
     Provide the correct path to the database directory with <option>-D</>, or
     make sure that the environment variable <envar>PGDATA</> is set.
@@ -262,7 +747,7 @@ PostgreSQL documentation
    </para>
 
    <para>
-    Normally, the stand-alone server treats newline as the command
+    Normally, the single-user mode server treats newline as the command
     entry terminator; there is no intelligence about semicolons,
     as there is in <application>psql</>.  To continue a command
     across multiple lines, you must type backslash just before each
@@ -285,10 +770,57 @@ PostgreSQL documentation
    </para>
 
    <para>
-    Note that the stand-alone server does not provide sophisticated
+    Note that the single-user mode server does not provide sophisticated
     line-editing features (no command history, for example).
    </para>
+ </refsect1>
+
+ <refsect1 id="app-postgres-examples">
+  <title>Examples</title>
 
+  <para>
+   To start <command>postgres</command> in the background
+   using default values, type:
+
+<screen>
+<prompt>$</prompt> <userinput>nohup postgres &gt;logfile 2&gt;&amp;1 &lt;/dev/null &amp;</userinput>
+</screen>
+  </para>
+
+  <para>
+   To start <command>postgres</command> with a specific
+   port:
+<screen>
+<prompt>$</prompt> <userinput>postgres -p 1234</userinput>
+</screen>
+   This command will start up <command>postgres</command>
+   communicating through the port 1234. In order to connect to this
+   <command>postgres</command> using <application>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>:
+<screen>
+<prompt>$</prompt> <userinput>export PGPORT=1234</userinput>
+<prompt>$</prompt> <userinput>psql</userinput>
+</screen>
+  </para>
+
+  <para>
+   Named run-time parameters can be set in either of these styles:
+<screen>
+<prompt>$</prompt> <userinput>postgres -c work_mem=1234</userinput>
+<prompt>$</prompt> <userinput>postgres --work-mem=1234</userinput>
+</screen>
+   Either form overrides whatever setting might exist for
+   <varname>work_mem</> in <filename>postgresql.conf</>.  Notice that
+   underscores in parameter names can be written as either underscore
+   or dash on the command line.  Except for short-term experiments,
+   it's probably better practice to edit the setting in
+   <filename>postgresql.conf</> than to rely on a command-line switch
+   to set a parameter.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -296,26 +828,7 @@ PostgreSQL documentation
 
   <para>
    <xref linkend="app-initdb">,
-   <xref linkend="app-ipcclean">,
-   <xref linkend="app-postmaster">
+   <xref linkend="app-pg-ctl">
   </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:
--->