diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index f2f959ef39d20f39f49518258994574acdf8c7ae..958bcd3b3dad73f6e50936ffd8cb85a81d7cd094 100644
--- 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 &