Rewrite PQping to be more like what we agreed to last week.

Basically, we want to distinguish all cases where the connection was
not made from those where it was.  A convenient proxy for this is to
see if we got a message with a SQLSTATE code back from the postmaster.
This presumes that the postmaster will always send us a SQLSTATE in
a failure message, which is true for 7.4 and later postmasters in
every case except fork failure.  (We could possibly complicate the
postmaster code to do something about that, but it seems not worth
the trouble, especially since pg_ctl's response for that case should
be to keep waiting anyway.)

If we did get a SQLSTATE from the postmaster, there are basically only
two cases, as per last week's discussion: ERRCODE_CANNOT_CONNECT_NOW
and everything else.  Any other error code implies that the postmaster
is in principle willing to accept connections, it just didn't like or
couldn't handle this particular request.  We want to make a special
case for ERRCODE_CANNOT_CONNECT_NOW so that "pg_ctl start -w" knows
it should keep waiting.

In passing, pick names for the enum constants that are a tad less
likely to present collision hazards in future.

1 files changed, 84 insertions, 68 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index d2a48113157..18199b06ce9 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1060,6 +1060,90 @@ PostgresPollingStatusType PQresetPoll(PGconn *conn);
      </listitem>
     </varlistentry>
 
+    <varlistentry id="libpq-pqpingparams">
+     <term><function>PQpingParams</function><indexterm><primary>PQpingParams</></></term>
+     <listitem>
+      <para>
+       <function>PQpingParams</function> reports the status of the
+       server.  It accepts connection parameters identical to those of
+       <function>PQconnectdbParams</>, described above.  It is not, however,
+       necessary to supply correct user name, password, or database name
+       values to obtain the server status.
+
+<synopsis>
+PGPing PQpingParams(const char **keywords, const char **values, int expand_dbname);
+</synopsis>
+
+       The function returns one of the following values:
+
+       <variablelist>
+        <varlistentry id="libpq-pqpingparams-pqping-ok">
+         <term><literal>PQPING_OK</literal></term>
+         <listitem>
+          <para>
+           The server is running and appears to be accepting connections.
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry id="libpq-pqpingparams-pqping-reject">
+         <term><literal>PQPING_REJECT</literal></term>
+         <listitem>
+          <para>
+           The server is running but is in a state that disallows connections
+           (startup, shutdown, or crash recovery).
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry id="libpq-pqpingparams-pqping-no-response">
+         <term><literal>PQPING_NO_RESPONSE</literal></term>
+         <listitem>
+          <para>
+           The server could not be contacted.
+          </para>
+         </listitem>
+        </varlistentry>
+
+        <varlistentry id="libpq-pqpingparams-pqping-no-attempt">
+         <term><literal>PQPING_NO_ATTEMPT</literal></term>
+         <listitem>
+          <para>
+           No attempt was made to contact the server, because the supplied
+           parameters were incorrect or there was some client-side problem
+           (for example, out of memory).
+          </para>
+         </listitem>
+        </varlistentry>
+       </variablelist>
+
+      </para>
+
+     </listitem>
+    </varlistentry>
+
+    <varlistentry id="libpq-pqping">
+     <term><function>PQping</function><indexterm><primary>PQping</></></term>
+     <listitem>
+      <para>
+       <function>PQping</function> reports the status of the
+       server.  It accepts connection parameters identical to those of
+       <function>PQconnectdb</>, described above.  It is not, however,
+       necessary to supply correct user name, password, or database name
+       values to obtain the server status.
+
+<synopsis>
+PGPing PQping(const char *conninfo);
+</synopsis>
+      </para>
+
+      <para>
+       The return values are the same as for <function>PQpingParams</>.
+      </para>
+
+     </listitem>
+    </varlistentry>
+
    </variablelist>
   </para>
  </sect1>
@@ -1511,74 +1595,6 @@ int PQbackendPID(const PGconn *conn);
      </listitem>
     </varlistentry>
 
-    <varlistentry id="libpq-pqpingparams">
-     <term><function>PQpingParams</function><indexterm><primary>PQpingParams</></></term>
-     <listitem>
-      <para>
-       <function>PQpingParams</function> indicates the status of the
-       server.  The currently recognized parameter key words are the
-       same as <function>PQconnectParams</>.
-
-<synopsis>
-PGPing PQpingParams(const char **keywords, const char **values, int expand_dbname);
-</synopsis>
-
-       It returns one of the following values:
-
-       <variablelist>
-        <varlistentry id="libpq-pqpingparams-pqaccess">
-         <term><literal>PQACCESS</literal></term>
-         <listitem>
-          <para>
-           The server is running and allows access.
-          </para>
-         </listitem>
-        </varlistentry>
-
-        <varlistentry id="libpq-pqpingparams-pqreject">
-         <term><literal>PQREJECT</literal></term>
-         <listitem>
-          <para>
-           The server is running but rejected a connection request.
-          </para>
-         </listitem>
-        </varlistentry>
-
-        <varlistentry id="libpq-pqpingparams-pqnoresponse">
-         <term><literal>PQNORESPONSE</literal></term>
-         <listitem>
-          <para>
-           The server did not respond.
-          </para>
-         </listitem>
-        </varlistentry>
-       </variablelist>
-
-      </para>
-
-     </listitem>
-    </varlistentry>
-
-    <varlistentry id="libpq-pqping">
-     <term><function>PQping</function><indexterm><primary>PQping</></></term>
-     <listitem>
-      <para>
-       Returns the status of the server.
-
-<synopsis>
-PGPing PQping(const char *conninfo);
-</synopsis>
-      </para>
-
-      <para>
-       This function uses the same <literal>conninfo</literal> parameter
-       key words as <function>PQconnectdb</>.  It returns the same
-       values as <function>PQpingParams</> above.
-      </para>
-
-     </listitem>
-    </varlistentry>
-
     <varlistentry id="libpq-pqconnectionneedspassword">
      <term><function>PQconnectionNeedsPassword</function><indexterm><primary>PQconnectionNeedsPassword</></></term>
      <listitem>