I have written a man page for pg_ctl. I will appreciate if someone
would give me comments on it including grammatical corrections.
--
Tatsuo Ishii

NAME

pg_ctl - starts/stops/restarts postmaster

SYNOPSIS

pg_ctl [-w][-D database_dir][-p path_to_postmaster][-o "postmaster_opts"] start
pg_ctl [-w][-D database_dir][-m s[mart]|f[ast]|i[mmediate]] stop
pg_ctl [-w][-D database_dir][-m s[mart]|f[ast]|i[mmediate]][-o "postmaster_opts"] restart
pg_ctl [-D database_dir] status

DESCRIPTION

pg_ctl is a utility for starting, stopping or restarting postmaster.

Starting postmaster

To start postmaster:

pg_ctl start

If -w is supplied, pg_ctl waits for the database server comes up,
checking the pid file (PGDATA/postmaster.pid) gets created, for up to
60 seconds.

Parameters to invoke postmaster are taken from following sources:

Path to postmaster: found in the command search path
Database directory: PGDATA environment variable
Other parameters: PGDATA/postmaster.opts.default

postmaster.opts.default contains parameters for postmaster. With a
default installation, it has a line "-S." So "pg_ctl start" implies:

postmaster -S

Note that postmaster.opts.default is installed by initdb from
lib/postmaster.opts.default.sample under the PostgreSQL installation
directory (lib/postmaster.opts.default.sample is copied from
src/bin/pg_ctl/postmaster.opts.default.sample while installing
PostgreSQL).

To override default parameters you can use -D, -p and -o option.

-D database_dir
	specifies the database directory

-p path_to_postmaster
	specifies the path to postmaster

-o "postmaster_opts"
	specifies any parameter for postmaster

Examples:

# blocks until postmaster comes up
pg_ctl -w start

# specifies postmaster path
pg_ctl -p /usr/local/pgsq/bin/postmaster start

# uses port 5433 and disables fsync
pg_ctl -o "-o -F -p 5433" start

Stopping postmaster

pg_ctl stop

stops postmaster.

There are several options for the stopping mode.

-w
	waits for postmaster shutting down

-m
       specifies the shutdown mode. s[mart] mode waits for all
       the clients get logged out. This is the default.
       f[ast] mode sends SIGTERM to the backends, that means
       active transactions get rollback. i[mmediate] mode sends SIGUSR1
       to the backends and let them abort. In this case, database recovery
       will be neccessary on the next startup.


Restarting postmaster

This is almost equivalent to stopping postmaster then starting it
again except that the parameters for postmaster used before stopping
it would be used too. This is done by saving them in
PGDATA/postmaster.opts file. -w, -D, -m, and -o can also be used in
the restarting mode and they have same meanings as described above.

Examples:

# restarting postmaster in the simplest form
pg_ctl restart

# waiting for postmaster shutdown and waiting for postmaster coming up
pg_ctl -w restart

# uses port 5433 and disables fsync next time
pg_ctl -o "-o -F -p 5433" restart

Getting status from postmaster

To get status information from postmaster:

pg_ctl status

Followings are sample outputs from pg_ctl.

pg_ctl: postmaster is running (pid: 13718)
options are:
/usr/local/src/pgsql/current/bin/postmaster
-p 5433
-D /usr/local/src/pgsql/current/data
-B 64
-b /usr/local/src/pgsql/current/bin/postgres
-N 32
-o '-F'


Sun, 06 Feb 2000 12:49:58 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
pg_ctl man page
> I have written a man page for pg_ctl. I will appreciate if someone
> would give me comments on it including grammatical corrections.

I assume that this is intended for the main documentation set? Then
I'll be happy to convert this to sgml markup if you haven't done so or
do not know how. Also, I can make small changes to grammar etc at that
time.

You probably weren't asking about this, but...

The switch options "smart", "fast", and "immediate" are imho a bit too
general. I would suggest that "wait", "stop", and "abort" (or
something similar) might be better and more direct terms which would
come to mind for an admin. Though I see that you also have the concept
of "wait" wrt pg_ctl and the postmaster, to allow pg_ctl to return
immediately before the effects of the commands are seen. So maybe
"asychronous" or something similar could be applied to the
pg_ctl/postmaster relationship, leaving the other terms for the
pg_ctl/client relationship.

I would also suggest dropping "-m <opt>" style switches in favor of
specific flags, with the last flag specified taking precedence. I'm
not aware of other utilities having quite that same style.

                      - Thomas

> NAME
> pg_ctl - starts/stops/restarts postmaster
> 
> SYNOPSIS
> 
> pg_ctl [-w][-D database_dir][-p path_to_postmaster][-o "postmaster_opts"] start
> pg_ctl [-w][-D database_dir][-m s[mart]|f[ast]|i[mmediate]] stop
> pg_ctl [-w][-D database_dir][-m s[mart]|f[ast]|i[mmediate]][-o "postmaster_opts"] restart
> pg_ctl [-D database_dir] status
> 
> DESCRIPTION
> 
> pg_ctl is a utility for starting, stopping or restarting postmaster.
> 
> Starting postmaster
> 
> To start postmaster:
> 
> pg_ctl start
> 
> If -w is supplied, pg_ctl waits for the database server comes up,
> checking the pid file (PGDATA/postmaster.pid) gets created, for up to
> 60 seconds.
> 
> Parameters to invoke postmaster are taken from following sources:
> 
> Path to postmaster: found in the command search path
> Database directory: PGDATA environment variable
> Other parameters: PGDATA/postmaster.opts.default
> 
> postmaster.opts.default contains parameters for postmaster. With a
> default installation, it has a line "-S." So "pg_ctl start" implies:
> 
> postmaster -S
> 
> Note that postmaster.opts.default is installed by initdb from
> lib/postmaster.opts.default.sample under the PostgreSQL installation
> directory (lib/postmaster.opts.default.sample is copied from
> src/bin/pg_ctl/postmaster.opts.default.sample while installing
> PostgreSQL).
> 
> To override default parameters you can use -D, -p and -o option.
> 
> -D database_dir
>         specifies the database directory
> 
> -p path_to_postmaster
>         specifies the path to postmaster
> 
> -o "postmaster_opts"
>         specifies any parameter for postmaster
> 
> Examples:
> 
> # blocks until postmaster comes up
> pg_ctl -w start
> 
> # specifies postmaster path
> pg_ctl -p /usr/local/pgsq/bin/postmaster start
> 
> # uses port 5433 and disables fsync
> pg_ctl -o "-o -F -p 5433" start
> 
> Stopping postmaster
> 
> pg_ctl stop
> 
> stops postmaster.
> 
> There are several options for the stopping mode.
> 
> -w
>         waits for postmaster shutting down
> 
> -m
>        specifies the shutdown mode. s[mart] mode waits for all
>        the clients get logged out. This is the default.
>        f[ast] mode sends SIGTERM to the backends, that means
>        active transactions get rollback. i[mmediate] mode sends SIGUSR1
>        to the backends and let them abort. In this case, database recovery
>        will be neccessary on the next startup.
> 
> Restarting postmaster
> 
> This is almost equivalent to stopping postmaster then starting it
> again except that the parameters for postmaster used before stopping
> it would be used too. This is done by saving them in
> PGDATA/postmaster.opts file. -w, -D, -m, and -o can also be used in
> the restarting mode and they have same meanings as described above.
> 
> Examples:
> 
> # restarting postmaster in the simplest form
> pg_ctl restart
> 
> # waiting for postmaster shutdown and waiting for postmaster coming up
> pg_ctl -w restart
> 
> # uses port 5433 and disables fsync next time
> pg_ctl -o "-o -F -p 5433" restart
> 
> Getting status from postmaster
> 
> To get status information from postmaster:
> 
> pg_ctl status
> 
> Followings are sample outputs from pg_ctl.
> 
> pg_ctl: postmaster is running (pid: 13718)
> options are:
> /usr/local/src/pgsql/current/bin/postmaster
> -p 5433
> -D /usr/local/src/pgsql/current/data
> -B 64
> -b /usr/local/src/pgsql/current/bin/postgres
> -N 32
> -o '-F'

-- 
Thomas Lockhart				lockhart@alumni.caltech.edu
South Pasadena, California

Sun, 06 Feb 2000 04:33:01 +0000
Thomas Lockhart <lockhart@alumni.caltech.edu>
Re: [HACKERS] pg_ctl man page
> > I have written a man page for pg_ctl. I will appreciate if someone
> > would give me comments on it including grammatical corrections.
> 
> I assume that this is intended for the main documentation set? Then
> I'll be happy to convert this to sgml markup if you haven't done so or
> do not know how. Also, I can make small changes to grammar etc at that
> time.

Oh, thank you very much!

> You probably weren't asking about this, but...
> 
> The switch options "smart", "fast", and "immediate" are imho a bit too
> general. I would suggest that "wait", "stop", and "abort" (or
> something similar) might be better and more direct terms which would
> come to mind for an admin. Though I see that you also have the concept
> of "wait" wrt pg_ctl and the postmaster, to allow pg_ctl to return
> immediately before the effects of the commands are seen. So maybe
> "asychronous" or something similar could be applied to the
> pg_ctl/postmaster relationship, leaving the other terms for the
> pg_ctl/client relationship.

Talking about "smart/fast/immediate," I have refered to them from
comments in postmaster.c probably written by Vadim. So before changing
them I would like to hear from Vadim. Ok?

> I would also suggest dropping "-m <opt>" style switches in favor of
> specific flags, with the last flag specified taking precedence. I'm
> not aware of other utilities having quite that same style.

Sounds resonable. 
--
Tatsuo Ishii

Sun, 06 Feb 2000 15:40:03 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
Re: [HACKERS] pg_ctl man page
I got grammer corrections from Ed Loehr. Also, I modified some option
flag styles according to Thomas's suggestion. Thanks for those who
gave me suggestions.

Thomas, I have changed -m <opts> style to -smart, -fast... style. I
hope this was what you meant. Also, please note that I still stick
with smart/fast/immediate since I have been waiting for Vadim's
opinion...

Tatsuo Ishii
-------------------------------------------------------------------
NAME

pg_ctl - starts/stops/restarts postmaster

SYNOPSIS

pg_ctl [-w][-D database_dir][-p path_to_postmaster][-o "postmaster_opts"] start
pg_ctl [-w][-D database_dir][-smart|-fast|-immediate] stop
pg_ctl [-w][-D database_dir][-smart|-fast|-immediate][-o "postmaster_opts"] restart
pg_ctl [-D database_dir] status

DESCRIPTION

pg_ctl is a utility for starting, stopping or restarting postmaster.

Starting postmaster

To start postmaster:

pg_ctl start

If -w is supplied, pg_ctl waits for the database server comes up, by
watching for creation of the pid file (PGDATA/postmaster.pid), for up
to 60 seconds.

Parameters to invoke postmaster are taken from following sources:

Path to postmaster: found in the command search path
Database directory: PGDATA environment variable
Other parameters: PGDATA/postmaster.opts.default

postmaster.opts.default contains parameters for postmaster. With a
default installation, the "-S" option is enabled. So "pg_ctl start"
implies:

postmaster -S

Note that postmaster.opts.default is installed by initdb from
lib/postmaster.opts.default.sample under the PostgreSQL installation
directory (lib/postmaster.opts.default.sample is copied from
src/bin/pg_ctl/postmaster.opts.default.sample while installing
PostgreSQL).

To override default parameters you can use -D, -p and -o options.

-D database_dir
	specifies the database directory

-p path_to_postmaster
	specifies the path to postmaster

-o "postmaster_opts"
	specifies any parameters for postmaster

Examples:

# blocks until postmaster comes up
pg_ctl -w start

# specifies postmaster path
pg_ctl -p /usr/local/pgsq/bin/postmaster start

# uses port 5433 and disables fsync
pg_ctl -o "-o -F -p 5433" start

Stopping postmaster

pg_ctl stop

stops postmaster.

There are several options for the stopping mode.

-w
	waits for postmaster to shut down

-smart|-fast|-immediate
       specifies the shutdown mode. smart mode waits for all
       the clients to logout. This is the default.
       fast mode sends SIGTERM to the backends, that means
       active transactions get rolled back. immediate mode sends SIGUSR1
       to the backends and lets them abort. In this case, database recovery
       will be neccessary on the next startup.


Restarting postmaster

This is almost equivalent to stopping postmaster then starting it
again except that the parameters for postmaster used before stopping
it would be used too. This is done by saving them in
PGDATA/postmaster.opts file. -w, -D, -smart, -fast, -immediate and -o
can also be used in the restarting mode and they have same meanings as
described above.

Examples:

# restarts postmaster in the simplest form
pg_ctl restart

# restarts postmaster, waiting for it to shut down and to come up
pg_ctl -w restart

# uses port 5433 and disables fsync next time
pg_ctl -o "-o -F -p 5433" restart

Getting status from postmaster

To get status information from postmaster:

pg_ctl status

Following is sample outputs from pg_ctl.

pg_ctl: postmaster is running (pid: 13718)
options are:
/usr/local/src/pgsql/current/bin/postmaster
-p 5433
-D /usr/local/src/pgsql/current/data
-B 64
-b /usr/local/src/pgsql/current/bin/postgres
-N 32
-o '-F'


************

Mon, 07 Feb 2000 13:49:47 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
Re: [HACKERS] pg_ctl man page
On 2000-02-07, Tatsuo Ishii mentioned:

> I got grammer corrections from Ed Loehr. Also, I modified some option
> flag styles according to Thomas's suggestion. Thanks for those who
> gave me suggestions.
> 
> Thomas, I have changed -m <opts> style to -smart, -fast... style. I
> hope this was what you meant. Also, please note that I still stick
> with smart/fast/immediate since I have been waiting for Vadim's
> opinion...

Ugh, that's not a compliant option style. What was wrong with -m
<opt>? How about --smart, etc.? But 'single dash, multiple letters' is
evil.

-- 
Peter Eisentraut                  Sernanders vï¿½g 10:115
peter_e@gmx.net                   75262 Uppsala
http://yi.org/peter-e/            Sweden


Mon, 7 Feb 2000 20:53:35 +0100 (CET)
Peter Eisentraut <peter_e@gmx.net>
Re: [HACKERS] pg_ctl man page
> > I got grammer corrections from Ed Loehr. Also, I modified some option
> > flag styles according to Thomas's suggestion. Thanks for those who
> > gave me suggestions.
> > 
> > Thomas, I have changed -m <opts> style to -smart, -fast... style. I
> > hope this was what you meant. Also, please note that I still stick
> > with smart/fast/immediate since I have been waiting for Vadim's
> > opinion...
> 
> Ugh, that's not a compliant option style. What was wrong with -m
> <opt>? How about --smart, etc.? But 'single dash, multiple letters' is
> evil.

Oh, I'm confused now. Thomas, could you let me know what you think?
Lamar is trying to use pg_ctl for his RPM project, and we need
decision on that.
--
Tatsuo Ishii



Tue, 08 Feb 2000 10:51:26 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
Re: [HACKERS] pg_ctl man page
> > > Thomas, I have changed -m <opts> style to -smart, -fast... style. I
> > > hope this was what you meant. Also, please note that I still stick
> > > with smart/fast/immediate since I have been waiting for Vadim's
> > > opinion...
> > Ugh, that's not a compliant option style. What was wrong with -m
> > <opt>? How about --smart, etc.? But 'single dash, multiple letters' is
> > evil.
> Oh, I'm confused now. Thomas, could you let me know what you think?
> Lamar is trying to use pg_ctl for his RPM project, and we need
> decision on that.

Sorry, I didn't catch your question earlier. I agree with Peter that
we should choose single character switches with single dashes (e.g. -s
for "smart", -f for "fast", etc.) or --smart, --fast etc (or both
styles).

Hopefully we'll get some feedback from Vadim soon on the naming; istm
that the "smart", "fast", "immediate" is just too obscure or too
related to the developer's view of the implementation to be the right
choice for the user interface.

The switches and options should describe what they *do*, not what the
developer thought of them ;)

                      - Thomas

-- 
Thomas Lockhart				lockhart@alumni.caltech.edu
South Pasadena, California

Tue, 08 Feb 2000 06:47:22 +0000
Thomas Lockhart <lockhart@alumni.caltech.edu>
Re: [HACKERS] pg_ctl man page
On Tue, 08 Feb 2000, Thomas Lockhart wrote:

> > Oh, I'm confused now. Thomas, could you let me know what you think?
> > Lamar is trying to use pg_ctl for his RPM project, and we need
> > decision on that.
 
> Sorry, I didn't catch your question earlier. I agree with Peter that
> we should choose single character switches with single dashes (e.g. -s
> for "smart", -f for "fast", etc.) or --smart, --fast etc (or both
> styles).

As for the RPM stuff, I can wait until it's ready easily enough -- if that's
early or late in the beta cycle is immaterial -- I'm just trying to get a feel
for the order I need to do things in.

--
Lamar Owen
WGCR Internet Radio
1 Peter 4:11

Tue, 8 Feb 2000 07:51:49 -0500
Lamar Owen <lamar.owen@wgcr.org>
Re: [HACKERS] pg_ctl man page
Beta testing is about to start, but I have not heard from Vadim what
he thinks about "smart" etc yet. Time is up... So I decided to keep
the options of pg_ctl as it is for coming 7.0.

P.S. I have reverted back "-smart" to "-m smart" as Peter and Thomas
suggested. If I have spare time, I would add "---" style options as
well. My first priority is fixing bugs and writing documentaions about
the multibyte support...
--
Tatsuo Ishii
-------------------------------------------------------------------
NAME

pg_ctl - starts/stops/restarts postmaster

SYNOPSIS

pg_ctl [-w][-D database_dir][-p path_to_postmaster][-o "postmaster_opts"] start
pg_ctl [-w][-D database_dir][-m [s[mart]|f[ast]|i[mmediate]]] stop
pg_ctl [-w][-D database_dir][-m [s[mart]|f[ast]|i[mmediate]][-o "postmaster_opts"] restart
pg_ctl [-D database_dir] status

DESCRIPTION

pg_ctl is a utility for starting, stopping or restarting postmaster.

Starting postmaster

To start postmaster:

pg_ctl start

If -w is supplied, pg_ctl waits for the database server comes up, by
watching for creation of the pid file (PGDATA/postmaster.pid), for up
to 60 seconds.

Parameters to invoke postmaster are taken from following sources:

Path to postmaster: found in the command search path
Database directory: PGDATA environment variable
Other parameters: PGDATA/postmaster.opts.default

postmaster.opts.default contains parameters for postmaster. With a
default installation, the "-S" option is enabled. So "pg_ctl start"
implies:

postmaster -S

Note that postmaster.opts.default is installed by initdb from
lib/postmaster.opts.default.sample under the PostgreSQL installation
directory (lib/postmaster.opts.default.sample is copied from
src/bin/pg_ctl/postmaster.opts.default.sample while installing
PostgreSQL).

To override default parameters you can use -D, -p and -o options.

-D database_dir
	specifies the database directory

-p path_to_postmaster
	specifies the path to postmaster

-o "postmaster_opts"
	specifies any parameters for postmaster

Examples:

# blocks until postmaster comes up
pg_ctl -w start

# specifies postmaster path
pg_ctl -p /usr/local/pgsq/bin/postmaster start

# uses port 5433 and disables fsync
pg_ctl -o "-o -F -p 5433" start

Stopping postmaster

pg_ctl stop

stops postmaster.

There are several options for the stopping mode.

-w
	waits for postmaster to shut down

-m [s[mart]|f[ast]|i[mmediate]]
       specifies the shutdown mode. smart mode waits for all
       the clients to logout. This is the default.
       fast mode sends SIGTERM to the backends, that means
       active transactions get rolled back. immediate mode sends SIGUSR1
       to the backends and lets them abort. In this case, database recovery
       will be neccessary on the next startup.


Restarting postmaster

This is almost equivalent to stopping postmaster then starting it
again except that the parameters for postmaster used before stopping
it would be used too. This is done by saving them in
PGDATA/postmaster.opts file. -w, -D, -m, -fast, -immediate and -o
can also be used in the restarting mode and they have same meanings as
described above.

Examples:

# restarts postmaster in the simplest form
pg_ctl restart

# restarts postmaster, waiting for it to shut down and to come up
pg_ctl -w restart

# uses port 5433 and disables fsync next time
pg_ctl -o "-o -F -p 5433" restart

Getting status from postmaster

To get status information from postmaster:

pg_ctl status

Following is sample outputs from pg_ctl.

pg_ctl: postmaster is running (pid: 13718)
options are:
/usr/local/src/pgsql/current/bin/postmaster
-p 5433
-D /usr/local/src/pgsql/current/data
-B 64
-b /usr/local/src/pgsql/current/bin/postgres
-N 32
-o '-F'


************

************

Tue, 22 Feb 2000 10:47:57 +0900
Tatsuo Ishii <t-ishii@sra.co.jp>
Re: [HACKERS] pg_ctl man page