.\" XXX standard disclaimer belongs here....
.\" $Header: /private/postgres/ref/unix/RCS/postmaster,v 1.12 1992/08/18 18:14:12 mao Exp $
.SP POSTMASTER UNIX 6/14/90
.XA 1 "The \*(PP Postmaster"
.uh "NAME"
.lp
postmaster \*- run the \*(PP postmaster
.uh "SYNOPSIS"
.lp
.(l
\fBpostmaster\fR [ -p port ] [ -b backend_pathname ] [ -d debug_level ] [ -s ] [ -n ] &
.)l
.uh "DESCRIPTION"
.lp
The postmaster manages the communication between frontends and backends,
as well as allocating the shared buffer pool and semaphores (on machines
without TAS).  The postmaster
does not itself interact with the user so it should be started as a background
process.  \fBOnly one postmaster should be run on a machine!\fR
.sp
.uh "COMMAND OPTIONS"
.lp
\fIport\fR is the well known TCP/IP port used for network 
communication between a libpq application and the backend.  If you specify
a port other than the default port then you must specify the same port when 
starting any libpq application including the terminal monitor.  Alternatively
you may set the environment variable PGPORT to the specified port and all
libpq applications will use it instead of the default.
.lp
\fIbackend_pathname\fR is the full pathname of the \*(PP backend you
wish to use.
.lp
\fIdeug_level\fR determines the amount of debugging output the backend will
produce.  Specifying any level will cause the postmaster to print out
a few terse debugging output messages to the tty on which it was started.
.lp
The
\fI\-s\fP and \fI\-n\fP options control the behavior of the postmaster
when a backend dies abnormally.
The ordinary strategy for this situation is to notify all other backends
that they must terminate,
and to reinitialize shared memory and semaphores.
This is because an errant backend,
before dumping core,
could have contaminated some shared state.
.lp
If the \fI\-s\fP option is supplied, then the postmaster will stop all
other backends,
but will not cause them to terminate.
This permits system programmers to collect core dumps from all concurrent
backends by hand.
.lp
If the \fI\-n\fP command-line option is supplied,
then the postmaster does not reinitialize shared data structures.
A knowledgable system programmer can use the
.i shmemdoc
program to examine shared memory and semaphore state,
in order to debug the problem.
.lp
Neither \fI\-s\fP nor \fI\-n\fP is intended for use in ordinary operation.
.sp
.uh "EXAMPLES"
.lp
.ft C
postmaster &
.ft
.lp
This command will start up a postmaster on the default port (4321) and 
will expect to use the default path to the 
\*(PP backend ($POSTGRESHOME/bin/postgres) or /usr/postgres/bin/postgres.
This is the simplest and most common way to start the postmaster.
.sp
.lp
.ft C
postmaster -p 1234 -b /a/postgres/bin/postgres &
.ft
.lp
This command will start up a postmaster communicating through the port
1234, and will expect to use the backend located at
/a/postgres/bin/postgres.  Note: to connect to this postmaster using
the terminal monitor, you would need to specify \fB-p 1234\fR on
the command line invoking the terminal monitor.
.sp
.uh "DIAGNOSTICS"
.lp
\fBsemget: No space left on device\fR
.lp
If you see this message, you should run the \fIipcclean\fR command.
After doing this, try starting the postmaster again.  If this still doesn't
work, you will need to configure your kernel for shared memory and
semaphores as described in the installation notes.
.lp
\fBStreamServerPort: cannot bind to port\fR
.lp
If you see this message, you should be certain that there is no other 
postmaster program already running.  The easiest way to determine this is
by the command "ps -ax | grep postmaster".  If you are sure there is no
other postmaster running and you still get this error try specifying a
different port using the -p option.  You may also get this error if you
terminate the postmaster and immediately restart it using the same port;
in this case, you should simply wait until the operating system closes
the port.
.lp
.uh "SEE ALSO"
.lp
postgres(unix), monitor(unix), ipcclean(unix), shmemdoc(unix).
