diff options
Diffstat (limited to 'doc/src/sgml/ref/pg_ctl-ref.sgml')
| -rw-r--r-- | doc/src/sgml/ref/pg_ctl-ref.sgml | 182 |
1 files changed, 98 insertions, 84 deletions
diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index 7b628ead937..617a070d6e4 100644 --- a/doc/src/sgml/ref/pg_ctl-ref.sgml +++ b/doc/src/sgml/ref/pg_ctl-ref.sgml @@ -1,11 +1,11 @@ <!-- -$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> @@ -25,12 +25,13 @@ Postgres documentation <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"> @@ -64,8 +65,52 @@ Postgres documentation <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"> @@ -74,38 +119,36 @@ Postgres documentation <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> @@ -125,82 +168,35 @@ Postgres documentation </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> - Stop the <application>postmaster</application>, if one is running, - and then start it again. + Wait for the start 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> @@ -223,7 +219,7 @@ Postgres documentation <refsect1 id="R1-APP-PGCTL-2"> - <title>Usage</title> + <title>Examples</title> <refsect2 id="R2-APP-PGCTL-3"> <title>Starting the postmaster</title> @@ -260,7 +256,6 @@ Postgres documentation </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> @@ -312,6 +307,25 @@ Command line was: </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 |