Add missing connection statuses to docs

The list of connection statuses that PQstatus might return during an
asynchronous connection attempt was outdated:

1. CONNECTION_SETENV is never returned anymore and is only part of the
   enum for backwards compatibility, so remove it from the docs.
2. CONNECTION_CHECK_STANDBY and CONNECTION_GSS_STARTUP were not listed,
   so add them.

CONNECTION_NEEDED and CONNECTION_CHECK_TARGET are not listed in the docs
on purpose, since these are internal states that can never be observed
by a caller of PQstatus.

Author: Jelte Fennema-Nio <postgres@jeltef.nl>
Discussion: https://postgr.es/m/CAGECzQRb21spiiykQ48rzz8w+Hcykz+mB2_hxR65D9Qk6nnw=w@mail.gmail.com

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 1d8998efb2a8ed27b69487d887a7b9e3db55ccba..a2bbf33d029ffeb2d3e8822a526299402d07eafb 100644 (file)
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -428,11 +428,11 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
          </listitem>
         </varlistentry>
 
-        <varlistentry id="libpq-connection-setenv">
-         <term><symbol>CONNECTION_SETENV</symbol></term>
+        <varlistentry id="libpq-connection-gss-startup">
+         <term><symbol>CONNECTION_GSS_STARTUP</symbol></term>
          <listitem>
           <para>
-           Negotiating environment-driven parameter settings.
+           Negotiating GSS encryption.
           </para>
          </listitem>
         </varlistentry>
@@ -446,6 +446,15 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
          </listitem>
         </varlistentry>
 
+        <varlistentry id="libpq-connection-check-standby">
+         <term><symbol>CONNECTION_CHECK_STANDBY</symbol></term>
+         <listitem>
+          <para>
+           Checking if connection is to a server in standby mode.
+          </para>
+         </listitem>
+        </varlistentry>
+
         <varlistentry id="libpq-connection-consume">
          <term><symbol>CONNECTION_CONSUME</symbol></term>
          <listitem>

diff --git a/src/interfaces/libpq/libpq-fe.h b/src/interfaces/libpq/libpq-fe.h
index defc415fa3fb8e380cad27a62356819c229137b8..2c06044a75e27128f2b6c19d1d747bb8ea8e2c93 100644 (file)
--- a/src/interfaces/libpq/libpq-fe.h
+++ b/src/interfaces/libpq/libpq-fe.h
@@ -73,11 +73,12 @@ typedef enum
                                 * backend startup. */
    CONNECTION_SETENV,          /* This state is no longer used. */
    CONNECTION_SSL_STARTUP,     /* Negotiating SSL. */
-   CONNECTION_NEEDED,          /* Internal state: connect() needed */
+   CONNECTION_NEEDED,          /* Internal state: connect() needed. */
    CONNECTION_CHECK_WRITABLE,  /* Checking if session is read-write. */
    CONNECTION_CONSUME,         /* Consuming any extra messages. */
    CONNECTION_GSS_STARTUP,     /* Negotiating GSSAPI. */
-   CONNECTION_CHECK_TARGET,    /* Checking target server properties. */
+   CONNECTION_CHECK_TARGET,    /* Internal state: checking target server
+                                * properties. */
    CONNECTION_CHECK_STANDBY    /* Checking if server is in standby mode. */
 } ConnStatusType;