<!--

$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.5 2000/12/25 23:15:26 petere Exp $

$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.6 2001/02/08 19:39:24 petere Exp $

Postgres documentation

-->

<refentry id="app-pg-ctl">

<docinfo>

<date>2000-11-25</date>

<date>2001-02-08</date>

</docinfo>

<refmeta>

<arg choice="plain">start</arg>

<arg>-w</arg>

<arg>-D <replaceable>datadir</replaceable></arg>

<arg>-p <replaceable>path</replaceable></arg>

<arg>-l <replaceable>filename</replaceable></arg>

<arg>-o <replaceable>options</replaceable></arg>

<arg>-p <replaceable>path</replaceable></arg>

<sbr>

<command>pg_ctl</command>

<arg choice="plain">stop</arg>

<arg>-w</arg>

<arg>-W</arg>

<arg>-D <replaceable>datadir</replaceable></arg>

<arg>-m

<group choice="plain">

<title>Description</title>

<para>

<application>pg_ctl</application> is a utility for starting,

stopping, or restarting the <xref linkend="app-postmaster">, or

displaying the status of a running postmaster.

stopping, or restarting <xref linkend="app-postmaster">, the

<productname>PostgreSQL</productname> backend server, or displaying

the status of a running postmaster. Although the postmaster can be

started manually, <application>pg_ctl</application> encapulates

tasks such as redirecting log output, properly detaching from the

terminal and process group, and additionally provides an option for

controlled shut down.

</para>

<para>

In <option>start</option> mode, a new postmaster is launched. The

server is started in the background, the standard input attached to

<filename>/dev/null</filename>. The standard output and standard

error are either appended to a log file, if the <option>-l</option>

option is used, or are redirected to

<application>pg_ctl</application>'s standard output (not standard

error). If no log file is chosen, the standard output of

<application>pg_ctl</application> should be redirected to a file or

piped to another process, for example a log rotating program,

otherwise the postmaster will write its output the the controlling

terminal (from the background) and will not leave the shell's

process group.

</para>

<para>

In <option>stop</option> mode, the postmaster that is running on

the specified data directory is shut down. Three different

shutdown methods can be selected with the <option>-m</option>

option: <quote>Smart</quote> mode waits for all the clients to

disconnect. This is the default. <quote>Fast</quote> mode does

not wait for clients to disconnect. All active transactions will

be rolled back. <quote>Immediate</quote> mode will abort without

complete shutdown. This will lead to a recovery run on restart.

By the default, stop mode waits for the shutdown to complete.

</para>

<para>

<option>restart</option> mode effectively executes a stop followed

by a start. This allows the changing of postmaster command line

options.

</para>

<para>

<option>status</option> mode checks whether a postmaster is running

and if so displays the <acronym>PID</acronym> and the command line

options that were used to invoke it.

</para>

<refsect2 id="app-pg-ctl-options">

<variablelist>

<varlistentry>

<term>-w</term>

<term>-D <replaceable class="parameter">datadir</replaceable></term>

<listitem>

<para>

Wait for the database server to come up, by watching for

creation of the pid file

(<filename><replaceable>PGDATA</replaceable>/postmaster.pid</filename>).

Times out after 60 seconds.

Specifies the file system location of the database files. If

this is omitted, the environment variable

<envar>PGDATA</envar> is used.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>-D <replaceable class="parameter">datadir</replaceable></term>

<term>-l <replaceable class="parameter">filename</replaceable></term>

<listitem>

<para>

Specifies the file system location of the database files. If

this is omitted, the environment variable

<envar>PGDATA</envar> is used.

Append the server log output to

<replaceable>filename</replaceable>. If the file does not

exist, it is created. The umask is set to 077, so access to

the log file from other users is disallowed by default.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>-p <replaceable class="parameter">path</replaceable></term>

<term>-m <replaceable class="parameter">mode</replaceable></term>

<listitem>

<para>

Specifies the location of the <filename>postmaster</filename>

executable. By default the postmaster is taken from the same

directory as pg_ctl, or failing that, the hard-wired

installation directory. It is not necessary to use this

option unless you are doing something unusual and get errors

that the postmaster was not found.

Specifies the shutdown mode. <replaceable>mode</replaceable>

may be <literal>smart</literal>, <literal>fast</literal>, or

<literal>immediate</literal>, or the first letter of one of

these three.

</para>

</listitem>

</varlistentry>

</varlistentry>

<varlistentry>

<term>-m <replaceable class="parameter">mode</replaceable></term>

<listitem>

<para>

Specifies the shutdown mode.

<variablelist>

<varlistentry>

<term>smart</term>

<term>s</term>

<listitem>

<para>

Smart mode waits for all the clients to disconnect. This

is the default.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>fast</term>

<term>f</term>

<listitem>

<para>

Fast mode does not wait for clients to disconnect. All

active transactions will be rolled back.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>immediate</term>

<term>i</term>

<listitem>

<para>

Immediate mode will abort without complete shutdown. This

will lead to a recovery run on restart.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>start</term>

<listitem>

<para>

Start up <application>postmaster</application>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>stop</term>

<term>-p <replaceable class="parameter">path</replaceable></term>

<listitem>

<para>

Shut down <application>postmaster</application>.

Specifies the location of the <filename>postmaster</filename>

executable. By default the postmaster is taken from the same

directory as pg_ctl, or failing that, the hard-wired

installation directory. It is not necessary to use this

option unless you are doing something unusual and get errors

that the postmaster was not found.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>restart</term>

<term>-w</term>

<listitem>

<para>

Stopthe<application>postmaster</application>, if one is running,

and then start it again.

Wait forthestart or stutdown to complete. Times out after

60 seconds. This is the default for shutdowns.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term>status</term>

<term>-W</term>

<listitem>

<para>

Show the current state of <application>postmaster</application>.

Do not wait for start or shutdown to complete. This is the

default for starts and restarts.

</para>

</listitem>

</varlistentry>

<refsect1 id="R1-APP-PGCTL-2">

<title>Usage</title>

<title>Examples</title>

<refsect2 id="R2-APP-PGCTL-3">

<title>Starting the postmaster</title>

</screen>

stops postmaster. Using the <option>-m</option> switch allows one

to control <emphasis>how</emphasis> the backend shuts down.

<option>-w</option> waits for postmaster to shut down.

</para>

</refsect2>

</para>

</refsect2>

</refsect1>

<refsect1>

<title>Bugs</title>

<para>

Waiting for complete start is not a well-defined operation and may

fail if access control is set up in way that a local client cannot

connect without manual interaction. It should be avoided.

</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>

</para>

</refsect1>

</refentry>

<!-- Keep this comment at the end of the file