Skip to content

P
Postgres FD Implementation
Commit 8bcb31ad authored by Tom Lane's avatar Tom Lane
Browse files
Options

Sync pg_ctl documentation and usage message with reality. 

Commit 05cd12ed ("pg_ctl: Change default to wait for all actions")
was a tad sloppy about updating the documentation to match.  The
documentation was also sorely in need of a copy-editing pass, having
been adjusted at different times by different people who took little
care to maintain consistency of style.
parent 594b526b
Show whitespace changes
Inline Side-by-side
Showing with 123 additions and 111 deletions
doc/src/sgml/ref/pg_ctl-ref.sgml
View file @ 8bcb31ad
...@@ -23,19 +23,19 @@ PostgreSQL documentation ...@@ -23,19 +23,19 @@ PostgreSQL documentation
<cmdsynopsis> <cmdsynopsis>
<command>pg_ctl</command> <command>pg_ctl</command>
<arg choice="plain"><option>init[db]</option></arg> <arg choice="plain"><option>init[db]</option></arg>
<arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-o</option> <replaceable>initdb-options</replaceable></arg> <arg choice="opt"><option>-o</option> <replaceable>initdb-options</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
<cmdsynopsis> <cmdsynopsis>
<command>pg_ctl</command> <command>pg_ctl</command>
<arg choice="plain"><option>start</option></arg> <arg choice="plain"><option>start</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-l</option> <replaceable>filename</replaceable></arg>
<arg choice="opt"><option>-W</option></arg> <arg choice="opt"><option>-W</option></arg>
<arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
<arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-l</option> <replaceable>filename</replaceable></arg>
<arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg> <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
<arg choice="opt"><option>-p</option> <replaceable>path</replaceable></arg> <arg choice="opt"><option>-p</option> <replaceable>path</replaceable></arg>
<arg choice="opt"><option>-c</option></arg> <arg choice="opt"><option>-c</option></arg>
...@@ -44,9 +44,6 @@ PostgreSQL documentation ...@@ -44,9 +44,6 @@ PostgreSQL documentation
<cmdsynopsis> <cmdsynopsis>
<command>pg_ctl</command> <command>pg_ctl</command>
<arg choice="plain"><option>stop</option></arg> <arg choice="plain"><option>stop</option></arg>
<arg choice="opt"><option>-W</option></arg>
<arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
<arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-m</option> <arg choice="opt"><option>-m</option>
<group choice="plain"> <group choice="plain">
...@@ -55,16 +52,15 @@ PostgreSQL documentation ...@@ -55,16 +52,15 @@ PostgreSQL documentation
<arg choice="plain"><option>i[mmediate]</option></arg> <arg choice="plain"><option>i[mmediate]</option></arg>
</group> </group>
</arg> </arg>
<arg choice="opt"><option>-W</option></arg>
<arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
<arg choice="opt"><option>-s</option></arg>
</cmdsynopsis> </cmdsynopsis>
<cmdsynopsis> <cmdsynopsis>
<command>pg_ctl</command> <command>pg_ctl</command>
<arg choice="plain"><option>restart</option></arg> <arg choice="plain"><option>restart</option></arg>
<arg choice="opt"><option>-W</option></arg>
<arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
<arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-c</option></arg>
<arg choice="opt"><option>-m</option> <arg choice="opt"><option>-m</option>
<group choice="plain"> <group choice="plain">
<arg choice="plain"><option>s[mart]</option></arg> <arg choice="plain"><option>s[mart]</option></arg>
...@@ -72,14 +68,18 @@ PostgreSQL documentation ...@@ -72,14 +68,18 @@ PostgreSQL documentation
<arg choice="plain"><option>i[mmediate]</option></arg> <arg choice="plain"><option>i[mmediate]</option></arg>
</group> </group>
</arg> </arg>
<arg choice="opt"><option>-W</option></arg>
<arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
<arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg> <arg choice="opt"><option>-o</option> <replaceable>options</replaceable></arg>
<arg choice="opt"><option>-c</option></arg>
</cmdsynopsis> </cmdsynopsis>
<cmdsynopsis> <cmdsynopsis>
<command>pg_ctl</command> <command>pg_ctl</command>
<arg choice="plain"><option>reload</option></arg> <arg choice="plain"><option>reload</option></arg>
<arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg> <arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-s</option></arg>
</cmdsynopsis> </cmdsynopsis>
<cmdsynopsis> <cmdsynopsis>
...@@ -91,10 +91,10 @@ PostgreSQL documentation ...@@ -91,10 +91,10 @@ PostgreSQL documentation
<cmdsynopsis> <cmdsynopsis>
<command>pg_ctl</command> <command>pg_ctl</command>
<arg choice="plain"><option>promote</option></arg> <arg choice="plain"><option>promote</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-W</option></arg> <arg choice="opt"><option>-W</option></arg>
<arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
<arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-s</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
<cmdsynopsis> <cmdsynopsis>
...@@ -104,19 +104,22 @@ PostgreSQL documentation ...@@ -104,19 +104,22 @@ PostgreSQL documentation
<arg choice="plain"><replaceable>process_id</replaceable></arg> <arg choice="plain"><replaceable>process_id</replaceable></arg>
</cmdsynopsis> </cmdsynopsis>
<para>On Microsoft Windows, also:</para>
<cmdsynopsis> <cmdsynopsis>
<command>pg_ctl</command> <command>pg_ctl</command>
<arg choice="plain"><option>register</option></arg> <arg choice="plain"><option>register</option></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-N</option> <replaceable>servicename</replaceable></arg> <arg choice="opt"><option>-N</option> <replaceable>servicename</replaceable></arg>
<arg choice="opt"><option>-U</option> <replaceable>username</replaceable></arg> <arg choice="opt"><option>-U</option> <replaceable>username</replaceable></arg>
<arg choice="opt"><option>-P</option> <replaceable>password</replaceable></arg> <arg choice="opt"><option>-P</option> <replaceable>password</replaceable></arg>
<arg choice="opt"><option>-D</option> <replaceable>datadir</replaceable></arg>
<arg choice="opt"><option>-S</option> <arg choice="opt"><option>-S</option>
<group choice="plain"> <group choice="plain">
<arg choice="plain"><option>a[uto]</option></arg> <arg choice="plain"><option>a[uto]</option></arg>
<arg choice="plain"><option>d[emand]</option></arg> <arg choice="plain"><option>d[emand]</option></arg>
</group> </group>
</arg> </arg>
<arg choice="opt"><option>-e</option> <replaceable>source</replaceable></arg>
<arg choice="opt"><option>-W</option></arg> <arg choice="opt"><option>-W</option></arg>
<arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg> <arg choice="opt"><option>-t</option> <replaceable>seconds</replaceable></arg>
<arg choice="opt"><option>-s</option></arg> <arg choice="opt"><option>-s</option></arg>
...@@ -147,14 +150,14 @@ PostgreSQL documentation ...@@ -147,14 +150,14 @@ PostgreSQL documentation
<para> <para>
The <option>init</option> or <option>initdb</option> mode creates a new The <option>init</option> or <option>initdb</option> mode creates a new
<productname>PostgreSQL</productname> database cluster. A database <productname>PostgreSQL</productname> database cluster, that is,
cluster is a collection of databases that are managed by a single a collection of databases that will be managed by a single
server instance. This mode invokes the <command>initdb</command> server instance. This mode invokes the <command>initdb</command>
command. See <xref linkend="app-initdb"> for details. command. See <xref linkend="app-initdb"> for details.
</para> </para>
<para> <para>
In <option>start</option> mode, a new server is launched. The <option>start</option> mode launches a new server. The
server is started in the background, and its standard input is attached server is started in the background, and its standard input is attached
to <filename>/dev/null</filename> (or <literal>nul</> on Windows). to <filename>/dev/null</filename> (or <literal>nul</> on Windows).
On Unix-like systems, by default, the server's standard output and On Unix-like systems, by default, the server's standard output and
...@@ -172,8 +175,8 @@ PostgreSQL documentation ...@@ -172,8 +175,8 @@ PostgreSQL documentation
</para> </para>
<para> <para>
In <option>stop</option> mode, the server that is running in <option>stop</option> mode shuts down the server that is running in
the specified data directory is shut down. Three different the specified data directory. Three different
shutdown methods can be selected with the <option>-m</option> shutdown methods can be selected with the <option>-m</option>
option. <quote>Smart</quote> mode waits for all active option. <quote>Smart</quote> mode waits for all active
clients to disconnect and any online backup to finish. clients to disconnect and any online backup to finish.
...@@ -183,60 +186,63 @@ PostgreSQL documentation ...@@ -183,60 +186,63 @@ PostgreSQL documentation
will terminate an online backup in progress. All active transactions are will terminate an online backup in progress. All active transactions are
rolled back and clients are forcibly disconnected, then the rolled back and clients are forcibly disconnected, then the
server is shut down. <quote>Immediate</quote> mode will abort server is shut down. <quote>Immediate</quote> mode will abort
all server processes immediately, without a clean shutdown. all server processes immediately, without a clean shutdown. This choice
This will lead to a crash-recovery run on the next restart. will lead to a crash-recovery cycle during the next server start.
</para> </para>
<para> <para>
<option>restart</option> mode effectively executes a stop followed <option>restart</option> mode effectively executes a stop followed
by a start. This allows changing the <command>postgres</command> by a start. This allows changing the <command>postgres</command>
command-line options. <option>restart</option> might fail if command-line options, or changing configuration-file options that
relative paths specified were specified on the command-line during cannot be changed without restarting the server.
server start. If relative paths were used on the command line during server
start, <option>restart</option> might fail unless
<application>pg_ctl</application> is executed in the same current
directory as it was during server start.
</para> </para>
<para> <para>
<option>reload</option> mode simply sends the <option>reload</option> mode simply sends the
<command>postgres</command> process a <systemitem>SIGHUP</> <command>postgres</command> server process a <systemitem>SIGHUP</>
signal, causing it to reread its configuration files signal, causing it to reread its configuration files
(<filename>postgresql.conf</filename>, (<filename>postgresql.conf</filename>,
<filename>pg_hba.conf</filename>, etc.). This allows changing of <filename>pg_hba.conf</filename>, etc.). This allows changing
configuration-file options that do not require a complete restart configuration-file options that do not require a full server restart
to take effect. to take effect.
</para> </para>
<para> <para>
<option>status</option> mode checks whether a server is running in <option>status</option> mode checks whether a server is running in
the specified data directory. If it is, the <acronym>PID</acronym> the specified data directory. If it is, the server's <acronym>PID</acronym>
and the command line options that were used to invoke it are and the command line options that were used to invoke it are displayed.
displayed. If the server is not running, the process returns an If the server is not running, <application>pg_ctl</application> returns
exit status of 3. If an accessible data directory is not specified, an exit status of 3. If an accessible data directory is not
the process returns an exit status of 4. specified, <application>pg_ctl</application> returns an exit status of 4.
</para> </para>
<para> <para>
In <option>promote</option> mode, the standby server that is <option>promote</option> mode commands the standby server that is
running in the specified data directory is commanded to exit running in the specified data directory to end standby mode
recovery and begin read-write operations. and begin read-write operations.
</para> </para>
<para> <para>
<option>kill</option> mode allows you to send a signal to a specified <option>kill</option> mode sends a signal to a specified process.
process. This is particularly valuable for <productname>Microsoft Windows</> This is primarily valuable on <productname>Microsoft Windows</>
which does not have a <application>kill</> command. Use which does not have a built-in <application>kill</> command. Use
<literal>--help</> to see a list of supported signal names. <literal>--help</> to see a list of supported signal names.
</para> </para>
<para> <para>
<option>register</option> mode allows you to register a system service <option>register</option> mode registers the <productname>PostgreSQL</>
on <productname>Microsoft Windows</>. The <option>-S</option> option server as a system service on <productname>Microsoft Windows</>.
allows selection of service start type, either <quote>auto</quote> (start The <option>-S</option> option allows selection of service start type,
service automatically on system startup) or <quote>demand</quote> (start either <quote>auto</quote> (start service automatically on system startup)
service on demand). or <quote>demand</quote> (start service on demand).
</para> </para>
<para> <para>
<option>unregister</option> mode allows you to unregister a system service <option>unregister</option> mode unregisters a system service
on <productname>Microsoft Windows</>. This undoes the effects of the on <productname>Microsoft Windows</>. This undoes the effects of the
<option>register</option> command. <option>register</option> command.
</para> </para>
...@@ -249,7 +255,7 @@ PostgreSQL documentation ...@@ -249,7 +255,7 @@ PostgreSQL documentation
<varlistentry> <varlistentry>
<term><option>-c</option></term> <term><option>-c</option></term>
<term><option>--core-file</option></term> <term><option>--core-files</option></term>
<listitem> <listitem>
<para> <para>
Attempt to allow server crashes to produce core files, on platforms Attempt to allow server crashes to produce core files, on platforms
...@@ -267,7 +273,7 @@ PostgreSQL documentation ...@@ -267,7 +273,7 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies the file system location of the database configuration files. If Specifies the file system location of the database configuration files. If
this is omitted, the environment variable this option is omitted, the environment variable
<envar>PGDATA</envar> is used. <envar>PGDATA</envar> is used.
</para> </para>
</listitem> </listitem>
...@@ -294,7 +300,8 @@ PostgreSQL documentation ...@@ -294,7 +300,8 @@ PostgreSQL documentation
Specifies the shutdown mode. <replaceable>mode</replaceable> Specifies the shutdown mode. <replaceable>mode</replaceable>
can be <literal>smart</literal>, <literal>fast</literal>, or can be <literal>smart</literal>, <literal>fast</literal>, or
<literal>immediate</literal>, or the first letter of one of <literal>immediate</literal>, or the first letter of one of
these three. If this is omitted, <literal>fast</literal> is used. these three. If this option is omitted, <literal>fast</literal> is
the default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -305,12 +312,13 @@ PostgreSQL documentation ...@@ -305,12 +312,13 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
Specifies options to be passed directly to the Specifies options to be passed directly to the
<command>postgres</command> command; multiple <command>postgres</command> command.
option invocations are appended. <option>-o</> can be specified multiple times, with all the given
options being passed through.
</para> </para>
<para> <para>
The options should usually be surrounded by single or double The <replaceable>options</> should usually be surrounded by single or
quotes to ensure that they are passed through as a group. double quotes to ensure that they are passed through as a group.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -322,10 +330,12 @@ PostgreSQL documentation ...@@ -322,10 +330,12 @@ PostgreSQL documentation
<para> <para>
Specifies options to be passed directly to the Specifies options to be passed directly to the
<command>initdb</command> command. <command>initdb</command> command.
<option>-o</> can be specified multiple times, with all the given
options being passed through.
</para> </para>
<para> <para>
The options should usually be surrounded by single or double The <replaceable>options</> should usually be surrounded by single or
quotes to ensure that they are passed through as a group. double quotes to ensure that they are passed through as a group.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -361,14 +371,14 @@ PostgreSQL documentation ...@@ -361,14 +371,14 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><option>-t</option></term> <term><option>-t <replaceable class="parameter">seconds</replaceable></option></term>
<term><option>--timeout</option></term> <term><option>--timeout=<replaceable class="parameter">seconds</replaceable></option></term>
<listitem> <listitem>
<para> <para>
The maximum number of seconds to wait when waiting for an operation Specifies the maximum number of seconds to wait when waiting for an
to complete (see option <option>-w</option>). Defaults to the value of the operation to complete (see option <option>-w</option>). Defaults to
<envar>PGCTLTIMEOUT</> environment variable or, if not set, to 60 the value of the <envar>PGCTLTIMEOUT</> environment variable or, if
seconds. not set, to 60 seconds.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -388,7 +398,7 @@ PostgreSQL documentation ...@@ -388,7 +398,7 @@ PostgreSQL documentation
<term><option>--wait</option></term> <term><option>--wait</option></term>
<listitem> <listitem>
<para> <para>
Wait for an operation to complete. This is supported for the Wait for the operation to complete. This is supported for the
modes <literal>start</literal>, <literal>stop</literal>, modes <literal>start</literal>, <literal>stop</literal>,
<literal>restart</literal>, <literal>promote</literal>, <literal>restart</literal>, <literal>promote</literal>,
and <literal>register</literal>, and is the default for those modes. and <literal>register</literal>, and is the default for those modes.
...@@ -399,7 +409,6 @@ PostgreSQL documentation ...@@ -399,7 +409,6 @@ PostgreSQL documentation
attempts to connect to the server. attempts to connect to the server.
When waiting for shutdown, <command>pg_ctl</command> waits for When waiting for shutdown, <command>pg_ctl</command> waits for
the server to remove its <acronym>PID</acronym> file. the server to remove its <acronym>PID</acronym> file.
This option allows the entry of an <acronym>SSL</> passphrase on startup.
<command>pg_ctl</command> returns an exit code based on the <command>pg_ctl</command> returns an exit code based on the
success of the startup or shutdown. success of the startup or shutdown.
</para> </para>
...@@ -411,8 +420,8 @@ PostgreSQL documentation ...@@ -411,8 +420,8 @@ PostgreSQL documentation
<term><option>--no-wait</option></term> <term><option>--no-wait</option></term>
<listitem> <listitem>
<para> <para>
Do not wait for an operation to complete. This is the opposite of the Do not wait for the operation to complete. This is the opposite of
option <option>-w</option>. the option <option>-w</option>.
</para> </para>
<para> <para>
...@@ -441,6 +450,11 @@ PostgreSQL documentation ...@@ -441,6 +450,11 @@ PostgreSQL documentation
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<para>
If an option is specified that is valid, but not relevant to the selected
operating mode, <application>pg_ctl</application> ignores it.
</para>
<refsect2 id="app-pg-ctl-windows-options"> <refsect2 id="app-pg-ctl-windows-options">
<title>Options for Windows</title> <title>Options for Windows</title>
...@@ -452,11 +466,12 @@ PostgreSQL documentation ...@@ -452,11 +466,12 @@ PostgreSQL documentation
Name of the event source for <application>pg_ctl</application> to use Name of the event source for <application>pg_ctl</application> to use
for logging to the event log when running as a Windows service. The for logging to the event log when running as a Windows service. The
default is <literal>PostgreSQL</literal>. Note that this only controls default is <literal>PostgreSQL</literal>. Note that this only controls
the logging from <application>pg_ctl</application> itself; once messages sent from <application>pg_ctl</application> itself; once
started, the server will use the event source specified started, the server will use the event source specified
by <xref linkend="guc-event-source">. Should the server fail during by its <xref linkend="guc-event-source"> parameter. Should the server
early startup, it might also log using the default event fail very early in startup, before that parameter has been set,
source <literal>PostgreSQL</literal>. it might also log using the default event
source name <literal>PostgreSQL</literal>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -465,8 +480,9 @@ PostgreSQL documentation ...@@ -465,8 +480,9 @@ PostgreSQL documentation
<term><option>-N <replaceable class="parameter">servicename</replaceable></option></term> <term><option>-N <replaceable class="parameter">servicename</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Name of the system service to register. The name will be used Name of the system service to register. This name will be used
as both the service name and the display name. as both the service name and the display name.
The default is <literal>PostgreSQL</literal>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -475,7 +491,7 @@ PostgreSQL documentation ...@@ -475,7 +491,7 @@ PostgreSQL documentation
<term><option>-P <replaceable class="parameter">password</replaceable></option></term> <term><option>-P <replaceable class="parameter">password</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Password for the user to start the service. Password for the user to run the service as.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -484,10 +500,10 @@ PostgreSQL documentation ...@@ -484,10 +500,10 @@ PostgreSQL documentation
<term><option>-S <replaceable class="parameter">start-type</replaceable></option></term> <term><option>-S <replaceable class="parameter">start-type</replaceable></option></term>
<listitem> <listitem>
<para> <para>
Start type of the system service to register. start-type can Start type of the system service. <replaceable>start-type</> can
be <literal>auto</literal>, or <literal>demand</literal>, or be <literal>auto</literal>, or <literal>demand</literal>, or
the first letter of one of these two. If this is omitted, the first letter of one of these two. If this option is omitted,
<literal>auto</literal> is used. <literal>auto</literal> is the default.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -496,7 +512,7 @@ PostgreSQL documentation ...@@ -496,7 +512,7 @@ PostgreSQL documentation
<term><option>-U <replaceable class="parameter">username</replaceable></option></term> <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
<listitem> <listitem>
<para> <para>
User name for the user to start the service. For domain users, use the User name for the user to run the service as. For domain users, use the
format <literal>DOMAIN\username</literal>. format <literal>DOMAIN\username</literal>.
</para> </para>
</listitem> </listitem>
...@@ -534,12 +550,22 @@ PostgreSQL documentation ...@@ -534,12 +550,22 @@ PostgreSQL documentation
</variablelist> </variablelist>
<para>
Most <command>pg_ctl</command> modes require knowing the data directory
location; therefore, the <option>-D</> option is required
unless <envar>PGDATA</envar> is set.
</para>
<para> <para>
<command>pg_ctl</command>, like most other <productname>PostgreSQL</> <command>pg_ctl</command>, like most other <productname>PostgreSQL</>
utilities, utilities,
also uses the environment variables supported by <application>libpq</> also uses the environment variables supported by <application>libpq</>
(see <xref linkend="libpq-envars">). (see <xref linkend="libpq-envars">).
For additional server variables, see <xref linkend="app-postgres">. </para>
<para>
For additional variables that affect the server,
see <xref linkend="app-postgres">.
</para> </para>
</refsect1> </refsect1>
...@@ -553,9 +579,8 @@ PostgreSQL documentation ...@@ -553,9 +579,8 @@ PostgreSQL documentation
<listitem> <listitem>
<para> <para>
The existence of this file in the data directory is used to help <application>pg_ctl</application> examines this file in the data
<application>pg_ctl</application> determine if the server is directory to determine whether the server is currently running.
currently running.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
...@@ -584,13 +609,6 @@ PostgreSQL documentation ...@@ -584,13 +609,6 @@ PostgreSQL documentation
<refsect2 id="R2-APP-PGCTL-3"> <refsect2 id="R2-APP-PGCTL-3">
<title>Starting the Server</title> <title>Starting the Server</title>
<para>
To start the server:
<screen>
<prompt>$</prompt> <userinput>pg_ctl start</userinput>
</screen>
</para>
<para> <para>
To start the server, waiting until the server is To start the server, waiting until the server is
accepting connections: accepting connections:
...@@ -626,24 +644,17 @@ PostgreSQL documentation ...@@ -626,24 +644,17 @@ PostgreSQL documentation
<para> <para>
Restarting the server is almost equivalent to stopping the Restarting the server is almost equivalent to stopping the
server and starting it again, server and starting it again, except that by default,
except that <command>pg_ctl</command> saves and reuses the command line options that <command>pg_ctl</command> saves and reuses the command line options that
were passed to the previously running instance. To restart were passed to the previously-running instance. To restart
the server in the simplest form, use: the server using the same options as before, use:
<screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen>
</para>
<para>
To restart the server,
waiting for it to shut down and restart:
<screen> <screen>
<prompt>$</prompt> <userinput>pg_ctl restart</userinput> <prompt>$</prompt> <userinput>pg_ctl restart</userinput>
</screen> </screen>
</para> </para>
<para> <para>
But if <option>-o</> is specified, that replaces any previous options.
To restart using port 5433, disabling <function>fsync</> upon restart: To restart using port 5433, disabling <function>fsync</> upon restart:
<screen> <screen>
<prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput> <prompt>$</prompt> <userinput>pg_ctl -o "-F -p 5433" restart</userinput>
...@@ -663,7 +674,7 @@ pg_ctl: server is running (PID: 13718) ...@@ -663,7 +674,7 @@ pg_ctl: server is running (PID: 13718)
/usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128" /usr/local/pgsql/bin/postgres "-D" "/usr/local/pgsql/data" "-p" "5433" "-B" "128"
</computeroutput> </computeroutput>
</screen> </screen>
This is the command line that would be invoked in restart mode. The second line is the command that would be invoked in restart mode.
</para> </para>
</refsect2> </refsect2>
</refsect1> </refsect1>
......
src/bin/pg_ctl/pg_ctl.c
View file @ 8bcb31ad
...@@ -1932,18 +1932,19 @@ do_help(void) ...@@ -1932,18 +1932,19 @@ do_help(void)
{ {
printf(_("%s is a utility to initialize, start, stop, or control a PostgreSQL server.\n\n"), progname); printf(_("%s is a utility to initialize, start, stop, or control a PostgreSQL server.\n\n"), progname);
printf(_("Usage:\n")); printf(_("Usage:\n"));
printf(_(" %s init[db] [-D DATADIR] [-s] [-o \"OPTIONS\"]\n"), progname); printf(_(" %s init[db] [-D DATADIR] [-s] [-o OPTIONS]\n"), progname);
printf(_(" %s start [-w] [-t SECS] [-D DATADIR] [-s] [-l FILENAME] [-o \"OPTIONS\"]\n"), progname); printf(_(" %s start [-D DATADIR] [-l FILENAME] [-W] [-t SECS] [-s]\n"
printf(_(" %s stop [-W] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"), progname); " [-o OPTIONS] [-p PATH] [-c]\n"), progname);
printf(_(" %s restart [-w] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n" printf(_(" %s stop [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]\n"), progname);
" [-o \"OPTIONS\"]\n"), progname); printf(_(" %s restart [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]\n"
" [-o OPTIONS] [-c]\n"), progname);
printf(_(" %s reload [-D DATADIR] [-s]\n"), progname); printf(_(" %s reload [-D DATADIR] [-s]\n"), progname);
printf(_(" %s status [-D DATADIR]\n"), progname); printf(_(" %s status [-D DATADIR]\n"), progname);
printf(_(" %s promote [-w] [-t SECS] [-D DATADIR] [-s]\n"), progname); printf(_(" %s promote [-D DATADIR] [-W] [-t SECS] [-s]\n"), progname);
printf(_(" %s kill SIGNALNAME PID\n"), progname); printf(_(" %s kill SIGNALNAME PID\n"), progname);
#ifdef WIN32 #ifdef WIN32
printf(_(" %s register [-N SERVICENAME] [-U USERNAME] [-P PASSWORD] [-D DATADIR]\n" printf(_(" %s register [-D DATADIR] [-N SERVICENAME] [-U USERNAME] [-P PASSWORD]\n"
" [-S START-TYPE] [-w] [-t SECS] [-o \"OPTIONS\"]\n"), progname); " [-S START-TYPE] [-e SOURCE] [-W] [-t SECS] [-s] [-o OPTIONS]\n"), progname);
printf(_(" %s unregister [-N SERVICENAME]\n"), progname); printf(_(" %s unregister [-N SERVICENAME]\n"), progname);
#endif #endif
...@@ -1958,7 +1959,6 @@ do_help(void) ...@@ -1958,7 +1959,6 @@ do_help(void)
printf(_(" -w, --wait wait until operation completes (default)\n")); printf(_(" -w, --wait wait until operation completes (default)\n"));
printf(_(" -W, --no-wait do not wait until operation completes\n")); printf(_(" -W, --no-wait do not wait until operation completes\n"));
printf(_(" -?, --help show this help, then exit\n")); printf(_(" -?, --help show this help, then exit\n"));
printf(_("(The default is to wait for shutdown, but not for start or restart.)\n\n"));
printf(_("If the -D option is omitted, the environment variable PGDATA is used.\n")); printf(_("If the -D option is omitted, the environment variable PGDATA is used.\n"));
printf(_("\nOptions for start or restart:\n")); printf(_("\nOptions for start or restart:\n"));
...@@ -1976,7 +1976,7 @@ do_help(void) ...@@ -1976,7 +1976,7 @@ do_help(void)
printf(_("\nShutdown modes are:\n")); printf(_("\nShutdown modes are:\n"));
printf(_(" smart quit after all clients have disconnected\n")); printf(_(" smart quit after all clients have disconnected\n"));
printf(_(" fast quit directly, with proper shutdown\n")); printf(_(" fast quit directly, with proper shutdown (default)\n"));
printf(_(" immediate quit without complete shutdown; will lead to recovery on restart\n")); printf(_(" immediate quit without complete shutdown; will lead to recovery on restart\n"));
printf(_("\nAllowed signal names for kill:\n")); printf(_("\nAllowed signal names for kill:\n"));
...@@ -2242,7 +2242,8 @@ main(int argc, char **argv) ...@@ -2242,7 +2242,8 @@ main(int argc, char **argv)
/* process command-line options */ /* process command-line options */
while (optind < argc) while (optind < argc)
{ {
while ((c = getopt_long(argc, argv, "cD:e:l:m:N:o:p:P:sS:t:U:wW", long_options, &option_index)) != -1) while ((c = getopt_long(argc, argv, "cD:e:l:m:N:o:p:P:sS:t:U:wW",
long_options, &option_index)) != -1)
{ {
switch (c) switch (c)
{ {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment