Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 088c0b9

Browse files
peterepetere
committed
Make -w the default for shut down, add -W option to specify no wait.
Add -l option to name log file. Set umask to 077. Proper file descriptor redirection to allow postmaster to detach from shell's process group. Add -s option to turn off informational messages.
1 parent e58775e commit 088c0b9

File tree

2 files changed

+240
-158
lines changed

2 files changed

+240
-158
lines changed

‎doc/src/sgml/ref/pg_ctl-ref.sgml

Lines changed: 98 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
<!--
2-
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.5 2000/12/25 23:15:26 petere Exp $
2+
$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.6 2001/02/08 19:39:24 petere Exp $
33
Postgres documentation
44
-->
55

66
<refentry id="app-pg-ctl">
77
<docinfo>
8-
<date>2000-11-25</date>
8+
<date>2001-02-08</date>
99
</docinfo>
1010

1111
<refmeta>
@@ -25,12 +25,13 @@ Postgres documentation
2525
<arg choice="plain">start</arg>
2626
<arg>-w</arg>
2727
<arg>-D <replaceable>datadir</replaceable></arg>
28-
<arg>-p <replaceable>path</replaceable></arg>
28+
<arg>-l <replaceable>filename</replaceable></arg>
2929
<arg>-o <replaceable>options</replaceable></arg>
30+
<arg>-p <replaceable>path</replaceable></arg>
3031
<sbr>
3132
<command>pg_ctl</command>
3233
<arg choice="plain">stop</arg>
33-
<arg>-w</arg>
34+
<arg>-W</arg>
3435
<arg>-D <replaceable>datadir</replaceable></arg>
3536
<arg>-m
3637
<group choice="plain">
@@ -64,8 +65,52 @@ Postgres documentation
6465
<title>Description</title>
6566
<para>
6667
<application>pg_ctl</application> is a utility for starting,
67-
stopping, or restarting the <xref linkend="app-postmaster">, or
68-
displaying the status of a running postmaster.
68+
stopping, or restarting <xref linkend="app-postmaster">, the
69+
<productname>PostgreSQL</productname> backend server, or displaying
70+
the status of a running postmaster. Although the postmaster can be
71+
started manually, <application>pg_ctl</application> encapulates
72+
tasks such as redirecting log output, properly detaching from the
73+
terminal and process group, and additionally provides an option for
74+
controlled shut down.
75+
</para>
76+
77+
<para>
78+
In <option>start</option> mode, a new postmaster is launched. The
79+
server is started in the background, the standard input attached to
80+
<filename>/dev/null</filename>. The standard output and standard
81+
error are either appended to a log file, if the <option>-l</option>
82+
option is used, or are redirected to
83+
<application>pg_ctl</application>'s standard output (not standard
84+
error). If no log file is chosen, the standard output of
85+
<application>pg_ctl</application> should be redirected to a file or
86+
piped to another process, for example a log rotating program,
87+
otherwise the postmaster will write its output the the controlling
88+
terminal (from the background) and will not leave the shell's
89+
process group.
90+
</para>
91+
92+
<para>
93+
In <option>stop</option> mode, the postmaster that is running on
94+
the specified data directory is shut down. Three different
95+
shutdown methods can be selected with the <option>-m</option>
96+
option: <quote>Smart</quote> mode waits for all the clients to
97+
disconnect. This is the default. <quote>Fast</quote> mode does
98+
not wait for clients to disconnect. All active transactions will
99+
be rolled back. <quote>Immediate</quote> mode will abort without
100+
complete shutdown. This will lead to a recovery run on restart.
101+
By the default, stop mode waits for the shutdown to complete.
102+
</para>
103+
104+
<para>
105+
<option>restart</option> mode effectively executes a stop followed
106+
by a start. This allows the changing of postmaster command line
107+
options.
108+
</para>
109+
110+
<para>
111+
<option>status</option> mode checks whether a postmaster is running
112+
and if so displays the <acronym>PID</acronym> and the command line
113+
options that were used to invoke it.
69114
</para>
70115

71116
<refsect2 id="app-pg-ctl-options">
@@ -74,38 +119,36 @@ Postgres documentation
74119

75120
<variablelist>
76121
<varlistentry>
77-
<term>-w</term>
122+
<term>-D <replaceable class="parameter">datadir</replaceable></term>
78123
<listitem>
79124
<para>
80-
Wait for the database server to come up, by watching for
81-
creation of the pid file
82-
(<filename><replaceable>PGDATA</replaceable>/postmaster.pid</filename>).
83-
Times out after 60 seconds.
125+
Specifies the file system location of the database files. If
126+
this is omitted, the environment variable
127+
<envar>PGDATA</envar> is used.
84128
</para>
85129
</listitem>
86130
</varlistentry>
87131

88132
<varlistentry>
89-
<term>-D <replaceable class="parameter">datadir</replaceable></term>
133+
<term>-l <replaceable class="parameter">filename</replaceable></term>
90134
<listitem>
91135
<para>
92-
Specifies the file system location of the database files. If
93-
this is omitted, the environment variable
94-
<envar>PGDATA</envar> is used.
136+
Append the server log output to
137+
<replaceable>filename</replaceable>. If the file does not
138+
exist, it is created. The umask is set to 077, so access to
139+
the log file from other users is disallowed by default.
95140
</para>
96141
</listitem>
97142
</varlistentry>
98143

99144
<varlistentry>
100-
<term>-p <replaceable class="parameter">path</replaceable></term>
145+
<term>-m <replaceable class="parameter">mode</replaceable></term>
101146
<listitem>
102147
<para>
103-
Specifies the location of the <filename>postmaster</filename>
104-
executable. By default the postmaster is taken from the same
105-
directory as pg_ctl, or failing that, the hard-wired
106-
installation directory. It is not necessary to use this
107-
option unless you are doing something unusual and get errors
108-
that the postmaster was not found.
148+
Specifies the shutdown mode. <replaceable>mode</replaceable>
149+
may be <literal>smart</literal>, <literal>fast</literal>, or
150+
<literal>immediate</literal>, or the first letter of one of
151+
these three.
109152
</para>
110153
</listitem>
111154
</varlistentry>
@@ -125,82 +168,35 @@ Postgres documentation
125168
</varlistentry>
126169

127170
<varlistentry>
128-
<term>-m <replaceable class="parameter">mode</replaceable></term>
129-
<listitem>
130-
<para>
131-
Specifies the shutdown mode.
132-
133-
<variablelist>
134-
<varlistentry>
135-
<term>smart</term>
136-
<term>s</term>
137-
<listitem>
138-
<para>
139-
Smart mode waits for all the clients to disconnect. This
140-
is the default.
141-
</para>
142-
</listitem>
143-
</varlistentry>
144-
145-
<varlistentry>
146-
<term>fast</term>
147-
<term>f</term>
148-
<listitem>
149-
<para>
150-
Fast mode does not wait for clients to disconnect. All
151-
active transactions will be rolled back.
152-
</para>
153-
</listitem>
154-
</varlistentry>
155-
156-
<varlistentry>
157-
<term>immediate</term>
158-
<term>i</term>
159-
<listitem>
160-
<para>
161-
Immediate mode will abort without complete shutdown. This
162-
will lead to a recovery run on restart.
163-
</para>
164-
</listitem>
165-
</varlistentry>
166-
</variablelist>
167-
</para>
168-
</listitem>
169-
</varlistentry>
170-
171-
<varlistentry>
172-
<term>start</term>
173-
<listitem>
174-
<para>
175-
Start up <application>postmaster</application>.
176-
</para>
177-
</listitem>
178-
</varlistentry>
179-
180-
<varlistentry>
181-
<term>stop</term>
171+
<term>-p <replaceable class="parameter">path</replaceable></term>
182172
<listitem>
183173
<para>
184-
Shut down <application>postmaster</application>.
174+
Specifies the location of the <filename>postmaster</filename>
175+
executable. By default the postmaster is taken from the same
176+
directory as pg_ctl, or failing that, the hard-wired
177+
installation directory. It is not necessary to use this
178+
option unless you are doing something unusual and get errors
179+
that the postmaster was not found.
185180
</para>
186181
</listitem>
187182
</varlistentry>
188183

189184
<varlistentry>
190-
<term>restart</term>
185+
<term>-w</term>
191186
<listitem>
192187
<para>
193-
Stop the <application>postmaster</application>, if one is running,
194-
and then start it again.
188+
Wait for the start or stutdown to complete. Times out after
189+
60 seconds. This is the default for shutdowns.
195190
</para>
196191
</listitem>
197192
</varlistentry>
198193

199194
<varlistentry>
200-
<term>status</term>
195+
<term>-W</term>
201196
<listitem>
202197
<para>
203-
Show the current state of <application>postmaster</application>.
198+
Do not wait for start or shutdown to complete. This is the
199+
default for starts and restarts.
204200
</para>
205201
</listitem>
206202
</varlistentry>
@@ -223,7 +219,7 @@ Postgres documentation
223219

224220

225221
<refsect1 id="R1-APP-PGCTL-2">
226-
<title>Usage</title>
222+
<title>Examples</title>
227223

228224
<refsect2 id="R2-APP-PGCTL-3">
229225
<title>Starting the postmaster</title>
@@ -260,7 +256,6 @@ Postgres documentation
260256
</screen>
261257
stops postmaster. Using the <option>-m</option> switch allows one
262258
to control <emphasis>how</emphasis> the backend shuts down.
263-
<option>-w</option> waits for postmaster to shut down.
264259
</para>
265260
</refsect2>
266261

@@ -312,6 +307,25 @@ Command line was:
312307
</para>
313308
</refsect2>
314309
</refsect1>
310+
311+
<refsect1>
312+
<title>Bugs</title>
313+
314+
<para>
315+
Waiting for complete start is not a well-defined operation and may
316+
fail if access control is set up in way that a local client cannot
317+
connect without manual interaction. It should be avoided.
318+
</para>
319+
</refsect1>
320+
321+
<refsect1>
322+
<title>See Also</title>
323+
324+
<para>
325+
<xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
326+
</para>
327+
</refsect1>
328+
315329
</refentry>
316330

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

0 commit comments

Comments
 (0)