pg_ctl-ref.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.32 2005/11/04 23:14:02 petere 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>

 <indexterm zone="app-pg-ctl">
  <primary>pg_ctl</primary>
 </indexterm>

 <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>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">kill</arg>
   <arg><replaceable>signal_name</replaceable></arg>
   <arg><replaceable>process_id</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">register</arg>
   <arg>-N <replaceable>servicename</replaceable></arg>
   <arg>-U <replaceable>username</replaceable></arg>
   <arg>-P <replaceable>password</replaceable></arg>
   <arg>-D <replaceable>datadir</replaceable></arg>
   <arg>-w</arg>
   <arg>-o <replaceable>options</replaceable></arg>
   <sbr>
   <command>pg_ctl</command>
   <arg choice="plain">unregister</arg>
   <arg>-N <replaceable>servicename</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 the <productname>PostgreSQL</productname>
   backend server (<xref linkend="app-postmaster">), or displaying the
   status of a running server.  Although the server 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 server 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 such as a log rotating program
   like <application>rotatelogs</>; otherwise the <command>postmaster</command> 
   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 server 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
   server 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 changing the <command>postmaster</command>
   command-line options.
  </para>

  <para>
   <option>reload</option> mode simply sends the
   <command>postmaster</command> process 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 server is running in
   the specified data directory. If it is, the <acronym>PID</acronym>
   and the command line options that were used to invoke it are
   displayed.
  </para>

  <para>
   <option>kill</option> mode allows you to send a signal to a specified
    process.  This is particularly valuable for <productname>Microsoft Windows</>
    which does not have a <application>kill</> command.  Use 
    <literal>--help</> to see a list of supported signal names.
  </para>

  <para>
   <option>register</option> mode allows you to register a system service
   on <productname>Microsoft Windows</>.
  </para>

  <para>
   <option>unregister</option> mode allows you to unregister a system service
   on <productname>Microsoft Windows</>, previously registered with the
   <option>register</option> command.
  </para>
 </refsect1>

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

  <para>

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

     <varlistentry>
      <term><option>-p <replaceable class="parameter">path</replaceable></option></term>
      <listitem>
       <para>
	Specifies the location of the <filename>postmaster</filename>
	executable.  By default the <filename>postmaster</filename> executable 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 <filename>postmaster</filename> executable was not found.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-s</option></term>
      <listitem>
       <para>
        Only print errors, no informational messages.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><option>-w</option></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 <application>psql</>. If the environment variable 
        <envar>PGPORT</envar> 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). When waiting, <command>pg_ctl</command> will
        return an accurate exit code based on the success of the startup 
	or shutdown.
       </para>
      </listitem>
     </varlistentry>