First copy from the man pages.

postgres-ref.sgml is not yet marked up.

2 files changed, 720 insertions, 0 deletions

diff --git a/doc/src/sgml/ref/postgres-ref.sgml b/doc/src/sgml/ref/postgres-ref.sgml
new file mode 100644
index 00000000000..ff3b3329524
--- /dev/null
+++ b/doc/src/sgml/ref/postgres-ref.sgml
@@ -0,0 +1,220 @@
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/doc/src/sgml/ref/postgres-ref.sgml,v 1.1 1999/05/26 17:25:38 thomas Exp $
+.TH POSTGRESQL UNIX 05/19/99 PostgreSQL PostgreSQL
+.SH NAME
+postgres - the Postgres backend server
+.SH SYNOPSIS
+.BR "postgres"
+[\c
+.BR "-B"
+n_buffers]
+[\c
+.BR "-C"
+]
+[\c
+.BR "-D"
+data_directory]
+[\c
+.BR "-E"
+]
+[\c
+.BR "-F"
+]
+[\c
+.BR "-O"
+]
+[\c
+.BR "-Q"
+]
+[\c
+.BR "-S kbytes"
+]
+[\c
+.BR "-d"
+debug_level]
+[\c
+.BR "-e"
+]
+[\c
+.BR "-o"
+output_file]
+[\c
+.BR "-s"
+]
+[\c
+.BR "-v protocol"
+]
+[dbname]
+.in -5n
+.SH DESCRIPTION
+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
+.IR postmaster
+on this set of databases.
+.PP
+Some of the switches explained in this man page 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.
+.PP
+The optional argument
+.IR dbname
+specifies the name of the database to be accessed.
+.IR Dbname
+defaults to the value of the
+.SM USER
+environment variable.
+.PP
+The 
+.IR postgres
+server understands the following command-line options:
+.TP
+.BR "-B" " n_buffers"
+If the backend is running under the 
+.IR postmaster ,
+.IR "n_buffers"
+is the number of shared-memory buffers that the
+.IR "postmaster"
+has allocated for the backend server processes that it starts.  If the
+backend is running standalone, 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).
+.TP
+.BR "-C"
+Do not show server version number.
+.TP
+.BR "-D" " data_directory"
+This option specifies the pathname of the directory that contains the
+database system data (the tables, the catalogs, etc.).  If you don't 
+specify this option, Postgres uses the value of the PGDATA environment
+variable.  You must either specify a -D option or set PGDATA.
+ 
+The data directory pathname for a database system is normally determined when
+the database system is created with
+.IR initdb ,
+with a --pgdata option to
+.IR initdb .
+.TP
+.BR "-E"
+Echo all queries.
+.TP
+.BR "-F"
+Disable automatic fsync() call after each transaction.
+This option improves performance, but an operating system crash
+while a transaction is in progress will probably cause data loss.
+.TP
+.BR "-O"
+Override restrictions, so system table structures can be modified(pg_*).
+.TP
+.BR "-Q"
+Specifies \*(lqquiet\*(rq mode.
+.TP
+.BR "-S" " kbytes"
+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 -S kilobytes before it starts to put
+data into temporary files.
+.TP
+.BR "-e"
+The
+.IR "-e"
+option controls how dates are input to and output from the database.
+.IP
+If the
+.IR "-e"
+option is supplied, then all dates passed to and from the frontend
+processes will be assumed to be in
+.IR "European"
+format ie.
+.IR "DD-MM-YYYY"
+otherwise dates are input and output in
+.IR "American"
+format ie.
+.IR "MM-DD-YYYY"
+.TP
+.BR "-d" " debug_level"
+Turns on debugging at the numeric level
+.IR "debug_level" .
+Turning on debugging will cause query, parse trees, and query plans to
+be displayed.
+.TP
+.BR "-o" " output_file"
+Sends all debugging and error output to 
+.IR output_file .
+If the backend is running under the 
+.IR postmaster ,
+error messages are still sent to the frontend process as well as to
+.IR output_file ,
+but debugging output is sent to the controlling tty of the
+.IR postmaster
+(since only one file descriptor can be sent to an actual file).
+.TP
+.BR "-s"
+Print time information and other statistics at the end of each query.
+This is useful for benchmarking or for use in tuning the number of
+buffers.
+.TP
+.BR "-v" " protocol"
+Specifies the number of the frontend/backend protocol to be used for this
+particular session.
+.SH "DEVELOPER COMMAND OPTIONS"
+There are several other options that may be specified, used mainly
+for debugging purposes.  These are listed here only for the use by
+Postgres system developers.
+.BR "Use of any of these options is highly discouraged" .
+Furthermore, any of these options may disappear or change at any time.
+.TP
+.BR "-A" "n|r|b|Q\fIn\fP|X\fIn\fP"
+.IP
+This option generates a tremendous amount of output.
+.TP
+.BR "-L"
+Turns off the locking system.
+.TP
+.BR "-N"
+Disables use of newline as a query delimiter.
+.TP
+.BR "-f"
+Forbids the use of particular scan and join methods:
+.IR s " and " i
+disable sequential and index scans respectively, while
+.IR n ", " m " and " h
+disable nested-loop, merge and hash joins respectively.
+(Neither sequential scans nor nested-loop joins can be disabled completely;
+the -fs and -fn options simply discourage the optimizer from using those
+plan types if it has any other alternative.)
+.TP
+.BR "-i"
+Prevents query execution, but shows the plan tree.
+.TP
+.BR "-p" " databasename"
+Indicates to the backend server that it has been started by a 
+.IR postmaster
+and make different assumptions about buffer pool management, file
+descriptors, etc.  Switches following -p are restricted to those
+considered "secure".
+.TP
+.BR "-t" "pa[rser]|pl[anner]|e[xecutor]"
+Print timing statistics for each query relating to each of the major
+system modules.  This option cannot be used with
+.BR "-s" .
+.SH "SEE ALSO"
+ipcclean(1),
+psql(1), 
+postmaster(1).
+.SH "DIAGNOSTICS"
+Of the nigh-infinite number of error messages you may see when you
+execute the backend server directly, the most common will probably be:
+.TP
+.BR "semget: No space left on device"
+If you see this message, you should run the
+.IR ipcclean
+command.  After doing this, try starting
+.IR postgres
+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.
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
new file mode 100644
index 00000000000..16f318c8143
--- /dev/null
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -0,0 +1,500 @@
+<refentry id="APP-POSTMASTER">
+ <refmeta>
+  <refentrytitle>
+   <application>postmaster</application>
+  </refentrytitle>
+  <refmiscinfo>Application</refmiscinfo>
+ </refmeta>
+ <refnamediv>
+  <refname id="postmaster">
+   <application>postmaster</application>
+  </refname>
+  <refpurpose>
+   Run the <productname>Postgres</productname> multi-user backend
+  </refpurpose>
+ </refnamediv>
+ <refsynopsisdiv>
+  <refsynopsisdivinfo>
+   <date>1999-05-19</date>
+  </refsynopsisdivinfo>
+  <synopsis>
+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 ] [ -o <replaceable class="parameter">BackendOptions</replaceable> ] [ -p <replaceable class="parameter">port</replaceable> ]
+postmaster [ -n | -s ] ...
+  </synopsis>
+
+  <refsect2 id="R2-APP-POSTMASTER-1">
+   <refsect2info>
+    <date>1999-05-19</date>
+   </refsect2info>
+   <title>
+    Inputs
+   </title>
+   <para>
+    <application>postmaster</application> accepts the following command line arguments:
+    
+    <variablelist>
+     <varlistentry>
+      <term>
+       -B <replaceable class="parameter">nBuffers</replaceable>
+      </term>
+      <listitem>
+       <para>
+	The number of shared-memory buffers for the 
+	<application>postmaster</application>
+	to allocate and manage for 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).
+       </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>
+
+     <varlistentry>
+      <term>
+       -N <replaceable class="parameter">nBackends</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).
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       -S
+      </term>
+      <listitem>
+       <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.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <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>
+
+     <varlistentry>
+      <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.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       -o <replaceable class="parameter">BackendOptions</replaceable>
+      </term>
+      <listitem>
+       <para>
+	The 
+	<literal>postgres</literal>
+	options specified in
+	<replaceable class="parameter">BackendOptions</replaceable>
+	are passed to all backend server processes started by this
+	<application>postmaster</application>.
+	If the option string contains any spaces, the entire string must be
+	quoted.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       -p <replaceable class="parameter">port</replaceable>
+      </term>
+      <listitem>
+       <para>
+	Specifies the TCP/IP port or local Unix domain socket file extension
+	on which the <application>postmaster</application>
+	is to listen for connections from frontend 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 when Postgres was
+	compiled (normally 5432).  If you specify a port other than the
+	default port then all frontend applications (including
+	<application>psql</application>) must specify the same
+	port using either command-line options or
+	<envar>PGPORT</envar>.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+
+   <para>
+    A few command line options are available for debugging in the case 
+    when a backend dies abnormally.
+    These options control the behavior of the
+    <application>postmaster</application> in this situation, and
+    <emphasis>neither option is intended for use in
+     ordinary operation</emphasis>.
+   </para>
+
+   <para>
+    The ordinary strategy for this situation is to notify all other
+    backends that they must terminate and then reinitialize the shared
+    memory and semaphores.  This is because an errant backend could have
+    corrupted some shared state before terminating.
+   </para>
+
+   <para>
+    These special-case options are:
+
+    <variablelist>
+     <varlistentry>
+      <term>
+       -n
+      </term>
+      <listitem>
+       <para>
+	If the <literal>-n</literal>
+	option is supplied, then the
+	<application>postmaster</application>
+	does not reinitialize shared data structures.  A knowledgable system
+	programmer can then use the
+	<application>shmemdoc</application>
+	program to examine shared memory and semaphore state.
+       </para>
+     </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>
+       -s
+      </term>
+      <listitem>
+       <para>
+	<application>postmaster</application>
+	will stop all other backend 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 backend processes by hand.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+  </refsect2>
+
+  <refsect2 id="R2-APP-POSTMASTER-1">
+   <refsect2info>
+    <date>1999-05-19</date>
+   </refsect2info>
+   <title>
+    Outputs
+   </title>
+   <para>
+
+    <variablelist>
+     <!--
+     <varlistentry>
+      <term>
+       FindBackend: could not find a backend to execute...
+      </term>
+      <listitem>
+       <para>
+	If you see this message, you do not have the 
+	<application>postgres</application>
+     executable in your path.  Add the directory in which
+    <application>postgres</application> resides to
+	your path.
+       </para>
+      </listitem>
+     </varlistentry>
+     -->
+     <varlistentry>
+      <term>
+       semget: No space left on device
+      </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 run multiple instances of
+	<application>postmaster</application>
+	on a single host, or 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.
+
+	<tip>
+	 <para>
+	  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.
+	 </para>
+	</tip>
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       StreamServerPort: cannot bind to port
+      </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
+	<programlisting>
+% ps -ax | grep postmaster
+	</programlisting>
+on BSD-based systems, or
+	<programlisting>
+% ps -e | grep postmast
+	</programlisting>
+	for System V-like or POSIX-compliant systems such as HP-UX.
+       </para>
+
+       <para>
+	If you 
+	are sure that no other
+	<application>postmaster</application>
+	processes are running and you still get this error, try specifying a
+	different port using the
+	<literal>-p</literal>
+	option.  You may also get this error if you terminate the
+	<application>postmaster</application>
+	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 <firstterm>trusted</firstterm>
+	and only permit the Unix superuser to access them.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       IpcMemoryAttach: shmat() failed: Permission denied
+      </term>
+      <listitem>
+       <para>
+	A likely explanation is that another user attempted to start a
+	<application>postmaster</application>
+	process on the same port which acquired shared resources and then 
+	died.  Since Postgres shared memory keys are based on the port number 
+	assigned to the
+	<application>postmaster</application>,
+	such conflicts are likely if there is more than one installation on 
+	a single host.  If there are no other
+	<application>postmaster</application>
+	processes currently running (see above), run
+	<application>ipcclean</application>
+	and try again.  If other <application>postmaster</application>
+	images
+	are running, you will have to find the owners of those processes to
+	coordinate the assignment of port numbers and/or removal of unused
+	shared memory segments.
+       </para>
+      </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+  </refsect2>
+ </refsynopsisdiv>
+
+ <refsect1 id="R1-APP-POSTMASTER-1">
+  <refsect1info>
+   <date>1999-05-19</date>
+  </refsect1info>
+  <title>
+   Description
+  </title>
+
+  <para>
+   <application>postmaster</application>
+   manages the communication between frontend and backend processes, as
+   well as allocating the shared buffer pool and SysV semaphores
+   (on machines without a test-and-set instruction).
+   <application>postmaster</application>
+   does not itself interact with the user and should be started as a
+   background process.
+  </para>
+
+  <para>
+   <emphasis>Only one postmaster should be running at a time in a given
+    <productname>Postgres</productname> installation.</emphasis>
+   Here, an installation means a database directory and
+   <application>postmaster</application> port number.
+   You can run more than one postmaster on a machine only if each one has a
+   separate directory and port number.
+  </para>
+
+ <refsect1 id="R1-APP-VACUUMDB-2">
+  <refsect1info>
+   <date>1998-10-04</date>
+  </refsect1info>
+  <title>
+   Notes
+  </title>
+  
+  <para>
+   If at all possible,
+   <emphasis>do not</emphasis>
+   use <literal>SIGKILL</literal>
+   when killing the <application>postmaster</application>.
+   <literal>SIGHUP</literal>,
+   <literal>SIGINT</literal>,
+   or
+   <literal>SIGTERM</literal>
+   (the default signal for 
+   <application>kill</application>(1))"
+   should be used instead. Using
+
+   <programlisting>
+% kill -KILL
+   </programlisting>
+
+or its alternative form
+
+   <programlisting>
+% kill -9
+   </programlisting>
+
+   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.
+  </para>
+
+  <para>
+   Useful utilities for dealing with shared memory problems include
+   <application>ipcs(1)</application>,
+   <application>ipcrm(1</application>), and
+   <application>ipcclean(1)</application>.
+  </para>
+ </refsect1>
+ 
+ <refsect1 id="R1-APP-VACUUMDB-3">
+  <refsect1info>
+   <date>1998-10-04</date>
+  </refsect1info>
+  <title>
+   Usage
+  </title>
+  <para>
+   To start <application>postmaster</application> using default
+   values, type:
+
+   <programlisting>
+% nohup postmaster >logfile 2>&1 &
+   </programlisting>
+
+   This command will start up <application>postmaster</application>
+   on the default port (5432). This is the
+   simplest and most common way to start the
+   <application>postmaster</application>.
+  </para>
+
+  <para>
+   To start <application>postmaster</application> with a specific port
+   and executable name:
+
+   <programlisting>
+% nohup postmaster -p 1234 &
+   </programlisting>
+
+   This command will start up <application>postmaster</application>
+   communicating through the port 1234. In order to
+   connect to this <application>postmaster</application>
+   using psql, you would need to run it as
+
+   <programlisting>
+% psql -p 1234
+   </programlisting>
+
+   or set the environment variable <envar>PGPORT</envar>:
+
+   <programlisting>
+% setenv PGPORT 1234
+% psql
+   </programlisting>.
+
+ </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:
+-->