Provided by: postgresql-8.4_8.4.8-0ubuntu0.11.04_i386 bug

NAME

       pg_ctl - start, stop, or restart a PostgreSQL server

SYNOPSIS

       pg_ctl  start  [  -w  ]   [  -t seconds ]  [ -s ]  [ -D datadir ]  [ -l
       filename ]  [ -o options ]  [ -p path ]  [ -c ]

       pg_ctl stop [ -W ]  [ -t seconds ]  [ -s ]  [ -D datadir ]  [ -m
         [ s[mart] ]  [ f[ast] ]  [ i[mmediate] ]
        ]

       pg_ctl restart [ -w ]  [ -t seconds ]  [ -s ]  [ -D datadir ]  [  -c  ]
       [ -m
         [ s[mart] ]  [ f[ast] ]  [ i[mmediate] ]
        ]  [ -o options ]

       pg_ctl reload [ -s ]  [ -D datadir ]

       pg_ctl status [ -D datadir ]

       pg_ctl kill [ signal_name ]  [ process_id ]

       pg_ctl register [ -N servicename ]  [ -U username ]  [ -P password ]  [
       -D datadir ]  [ -w ]  [ -t seconds ]  [ -o options ]

       pg_ctl unregister [ -N servicename ]

DESCRIPTION

       pg_ctl  is  a  utility  for  starting,  stopping,  or  restarting   the
       PostgreSQL  backend server (postgres(1)), or displaying the status of a
       running server. Although the server can  be  started  manually,  pg_ctl
       encapsulates   tasks  such  as  redirecting  log  output  and  properly
       detaching from  the  terminal  and  process  group.  It  also  provides
       convenient options for controlled shutdown.

       In  start  mode, a new server is launched. The server is started in the
       background, and standard input is attached to /dev/null.  The  standard
       output  and standard error are either appended to a log file (if the -l
       option is  used),  or  redirected  to  pg_ctl's  standard  output  (not
       standard  error).  If  no  log  file  is chosen, the standard output of
       pg_ctl should be redirected to a file or piped to another process  such
       as  a  log  rotating  program  like rotatelogs; otherwise postgres will
       write its output to the controlling terminal (from the background)  and
       will not leave the shell's process group.

       In  stop  mode,  the  server  that  is  running  in  the specified data
       directory is  shut  down.  Three  different  shutdown  methods  can  be
       selected  with  the  -m  option: ``Smart'' mode waits for online backup
       mode to finish and all the clients to disconnect. This is the  default.
       ``Fast''  mode  does  not  wait  for  clients  to  disconnect  and will
       terminate an online backup in progress.  All  active  transactions  are
       rolled  back  and clients are forcibly disconnected, then the server is
       shut down. ``Immediate'' mode will abort all server processes without a
       clean shutdown. This will lead to a recovery run on restart.

       restart  mode  effectively  executes  a  stop followed by a start. This
       allows changing the postgres command-line options.

       reload mode simply sends the postgres process a SIGHUP signal,  causing
       it  to  reread  its  configuration files (postgresql.conf, pg_hba.conf,
       etc.). This allows changing of configuration-file options that  do  not
       require a complete restart to take effect.

       status  mode  checks  whether a server is running in the specified data
       directory. If it is, the PID and the command  line  options  that  were
       used to invoke it are displayed.

       kill  mode  allows you to send a signal to a specified process. This is
       particularly valuable for Microsoft Windows which does not have a  kill
       command. Use --help to see a list of supported signal names.

       register  mode  allows  you  to  register a system service on Microsoft
       Windows.

       unregister mode allows you to unregister a system service on  Microsoft
       Windows, previously registered with the register command.

OPTIONS

       -c     Attempt  to  allow  server  crashes  to  produce  core files, on
              platforms where this available, by  lifting  any  soft  resource
              limit placed on them.  This is useful in debugging or diagnosing
              problems by allowing a stack trace to be obtained from a  failed
              server process.

       -D datadir
              Specifies  the  file  system  location of the database files. If
              this is omitted, the environment variable PGDATA is used.

       -l filename
              Append the server log output to filename. 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.

       -m mode
              Specifies the  shutdown  mode.  mode  can  be  smart,  fast,  or
              immediate, or the first letter of one of these three.

       -o options
              Specifies options to be passed directly to the postgres command.

              The options are usually surrounded by single or double quotes to
              ensure that they are passed through as a group.

       -p path
              Specifies the location of the postgres  executable.  By  default
              the  postgres  executable  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  postgres  executable
              was not found.

       -s     Only print errors, no informational messages.

       -t     The number of seconds to wait when waiting for start or shutdown
              to complete.

       -w     Wait for the start or shutdown to  complete.  The  default  wait
              time  is 60 seconds. This is the default option for shutdowns. A
              successful shutdown is indicated by removal of the PID file. For
              starting up, a successful psql -l indicates success. pg_ctl will
              attempt to use the proper port  for  psql.  If  the  environment
              variable  PGPORT exists, that is used. Otherwise, it will see if
              a port has been set in the postgresql.conf file.  If neither  of
              those  is used, it will use the default port that PostgreSQL was
              compiled with (5432  by  default).  When  waiting,  pg_ctl  will
              return an accurate exit code based on the success of the startup
              or shutdown.

       -W     Do not wait for start or  shutdown  to  complete.  This  is  the
              default for starts and restarts.

   OPTIONS FOR WINDOWS
       -N servicename
              Name of the system service to register. The name will be used as
              both the service name and the display name.

       -P password
              Password for the user to start the service.

       -U username
              User name for the user to start the service. For  domain  users,
              use the format DOMAIN\username.

ENVIRONMENT

       PGDATA Default data directory location.

       PGPORT Default port for psql(1) (used by the -w option).

       For  additional  server variables, see postgres(1).  This utility, like
       most other PostgreSQL utilities, also uses  the  environment  variables
       supported by libpq (see in the documentation).

FILES

       postmaster.pid
              The existence of this file in the data directory is used to help
              pg_ctl determine if the server is currently running or not.

       postmaster.opts
              If this file exists in the data directory,  pg_ctl  (in  restart
              mode) will pass the contents of the file as options to postgres,
              unless overridden by the -o option. The contents  of  this  file
              are also displayed in status mode.

       postgresql.conf
              This  file, located in the data directory, is parsed to find the
              proper port to use with psql when the -w is given in start mode.

NOTES

       Waiting for complete start is not a well-defined  operation  and  might
       fail  if access control is set up so that a local client cannot connect
       without  manual  interaction  (e.g.,  password   authentication).   For
       additional  connection  variables,  see  in  the documentation, and for
       passwords, also see in the documentation.

EXAMPLES

   STARTING THE SERVER
       To start up a server:

       $ pg_ctl start

       An example of starting the server, blocking until the server  has  come
       up is:

       $ pg_ctl -w start

       For a server using port 5433, and running without fsync, use:

       $ pg_ctl -o "-F -p 5433" start

   STOPPING THE SERVER
       $ pg_ctl stop

       stops  the  server.  Using  the -m switch allows one to control how the
       backend shuts down.

   RESTARTING THE SERVER
       Restarting the server is almost equivalent to stopping the  server  and
       starting  it again except that pg_ctl saves and reuses the command line
       options that were passed to the previously running instance. To restart
       the server in the simplest form, use:

       $ pg_ctl restart

       To restart server, waiting for it to shut down and to come up:

       $ pg_ctl -w restart

       To restart using port 5433 and disabling fsync after restarting:

       $ pg_ctl -o "-F -p 5433" restart

   SHOWING THE SERVER STATUS
       Here is a sample status output from pg_ctl:

       $ pg_ctl status
       pg_ctl: server is running (pid: 13718)
       Command line was:
       /usr/local/pgsql/bin/postgres '-D' '/usr/local/pgsql/data' '-p' '5433' '-B' '128'

       This is the command line that would be invoked in restart mode.

SEE ALSO

       postgres(1)