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.

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

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.5 2000/12/25 23:15:26 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.6 2001/02/08 19:39:24 petere Exp $
 Postgres documentation
 -->
 
 <refentry id="app-pg-ctl">
  <docinfo>
-  <date>2000-11-25</date>
+  <date>2001-02-08</date>
  </docinfo>
 
  <refmeta>
@@ -25,12 +25,13 @@ Postgres documentation
    <arg choice="plain">start</arg>
    <arg>-w</arg>
    <arg>-D <replaceable>datadir</replaceable></arg>
-   <arg>-p <replaceable>path</replaceable></arg>
+   <arg>-l <replaceable>filename</replaceable></arg>
    <arg>-o <replaceable>options</replaceable></arg>
+   <arg>-p <replaceable>path</replaceable></arg>
    <sbr>
    <command>pg_ctl</command>
    <arg choice="plain">stop</arg>
-   <arg>-w</arg>
+   <arg>-W</arg>
    <arg>-D <replaceable>datadir</replaceable></arg>
    <arg>-m
      <group choice="plain">
@@ -64,8 +65,52 @@ Postgres documentation
   <title>Description</title>
   <para>
    <application>pg_ctl</application> is a utility for starting,
-   stopping, or restarting the <xref linkend="app-postmaster">, or
-   displaying the status of a running postmaster.
+   stopping, or restarting <xref linkend="app-postmaster">, the
+   <productname>PostgreSQL</productname> backend server, or displaying
+   the status of a running postmaster.  Although the postmaster can be
+   started manually, <application>pg_ctl</application> encapulates
+   tasks such as redirecting log output, properly detaching from the
+   terminal and process group, and additionally provides an option for
+   controlled shut down.
+  </para>
+
+  <para>
+   In <option>start</option> mode, a new postmaster is launched.  The
+   server is started in the background, the standard input attached to
+   <filename>/dev/null</filename>.  The standard output and standard
+   error are either appended to a log file, if the <option>-l</option>
+   option is used, or are redirected to
+   <application>pg_ctl</application>'s standard output (not standard
+   error).  If no log file is chosen, the standard output of
+   <application>pg_ctl</application> should be redirected to a file or
+   piped to another process, for example a log rotating program,
+   otherwise the postmaster will write its output the the controlling
+   terminal (from the background) and will not leave the shell's
+   process group.
+  </para>
+
+  <para>
+   In <option>stop</option> mode, the postmaster that is running on
+   the specified data directory is shut down.  Three different
+   shutdown methods can be selected with the <option>-m</option>
+   option: <quote>Smart</quote> mode waits for all the clients to
+   disconnect.  This is the default.  <quote>Fast</quote> mode does
+   not wait for clients to disconnect.  All active transactions will
+   be rolled back.  <quote>Immediate</quote> mode will abort without
+   complete shutdown.  This will lead to a recovery run on restart.
+   By the default, stop mode waits for the shutdown to complete.
+  </para>
+
+  <para>
+   <option>restart</option> mode effectively executes a stop followed
+   by a start.  This allows the changing of postmaster command line
+   options.
+  </para>
+
+  <para>
+   <option>status</option> mode checks whether a postmaster is running
+   and if so displays the <acronym>PID</acronym> and the command line
+   options that were used to invoke it.
   </para>
 
   <refsect2 id="app-pg-ctl-options">
@@ -74,38 +119,36 @@ Postgres documentation
 
     <variablelist>
      <varlistentry>
-      <term>-w</term>
+      <term>-D <replaceable class="parameter">datadir</replaceable></term>
       <listitem>
        <para>
-	Wait for the database server to come up, by watching for
-	creation of the pid file
-	(<filename><replaceable>PGDATA</replaceable>/postmaster.pid</filename>).
-	Times out after 60 seconds.
+	Specifies the file system location of the database files.  If
+	this is omitted, the environment variable
+	<envar>PGDATA</envar> is used.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-D <replaceable class="parameter">datadir</replaceable></term>
+      <term>-l <replaceable class="parameter">filename</replaceable></term>
       <listitem>
        <para>
-	Specifies the file system location of the database files.  If
-	this is omitted, the environment variable
-	<envar>PGDATA</envar> is used.
+        Append the server log output to
+        <replaceable>filename</replaceable>.  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.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>-p <replaceable class="parameter">path</replaceable></term>
+      <term>-m <replaceable class="parameter">mode</replaceable></term>
       <listitem>
        <para>
-	Specifies the location of the <filename>postmaster</filename>
-	executable.  By default the postmaster 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 postmaster was not found.
+	Specifies the shutdown mode.  <replaceable>mode</replaceable>
+	may be <literal>smart</literal>, <literal>fast</literal>, or
+	<literal>immediate</literal>, or the first letter of one of
+	these three.
        </para>
       </listitem>
      </varlistentry>
@@ -125,82 +168,35 @@ Postgres documentation
      </varlistentry>
 
      <varlistentry>
-      <term>-m <replaceable class="parameter">mode</replaceable></term>
-      <listitem>
-       <para>
-	Specifies the shutdown mode.
-
-	<variablelist>
-	 <varlistentry>
-	  <term>smart</term>
-	  <term>s</term>
-	  <listitem>
-	   <para>
-	    Smart mode waits for all the clients to disconnect. This
-	    is the default.
-	   </para>
-	  </listitem>
-	 </varlistentry>
-
-	 <varlistentry>
-	  <term>fast</term>
-	  <term>f</term>
-	  <listitem>
-	   <para>
-	    Fast mode does not wait for clients to disconnect.  All
-	    active transactions will be rolled back.
-	   </para>
-	  </listitem>
-	 </varlistentry>
-
-	 <varlistentry>
-	  <term>immediate</term>
-	  <term>i</term>
-	  <listitem>
-	   <para>
-	    Immediate mode will abort without complete shutdown.  This
-	    will lead to a recovery run on restart.
-	   </para>
-	  </listitem>
-	 </varlistentry>
-	</variablelist>
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>start</term>
-      <listitem>
-       <para>
-	Start up <application>postmaster</application>.
-       </para>
-      </listitem>
-     </varlistentry>
-
-     <varlistentry>
-      <term>stop</term>
+      <term>-p <replaceable class="parameter">path</replaceable></term>
       <listitem>
        <para>
-	Shut down <application>postmaster</application>.
+	Specifies the location of the <filename>postmaster</filename>
+	executable.  By default the postmaster 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 postmaster was not found.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>restart</term>
+      <term>-w</term>
       <listitem>
        <para>
-	Stop the <application>postmaster</application>, if one is running,
-	and then start it again.
+	Wait for the start or stutdown to complete.  Times out after
+	60 seconds.  This is the default for shutdowns.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term>status</term>
+      <term>-W</term>
       <listitem>
        <para>
-	Show the current state of <application>postmaster</application>.
+        Do not wait for start or shutdown to complete.  This is the
+        default for starts and restarts.
        </para>
       </listitem>
      </varlistentry>
@@ -223,7 +219,7 @@ Postgres documentation
 
 
  <refsect1 id="R1-APP-PGCTL-2">
-  <title>Usage</title>
+  <title>Examples</title>
 
   <refsect2 id="R2-APP-PGCTL-3">
    <title>Starting the postmaster</title>
@@ -260,7 +256,6 @@ Postgres documentation
 </screen>
     stops postmaster. Using the <option>-m</option> switch allows one
     to control <emphasis>how</emphasis> the backend shuts down.
-    <option>-w</option> waits for postmaster to shut down.
    </para>
   </refsect2>
 
@@ -312,6 +307,25 @@ Command line was:
    </para>
   </refsect2>
  </refsect1>
+
+ <refsect1>
+  <title>Bugs</title>
+
+  <para>
+   Waiting for complete start is not a well-defined operation and may
+   fail if access control is set up in way that a local client cannot
+   connect without manual interaction.  It should be avoided.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <para>
+   <xref linkend="app-postmaster">, <citetitle>PostgreSQL Administrator's Guide</citetitle>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file

src/bin/pg_ctl/pg_ctl.sh

@@ -4,11 +4,11 @@
 # pg_ctl.sh--
 #    Start/Stop/Restart/Report status of postmaster
 #
-# Copyright (c) 2000, PostgreSQL Global Development Group
+# Copyright (c) 2001  PostgreSQL Global Development Group
 #
 #
 # IDENTIFICATION
-#    $Header: /cvsroot/pgsql/src/bin/pg_ctl/Attic/pg_ctl.sh,v 1.17 2000/12/30 06:10:43 ishii Exp $
+#    $Header: /cvsroot/pgsql/src/bin/pg_ctl/Attic/pg_ctl.sh,v 1.18 2001/02/08 19:39:24 petere Exp $
 #
 #-------------------------------------------------------------------------
 
@@ -19,20 +19,29 @@ $CMDNAME is a utility to start, stop, restart, and report the status
 of a PostgreSQL server.
 
 Usage:
-  $CMDNAME start   [-w] [-D DATADIR] [-p PATH-TO-POSTMASTER] [-o \"OPTIONS\"]
-  $CMDNAME stop    [-w] [-D DATADIR] [-m SHUTDOWN-MODE]
-  $CMDNAME restart [-w] [-D DATADIR] [-m SHUTDOWN-MODE] [-o \"OPTIONS\"]
+  $CMDNAME start   [-w] [-D DATADIR] [-s] [-l FILENAME] [-o \"OPTIONS\"]
+  $CMDNAME stop    [-W] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]
+  $CMDNAME restart [-w] [-D DATADIR] [-s] [-m SHUTDOWN-MODE] [-o \"OPTIONS\"]
   $CMDNAME status  [-D DATADIR]
 
-Options:
+Common options:
   -D DATADIR            Location of the database storage area
-  -m SHUTDOWN-MODE      May be 'smart', 'fast', or 'immediate'
+  -s                    Only print errors, no informational messages
+  -w                    Wait until operation completes
+  -W                    Do not wait until operation completes
+(The default is to wait for shutdown, but not for start or restart.)
+
+If the -D option is omitted, the environment variable PGDATA is used.
+
+Options for start or restart:
+  -l FILENAME           Write (or append) server log to FILENAME.  The
+                        use of this option is highly recommended.
   -o OPTIONS            Command line options to pass to the postmaster
                         (PostgreSQL server executable)
   -p PATH-TO-POSTMASTER Normally not necessary
-  -w                    Wait until operation completes
 
-If the -D option is omitted, the environment variable PGDATA is used.
+Options for stop or restart:
+  -m SHUTDOWN-MODE      May be 'smart', 'fast', or 'immediate'
 
 Shutdown modes are:
   smart                 Quit after all clients have disconnected
@@ -50,6 +59,9 @@ Try '$CMDNAME --help' for more information."
 bindir='@bindir@'
 VERSION='@VERSION@'
 
+# protect the log file
+umask 077
+
 # Check for echo -n vs echo \c
 
 if echo '\c' | grep -s c >/dev/null 2>&1
@@ -96,8 +108,11 @@ fi
 
 po_path="$PGPATH/postmaster"
 
-# set default shutdown signal
-sig="-TERM"
+wait=
+wait_seconds=60
+logfile=
+silence_echo=
+shutdown_mode=smart
 
 while [ "$#" -gt 0 ]
 do
@@ -114,34 +129,34 @@ do
 	    shift
 	    PGDATA="$1"
 	    ;;
+	-l)
+	    logfile=$2
+	    shift;;
+	-l*)
+	    logfile=`echo "$1" | sed 's/^-l//'`
+	    ;;
+	-m)
+	    shutdown_mode=$2
+	    shift;;
+	-m*)
+	    shutdown_mode=`echo "$1" | sed 's/^-m//'`
+	    ;;
+	-o)
+	    shift
+	    POSTOPTS="$1"
+	    ;;
 	-p)
 	    shift
 	    po_path="$1"
 	    ;;
-	-m)
-	    shift
-	    case $1 in
-		s|smart)
-		    ;;
-		f|fast)
-		    sig="-INT"
-		    ;;
-		i|immediate)
-		    sig="-QUIT"
-		    ;;
-	    *)
-		echo "$CMDNAME: wrong shutdown mode: $1" 1>&2
-		echo "$advice" 1>&2
-		exit 1
-		;;
-	    esac
+	-s)
+	    silence_echo=:
 	    ;;
 	-w)
-	    wait=1
+	    wait=yes
 	    ;;
-	-o)
-	    shift
-	    POSTOPTS="$1"
+	-W)
+	    wait=no
 	    ;;
 	-*)
 	    echo "$CMDNAME: invalid option: $1" 1>&2
@@ -181,20 +196,47 @@ if [ -z "$PGDATA" ];then
     exit 1
 fi
 
+if [ -z "$wait" ]; then
+    case $op in
+	start)      wait=no;;
+	stop)       wait=yes;;
+	restart)    wait=no;;   # must wait on shutdown anyhow
+    esac
+fi
+
+
+case $shutdown_mode in
+    s|smart)
+	sig="-TERM"
+	;;
+    f|fast)
+	sig="-INT"
+	;;
+    i|immediate)
+	sig="-QUIT"
+	;;
+    *)
+	echo "$CMDNAME: invalid shutdown mode: $1" 1>&2
+	echo "$advice" 1>&2
+	exit 1
+	;;
+esac
+
+
 DEFPOSTOPTS=$PGDATA/postmaster.opts.default
 POSTOPTSFILE=$PGDATA/postmaster.opts
 PIDFILE=$PGDATA/postmaster.pid
 
 if [ $op = "status" ];then
     if [ -f $PIDFILE ];then
-	PID=`head -1 $PIDFILE`
+	PID=`sed -n 1p $PIDFILE`
 	if [ $PID -lt 0 ];then
 	    PID=`expr 0 - $PID`
 	    echo "$CMDNAME: postgres is running (pid: $PID)"
 	else
 	    echo "$CMDNAME: postmaster is running (pid: $PID)"
 	    echo "Command line was:"
-	    echo "`cat $POSTOPTSFILE`"
+	    cat "$POSTOPTSFILE"
 	fi
 	exit 0
     else
@@ -205,29 +247,29 @@ fi
 
 if [ $op = "stop" -o $op = "restart" ];then
     if [ -f $PIDFILE ];then
-	PID=`head -1 $PIDFILE`
+	PID=`sed -n 1p $PIDFILE`
 	if [ $PID -lt 0 ];then
 	    PID=`expr 0 - $PID`
-	    echo "$CMDNAME: Cannot restart postmaster. postgres is running (pid: $PID)"
-	    echo "Please terminate postgres and try again"
+	    echo "$CMDNAME: Cannot restart postmaster.  postgres is running (pid: $PID)" 1>&2
+	    echo "Please terminate postgres and try again." 1>&2
 	    exit 1
 	fi
 
 	kill $sig $PID
 
 	# wait for postmaster to shut down
-	if [ "$wait" = 1 -o $op = "restart" ];then
+	if [ "$wait" = yes -o "$op" = restart ];then
 	    cnt=0
-	    $ECHO_N "Waiting for postmaster to shut down.."$ECHO_C
+	    $silence_echo $ECHO_N "waiting for postmaster to shut down..."$ECHO_C
 
 	    while :
 	    do
 		if [ -f $PIDFILE ];then
-		    $ECHO_N "."$ECHO_C
+		    $silence_echo $ECHO_N "."$ECHO_C
 		    cnt=`expr $cnt + 1`
-		    if [ $cnt -gt 60 ];then
-			echo "failed."
-			echo "postmaster does not shut down."
+		    if [ $cnt -gt $wait_seconds ];then
+			$silence_echo echo " failed"
+			echo "$CMDNAME: postmaster does not shut down" 1>&2
 			exit 1
 		    fi
 		else
@@ -235,76 +277,102 @@ if [ $op = "stop" -o $op = "restart" ];then
 		fi
 		sleep 1
 	    done
-	    echo "done."
+	    $silence_echo echo "done"
 	fi
+	$silence_echo echo "postmaster successfully shut down"
 
-	echo "postmaster successfully shut down."
-
-    else
-	echo "$CMDNAME: cannot find $PIDFILE"
-	echo "Is postmaster running?"
+    else # ! -f $PIDFILE
+	echo "$CMDNAME: cannot find $PIDFILE" 1>&2
+	echo "Is postmaster running?" 1>&2
 	if [ $op = "restart" ];then
-	    echo "starting postmaster anyway..."
+	    echo "starting postmaster anyway" 1>&2
 	else
 	    exit 1
 	fi
     fi
-fi
+fi # stop or restart
 
 if [ $op = "start" -o $op = "restart" ];then
     if [ -f $PIDFILE ];then
-	echo "$CMDNAME: It seems another postmaster is running. Trying to start postmaster anyway."
-	pid=`head -1 $PIDFILE`
+	echo "$CMDNAME: It seems another postmaster is running.  Trying to start postmaster anyway." 1>&2
+	pid=`sed -n 1p $PIDFILE`
+    fi
+
+    unset logopt
+    if [ -n "$logfile" ]; then
+        logopt='</dev/null >>$logfile 2>&1'
+    else
+        # when starting without log file, redirect stderr to stdout, so
+        # pg_ctl can be invoked with >$logfile and still have pg_ctl's
+        # stderr on the terminal.
+        logopt='</dev/null 2>&1'
     fi
 
     # no -o given
     if [ -z "$POSTOPTS" ];then
 	if [ $op = "start" ];then
 	    # if we are in start mode, then look for postmaster.opts.default
-	    if [ -f $DEFPOSTOPTS ];then
-		$po_path -D $PGDATA `cat $DEFPOSTOPTS` &
-	    else
-		$po_path -D $PGDATA &
+	    if [ -f $DEFPOSTOPTS ]; then
+		POSTOPTS=`cat $DEFPOSTOPTS`
 	    fi
+	    POSTOPTS="-D $PGDATA $POSTOPTS"
 	else
-	    # if we are in restart mode, then look postmaster.opts
-	    `cat $POSTOPTSFILE` &
+	    # if we are in restart mode, then look for postmaster.opts
+	    set X `cat $POSTOPTSFILE`
+	    shift
+            po_path=$1
+            shift
+	    POSTOPTS=$@
 	fi
-    else
-    # -o given
-	$po_path -D $PGDATA $POSTOPTS &
+    else # -o given
+        POSTOPTS="-D $PGDATA $POSTOPTS"
     fi
 
+    eval '$po_path' '$POSTOPTS' $logopt '&'
+
     if [ -f $PIDFILE ];then
-	if [ "`head -1 $PIDFILE`" = "$pid" ];then
-	    echo "$CMDNAME: Cannot start postmaster. Is another postmaster is running?"
+	if [ "`sed -n 1p $PIDFILE`" = "$pid" ];then
+	    echo "$CMDNAME: cannot start postmaster" 1>&2
+	    echo "Examine the log output." 1>&2
 	    exit 1
         fi
     fi
 
-    # wait for postmaster to start up
-    if [ "$wait" = 1 ];then
+    # wait for postmaster to start
+    if [ "$wait" = yes ];then
 	cnt=0
-	$ECHO_N "Waiting for postmaster to start up.."$ECHO_C
+	$silence_echo $ECHO_N "waiting for postmaster to start..."$ECHO_C
 	while :
 	do
+# FIXME:  This is horribly misconceived.
+# 1) If password authentication is set up, the connection will fail.
+# 2) If a virtual host is set up, the connection may fail.
+# 3) If network traffic filters are set up tight enough, the connection
+#    may fail.
+# 4) When no Unix domain sockets are available, the connection will
+#    fail.  (Using TCP/IP by default ain't better.)
+# 5) When a different port is configured, the connection will fail
+#    or go to the wrong server.
+# 6) If the dynamic loader is not set up correctly (for this user/at
+#    this time), psql will fail (to find libpq).
+# 7) If psql is misconfigured, this may fail.
 	    if "$PGPATH/psql" -l >/dev/null 2>&1
 	    then
 		break;
 	    else
-		$ECHO_N "."$ECHO_C
+		$silence_echo $ECHO_N "."$ECHO_C
 		cnt=`expr $cnt + 1`
-		if [ $cnt -gt 60 ];then
-		    echo "$CMDNAME: postmaster does not start up"
+		if [ $cnt -gt $wait_seconds ];then
+		    $silence_echo echo "failed"
+		    echo "$CMDNAME: postmaster does not start" 1>&2
 		    exit 1
 		fi
 		sleep 1
 	    fi
 	done
-	echo "done"
+	$silence_echo echo "done"
     fi
-
-    echo "postmaster successfully started up"
-fi
+    $silence_echo echo "postmaster successfully started"
+fi # start or restart
 
 exit 0