diff --git a/doc/src/sgml/ref/pg_ctl-ref.sgml b/doc/src/sgml/ref/pg_ctl-ref.sgml index 176dfaf98a3..71e52c4c355 100644 --- a/doc/src/sgml/ref/pg_ctl-ref.sgml +++ b/doc/src/sgml/ref/pg_ctl-ref.sgml @@ -23,19 +23,19 @@ PostgreSQL documentation pg_ctl - datadir + initdb-options pg_ctl + datadir + filename seconds - datadir - filename options path @@ -44,9 +44,6 @@ PostgreSQL documentation pg_ctl - - seconds - datadir @@ -55,16 +52,15 @@ PostgreSQL documentation + + seconds + pg_ctl - - seconds - datadir - @@ -72,14 +68,18 @@ PostgreSQL documentation + + seconds + options + pg_ctl - datadir + @@ -91,10 +91,10 @@ PostgreSQL documentation pg_ctl + datadir seconds - datadir @@ -104,19 +104,22 @@ PostgreSQL documentation process_id + On Microsoft Windows, also: + pg_ctl + datadir servicename username password - datadir + source seconds @@ -147,14 +150,14 @@ PostgreSQL documentation The or mode creates a new - PostgreSQL database cluster. A database - cluster is a collection of databases that are managed by a single + PostgreSQL database cluster, that is, + a collection of databases that will be managed by a single server instance. This mode invokes the initdb command. See for details. - In mode, a new server is launched. The + mode launches a new server. The server is started in the background, and its standard input is attached to /dev/null (or nul on Windows). On Unix-like systems, by default, the server's standard output and @@ -172,8 +175,8 @@ PostgreSQL documentation - In mode, the server that is running in - the specified data directory is shut down. Three different + mode shuts down the server that is running in + the specified data directory. Three different shutdown methods can be selected with the option. Smart mode waits for all active clients to disconnect and any online backup to finish. @@ -183,60 +186,63 @@ PostgreSQL documentation 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 immediately, without a clean shutdown. - This will lead to a crash-recovery run on the next restart. + all server processes immediately, without a clean shutdown. This choice + will lead to a crash-recovery cycle during the next server start. mode effectively executes a stop followed by a start. This allows changing the postgres - command-line options. might fail if - relative paths specified were specified on the command-line during - server start. + command-line options, or changing configuration-file options that + cannot be changed without restarting the server. + If relative paths were used on the command line during server + start, might fail unless + pg_ctl is executed in the same current + directory as it was during server start. mode simply sends the - postgres process a SIGHUP + postgres server 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 + pg_hba.conf, etc.). This allows changing + configuration-file options that do not require a full server restart to take effect. 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. If the server is not running, the process returns an - exit status of 3. If an accessible data directory is not specified, - the process returns an exit status of 4. + the specified data directory. If it is, the server's PID + and the command line options that were used to invoke it are displayed. + If the server is not running, pg_ctl returns + an exit status of 3. If an accessible data directory is not + specified, pg_ctl returns an exit status of 4. - In mode, the standby server that is - running in the specified data directory is commanded to exit - recovery and begin read-write operations. + mode commands the standby server that is + running in the specified data directory to end standby mode + and begin read-write operations. - 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. + mode sends a signal to a specified process. + This is primarily valuable on Microsoft Windows + which does not have a built-in kill command. Use + --help to see a list of supported signal names. - mode allows you to register a system service - on Microsoft Windows. The option - allows selection of service start type, either auto (start - service automatically on system startup) or demand (start - service on demand). + mode registers the PostgreSQL + server as a system service on Microsoft Windows. + The option allows selection of service start type, + either auto (start service automatically on system startup) + or demand (start service on demand). - mode allows you to unregister a system service + mode unregisters a system service on Microsoft Windows. This undoes the effects of the command. @@ -249,7 +255,7 @@ PostgreSQL documentation - + Attempt to allow server crashes to produce core files, on platforms @@ -267,7 +273,7 @@ PostgreSQL documentation Specifies the file system location of the database configuration files. If - this is omitted, the environment variable + this option is omitted, the environment variable PGDATA is used. @@ -294,7 +300,8 @@ PostgreSQL documentation Specifies the shutdown mode. mode can be smart, fast, or immediate, or the first letter of one of - these three. If this is omitted, fast is used. + these three. If this option is omitted, fast is + the default. @@ -305,12 +312,13 @@ PostgreSQL documentation Specifies options to be passed directly to the - postgres command; multiple - option invocations are appended. + postgres command. + - The options should usually be surrounded by single or double - quotes to ensure that they are passed through as a group. + The options should usually be surrounded by single or + double quotes to ensure that they are passed through as a group. @@ -322,10 +330,12 @@ PostgreSQL documentation Specifies options to be passed directly to the initdb command. + - The options should usually be surrounded by single or double - quotes to ensure that they are passed through as a group. + The options should usually be surrounded by single or + double quotes to ensure that they are passed through as a group. @@ -361,14 +371,14 @@ PostgreSQL documentation - - + + - The maximum number of seconds to wait when waiting for an operation - to complete (see option ). Defaults to the value of the - PGCTLTIMEOUT environment variable or, if not set, to 60 - seconds. + Specifies the maximum number of seconds to wait when waiting for an + operation to complete (see option ). Defaults to + the value of the PGCTLTIMEOUT environment variable or, if + not set, to 60 seconds. @@ -388,7 +398,7 @@ PostgreSQL documentation - Wait for an operation to complete. This is supported for the + Wait for the operation to complete. This is supported for the modes start, stop, restart, promote, and register, and is the default for those modes. @@ -399,7 +409,6 @@ PostgreSQL documentation attempts to connect to the server. When waiting for shutdown, pg_ctl waits for the server to remove its PID file. - This option allows the entry of an SSL passphrase on startup. pg_ctl returns an exit code based on the success of the startup or shutdown. @@ -411,8 +420,8 @@ PostgreSQL documentation - Do not wait for an operation to complete. This is the opposite of the - option . + Do not wait for the operation to complete. This is the opposite of + the option . @@ -441,6 +450,11 @@ PostgreSQL documentation + + If an option is specified that is valid, but not relevant to the selected + operating mode, pg_ctl ignores it. + + Options for Windows @@ -452,11 +466,12 @@ PostgreSQL documentation Name of the event source for pg_ctl to use for logging to the event log when running as a Windows service. The default is PostgreSQL. Note that this only controls - the logging from pg_ctl itself; once + messages sent from pg_ctl itself; once started, the server will use the event source specified - by . Should the server fail during - early startup, it might also log using the default event - source PostgreSQL. + by its parameter. Should the server + fail very early in startup, before that parameter has been set, + it might also log using the default event + source name PostgreSQL. @@ -465,8 +480,9 @@ PostgreSQL documentation - 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. + The default is PostgreSQL. @@ -475,7 +491,7 @@ PostgreSQL documentation - Password for the user to start the service. + Password for the user to run the service as. @@ -484,10 +500,10 @@ PostgreSQL documentation - Start type of the system service to register. start-type can + Start type of the system service. start-type can be auto, or demand, or - the first letter of one of these two. If this is omitted, - auto is used. + the first letter of one of these two. If this option is omitted, + auto is the default. @@ -496,7 +512,7 @@ PostgreSQL documentation - 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 DOMAIN\username. @@ -534,12 +550,22 @@ PostgreSQL documentation + + Most pg_ctl modes require knowing the data directory + location; therefore, the + pg_ctl, like most other PostgreSQL utilities, also uses the environment variables supported by libpq (see ). - For additional server variables, see . + + + + For additional variables that affect the server, + see . @@ -553,9 +579,8 @@ PostgreSQL documentation - The existence of this file in the data directory is used to help - pg_ctl determine if the server is - currently running. + pg_ctl examines this file in the data + directory to determine whether the server is currently running. @@ -584,13 +609,6 @@ PostgreSQL documentation Starting the Server - - To start the server: - -$ pg_ctl start - - - To start the server, waiting until the server is accepting connections: @@ -626,24 +644,17 @@ PostgreSQL documentation 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 the server, - waiting for it to shut down and restart: + server and starting it again, except that by default, + pg_ctl saves and reuses the command line options that + were passed to the previously-running instance. To restart + the server using the same options as before, use: $ pg_ctl restart + But if diff --git a/src/bin/pg_ctl/pg_ctl.c b/src/bin/pg_ctl/pg_ctl.c index c63819b88b4..f34dd28c6e2 100644 --- a/src/bin/pg_ctl/pg_ctl.c +++ b/src/bin/pg_ctl/pg_ctl.c @@ -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(_("Usage:\n")); - 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 stop [-W] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"), progname); - printf(_(" %s restart [-w] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n" - " [-o \"OPTIONS\"]\n"), progname); - printf(_(" %s reload [-D DATADIR] [-s]\n"), progname); - printf(_(" %s status [-D DATADIR]\n"), progname); - printf(_(" %s promote [-w] [-t SECS] [-D DATADIR] [-s]\n"), progname); - printf(_(" %s kill SIGNALNAME PID\n"), progname); + printf(_(" %s init[db] [-D DATADIR] [-s] [-o OPTIONS]\n"), progname); + printf(_(" %s start [-D DATADIR] [-l FILENAME] [-W] [-t SECS] [-s]\n" + " [-o OPTIONS] [-p PATH] [-c]\n"), progname); + printf(_(" %s stop [-D DATADIR] [-m SHUTDOWN-MODE] [-W] [-t SECS] [-s]\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 status [-D DATADIR]\n"), progname); + printf(_(" %s promote [-D DATADIR] [-W] [-t SECS] [-s]\n"), progname); + printf(_(" %s kill SIGNALNAME PID\n"), progname); #ifdef WIN32 - printf(_(" %s register [-N SERVICENAME] [-U USERNAME] [-P PASSWORD] [-D DATADIR]\n" - " [-S START-TYPE] [-w] [-t SECS] [-o \"OPTIONS\"]\n"), progname); + printf(_(" %s register [-D DATADIR] [-N SERVICENAME] [-U USERNAME] [-P PASSWORD]\n" + " [-S START-TYPE] [-e SOURCE] [-W] [-t SECS] [-s] [-o OPTIONS]\n"), progname); printf(_(" %s unregister [-N SERVICENAME]\n"), progname); #endif @@ -1958,7 +1959,6 @@ do_help(void) printf(_(" -w, --wait wait until operation completes (default)\n")); printf(_(" -W, --no-wait do not wait until operation completes\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(_("\nOptions for start or restart:\n")); @@ -1976,7 +1976,7 @@ do_help(void) printf(_("\nShutdown modes are:\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(_("\nAllowed signal names for kill:\n")); @@ -2242,7 +2242,8 @@ main(int argc, char **argv) /* process command-line options */ 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) {