Fix typo in SGML tags.

[postgresql] / doc / src / sgml / ref / pg_ctl-ref.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.20 2003/03/20 17:37:46 momjian Exp $
PostgreSQL documentation
-->

<refentry id="app-pg-ctl">
 <refmeta>
  <refentrytitle id="app-pg-ctl-title"><application>pg_ctl</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>pg_ctl</refname>
  <refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>pg_ctl</command>
   <arg choice="plain">start</arg>
   <arg>-w</arg>
   <arg>-s</arg>
   <arg>-D <replaceable>datadir</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>-s</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-m
     <group choice="plain">
       <arg>s[mart]</arg>
       <arg>f[ast]</arg>
       <arg>i[mmediate]</arg>
     </group>
   </arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">restart</arg>
   <arg>-w</arg>
   <arg>-s</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-m
     <group choice="plain">
       <arg>s[mart]</arg>
       <arg>f[ast]</arg>
       <arg>i[mmediate]</arg>
     </group>
   </arg>
   <arg>-o <replaceable>options</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">reload</arg>
   <arg>-s</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">status</arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
  </cmdsynopsis>
 </refsynopsisdiv>


 <refsect1 id="app-pg-ctl-description">
  <title>Description</title>
  <para>
   <application>pg_ctl</application> is a utility for starting,
   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> encapsulates
   tasks such as redirecting log output and properly detaching from the
   terminal and process group. It also provides convenient options for
   controlled shutdown.
  </para>

  <para>
   In <option>start</option> mode, a new postmaster is launched.  The
   server is started in the background, and standard input is 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 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 to 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 in
   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 are
   rolled back and clients are forcibly disconnected, then the
   database is shut down.  <quote>Immediate</quote> mode will abort
   all server processes without a clean shutdown.  This will lead to 
   a recovery run on restart.
  </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>reload</option> mode simply sends the postmaster a <systemitem>SIGHUP</> signal,
   causing it to reread its configuration files
   (<filename>postgresql.conf</filename>, <filename>pg_hba.conf</filename>,
   etc.).  This allows changing of configuration-file options that do not
   require a complete restart to take effect.
  </para>

  <para>
   <option>status</option> mode checks whether a postmaster is running. 
   If it is, the <acronym>PID</acronym> and the command line
   options that were used to invoke it are displayed.
  </para>
 </refsect1>

 <refsect1 id="app-pg-ctl-options">
  <title>Options</title>

  <para>

    <variablelist>
     <varlistentry>
      <term>-D <replaceable class="parameter">datadir</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.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-l <replaceable class="parameter">filename</replaceable></term>
      <listitem>
       <para>
        Append the server log output to
        <replaceable>filename</replaceable>.  If the file does not
        exist, it is created.  The <systemitem>umask</> is set to 077, so access to
        the log file from other users is disallowed by default.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-m <replaceable class="parameter">mode</replaceable></term>
      <listitem>
       <para>
        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>
      <term>-o <replaceable class="parameter">options</replaceable></term>
      <listitem>
       <para>
        Specifies options to be passed directly to
        <application>postmaster</application>.
       </para>
       <para>
        The parameters are usually surrounded by single or double
        quotes to ensure that they are passed through as a group.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-p <replaceable class="parameter">path</replaceable></term>
      <listitem>
       <para>
        Specifies the location of the <filename>postmaster</filename>
        executable.  By default the postmaster is taken from the same
        directory as <command>pg_ctl</command>, 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>-s</term>
      <listitem>
       <para>
        Only print errors, no informational messages.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-w</term>
      <listitem>
       <para>
        Wait for the start or shutdown to complete.  Times out after
        60 seconds.  This is the default for shutdowns. A successful 
        shutdown is indicated by removal of the <acronym>PID</acronym> 
        file. For starting up, a successful <command>psql -l</command> 
        indicates success. <command>pg_ctl</command> will attempt to 
        use the proper port for psql. If the environment variable 
        PGPORT exists, that is used. Otherwise, it will see if a port 
        has been set in the <filename>postgresql.conf</filename> file. 
        If neither of those is used, it will use the default port that 
        <productname>PostgreSQL</productname> was compiled with 
        (5432 by default).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>-W</term>
      <listitem>
       <para>
        Do not wait for start or shutdown to complete.  This is the
        default for starts and restarts.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
 </refsect1>


 <refsect1>
  <title>Environment</title>

  <variablelist>
   <varlistentry>
    <term><envar>PGDATA</envar></term>

    <listitem>
     <para>
      Default data directory location.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><envar>PGPORT</envar></term>

    <listitem>
     <para>
      Default port for <xref linkend="app-psql"> (used by the -w option).
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   For others, see <xref linkend="app-postmaster">.
  </para>
 </refsect1>


 <refsect1>
  <title>Files</title>

  <variablelist>
   <varlistentry>
    <term><filename>postmaster.pid</filename></term>

    <listitem>
     <para>The existence of this file in the data directory is used to help 
           <application>pg_ctl</application> determine if the server is 
           currently running or not.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><filename>postmaster.opts.default</filename></term>

    <listitem>
     <para>If this file exists in the data directory, 
      <application>pg_ctl</application> (in <option>start</option> mode) 
      will pass the contents of the file as options to the 
      <application>postmaster</application>, unless overridden 
      by the <option>-o</option> option.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><filename>postmaster.opts</filename></term>

    <listitem>
     <para>If this file exists in the data directory,
      <application>pg_ctl</application> (in <option>restart</option> mode) 
      will pass the contents of the file as options to the 
      <application>postmaster</application>, unless overridden 
      by the <option>-o</option> option. The contents of this file 
      are also displayed in <option>status</option> mode.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><filename>postgresql.conf</filename></term>

    <listitem>
     <para>This file, located in the data directory, is parsed to 
      find the proper port to send to the 
      <application>psql</application> when the <option>-w</option> 
      is given in <option>start</option> mode.      
     </para>
    </listitem>
   </varlistentry>

  </variablelist>
 </refsect1>


 <refsect1>
  <title>Notes</title>

  <para>
   Waiting for complete start is not a well-defined operation and may
   fail if access control is set up so that a local client cannot
   connect without manual interaction (e.g. password authentication).
  </para>
 </refsect1>


 <refsect1 id="R1-APP-PGCTL-2">
  <title>Examples</title>

  <refsect2 id="R2-APP-PGCTL-3">
   <title>Starting the postmaster</title>

   <para>
    To start up a <application>postmaster</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
   </para>

   <para>
    An example of starting the <application>postmaster</application>,
    blocking until the postmaster comes up is:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w start</userinput>
</screen>
   </para>

   <para>
    For a <application>postmaster</application> using port 5433, and
    running without <function>fsync</function>, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" start</userinput>
</screen>
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-4">
   <title>Stopping the postmaster</title>
   <para>
<screen>
<prompt>$</prompt> <userinput>pg_ctl stop</userinput>
</screen>
    stops the postmaster. Using the <option>-m</option> switch allows one
    to control <emphasis>how</emphasis> the backend shuts down.
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-5">
   <title>Restarting the postmaster</title>

   <para>
    This is almost equivalent to stopping the
    <application>postmaster</application> and starting it again
    except that <command>pg_ctl</command> saves and reuses the command line options that
    were passed to the previously running instance.  To restart
    the <application>postmaster</application> in the simplest form:
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
   </para>

   <para>
    To restart <application>postmaster</application>,
    waiting for it to shut down and to come up:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -w restart</userinput>
</screen>
   </para>

   <para>
    To restart using port 5433 and disabling <function>fsync</> after restarting:
<screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
</screen>
   </para>
  </refsect2>

  <refsect2 id="R2-APP-PGCTL-6">
   <title>Showing postmaster status</title>

   <para>
    Here is a sample status output from
    <application>pg_ctl</application>:
<screen>
<prompt>$</prompt> <userinput>pg_ctl status</userinput>
<computeroutput>
pg_ctl: postmaster is running (pid: 13718)
Command line was:
/usr/local/pgsql/bin/postmaster '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'
</computeroutput>
</screen>
    This is the command line that would be invoked in restart mode.
   </para>
  </refsect2>
 </refsect1>


 <refsect1>
  <title>See Also</title>

  <para>
   <xref linkend="app-postmaster">, &cite-admin;
  </para>
 </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:
-->