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.

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