Improve descriptions of postmaster switches.

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 &