Improve descriptions of postmaster switches.

diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index f2f959ef39d20f39f49518258994574acdf8c7ae..958bcd3b3dad73f6e50936ffd8cb85a81d7cd094 100644 (file)
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.7 1999/10/12 13:59:45 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.8 2000/03/26 07:04:54 tgl Exp $
 Postgres documentation
 -->
 
@@ -23,10 +23,9 @@ Postgres documentation
    <date>1999-07-20</date>
   </refsynopsisdivinfo>
   <synopsis>
-postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -i ] [ -l ]
-postmaster [ -B <replaceable class="parameter">nBuffers</replaceable> ] [ -D <replaceable class="parameter">DataDir</replaceable> ] [ -N <replaceable class="parameter">nBackends</replaceable> ] [ -S ]
-   [ -d [ <replaceable class="parameter">DebugLevel</replaceable> ] [ -i ] [ -l ] [ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
-postmaster [ -n | -s ] ...
+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> ] [ -i ] [ -l ]
+ [ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ] [ -n | -s ]
   </synopsis>
 
   <refsect2 id="R2-APP-POSTMASTER-1">
@@ -44,11 +43,11 @@ postmaster [ -n | -s ] ...
       <term>-B <replaceable class="parameter">nBuffers</replaceable></term>
       <listitem>
        <para>
-   The number of shared-memory buffers for the 
+   Sets the number of shared-memory disk buffers for the 
    <application>postmaster</application>
-   to allocate and manage for the backend server processes that it
+   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 config.h).
+   (or whatever BLCKSZ is set to in src/include/config.h).
        </para>
       </listitem>
      </varlistentry>
@@ -71,15 +70,17 @@ postmaster [ -n | -s ] ...
      </varlistentry>
 
      <varlistentry>
-      <term>-N <replaceable class="parameter">nBackends</replaceable></term>
+      <term>-N <replaceable class="parameter">maxBackends</replaceable></term>
       <listitem>
        <para>
-   The maximum number of backend server processes that this postmaster
-   is allowed to start.  In the default configuration, this value
-   is usually set
-   to 32, and can be set as high as 1024 if your system will support that
-   many processes. Both the default and upper limit values can be altered
-   when building <productname>Postgres</productname> (see src/include/config.h).
+   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).
        </para>
       </listitem>
      </varlistentry>
@@ -90,31 +91,34 @@ postmaster [ -n | -s ] ...
        <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 and start its own process group.
-   This should not be used in combination with debugging options because
-   any messages printed to standard output and standard error are 
-   discarded.
+   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.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-d [ <replaceable class="parameter">DebugLevel</replaceable> ]</term>
+      <term>-d <replaceable class="parameter">DebugLevel</replaceable></term>
       <listitem>
        <para>
-   This argument <replaceable class="parameter">DebugLevel</replaceable>
-   determines the amount of debugging output the backend servers will
+   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,
+   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 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>.
+   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>.
        </para>
       </listitem>
      </varlistentry>
@@ -123,9 +127,9 @@ postmaster [ -n | -s ] ...
       <term>-i</term>
       <listitem>
        <para>
-   This enables TCP/IP or Internet domain socket communication.
-   Without this option, only local Unix domain socket communication is
-   possible.
+        Allows clients to connect via TCP/IP (Internet domain) connections.
+   Without this option, only local Unix domain socket connections are
+   accepted.
        </para>
       </listitem>
      </varlistentry>
@@ -134,9 +138,9 @@ postmaster [ -n | -s ] ...
       <term>-l</term>
       <listitem>
        <para>
-   This enables SSL socket communication.  The <option>-i</option> option
+   Enables secure connections using SSL.  The <option>-i</option> option
    is also required.
-   You have to have compiled with SSL enabled to use this option.
+   You must have compiled with SSL enabled to use this option.
        </para>
       </listitem>
      </varlistentry>
@@ -147,7 +151,7 @@ postmaster [ -n | -s ] ...
        <para>
    The 
    <literal>postgres</literal>
-   options specified in
+   option(s) specified in
    <replaceable class="parameter">BackendOptions</replaceable>
    are passed to all backend server processes started by this
    <application>postmaster</application>.
@@ -180,8 +184,8 @@ postmaster [ -n | -s ] ...
    </para>
 
    <para>
-    A few command line options are available for debugging in the case 
-    when a backend dies abnormally.
+    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
@@ -204,10 +208,9 @@ postmaster [ -n | -s ] ...
       <listitem>
        <para>
    <application>postmaster</application>
-   will not reinitialize shared data structures.  A knowledgable system
-   programmer can then use the
-   <application>shmemdoc</application>
-   program to examine shared memory and semaphore state.
+   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>
@@ -262,7 +265,7 @@ semget: No space left on device
        <para>
    If you see this message, you should run the
    <application>ipcclean</application>
-   command.  After doing this, try starting
+   command.  After doing so, 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
@@ -277,7 +280,7 @@ semget: No space left on device
      You may be able to postpone
      reconfiguring your kernel by decreasing -B to reduce
      <productname>Postgres</productname>' shared memory
-     consumption, or by reducing -N to reduce Postgres' semaphore
+     consumption, and/or by reducing -N to reduce Postgres' semaphore
      consumption.
     </para>
    </tip>
@@ -291,10 +294,10 @@ StreamServerPort: cannot bind to port
        </computeroutput></term>
       <listitem>
        <para>
-   If you see this message, you should be certain that there is no other 
-   <application>postmaster</application>
-   process already running.  The easiest way to determine this is by
-   using the command
+   If you see this message, you should make certain that there is no
+   other <application>postmaster</application>
+   process already running on the same port number.  The easiest way to
+   determine this is by using the command
    <programlisting>
 % ps -ax | grep postmaster
    </programlisting>
@@ -416,8 +419,8 @@ or its alternative form
 
    will prevent <application>postmaster</application>
    from freeing the system resources (e.g., shared memory and semaphores)
-   that it holds before dying.  This prevents you from having to deal with
-   the problem with shared memory described earlier.
+   that it holds before dying.  Use <literal>SIGTERM</literal> instead
+   to avoid having to clean up manually (as described earlier).
   </para>
 
   <para>
@@ -450,8 +453,7 @@ or its alternative form
   </para>
 
   <para>
-   To start <application>postmaster</application> with a specific port
-   and executable name:
+   To start <application>postmaster</application> with a specific port:
 
    <programlisting>
 % nohup postmaster -p 1234 &