libpq: PQhost to return active connected host or hostaddr

Previously, PQhost didn't return the connected host details when the
connection type was CHT_HOST_ADDRESS (i.e., via hostaddr).  Instead, it
returned the complete host connection parameter (which could contain
multiple hosts) or the default host details, which was confusing and
arguably incorrect.

Change this to return the actually connected host or hostaddr
irrespective of the connection type.  When hostaddr but no host was
specified, hostaddr is now returned.  Never return the original host
connection parameter, and document that PQhost cannot be relied on
before the connection is established.

PQport is similarly changed to always return the active connection port
and never the original connection parameter.

Back-patch of commit 1944cdc98273dbb8439ad9b387ca2858531afcf0
into the v10 branch.

Author: Hari Babu <kommi.haribabu@gmail.com>
Reviewed-by: Michael Paquier <michael@paquier.xyz>
Reviewed-by: Kyotaro HORIGUCHI <horiguchi.kyotaro@lab.ntt.co.jp>
Reviewed-by: David G. Johnston <david.g.johnston@gmail.com>

1 files changed, 46 insertions, 2 deletions

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 966fc171626..e05acbd28b3 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1619,7 +1619,7 @@ char *PQpass(const PGconn *conn);
 
      <listitem>
       <para>
-       Returns the server host name of the connection.
+       Returns the server host name of the active connection.
        This can be a host name, an IP address, or a directory path if the
        connection is via Unix socket.  (The path case can be distinguished
        because it will always be an absolute path, beginning
@@ -1628,6 +1628,30 @@ char *PQpass(const PGconn *conn);
 char *PQhost(const PGconn *conn);
 </synopsis>
       </para>
+
+      <para>
+       If the connection parameters specified both <literal>host</literal> and
+       <literal>hostaddr</literal>, then <function>PQhost</function> will
+       return the <literal>host</literal> information.  If only
+       <literal>hostaddr</literal> was specified, then that is returned.
+       If multiple hosts were specified in the connection parameters,
+       <function>PQhost</function> returns the host actually connected to.
+      </para>
+
+      <para>
+       <function>PQhost</function> returns <symbol>NULL</symbol> if the
+       <parameter>conn</parameter> argument is <symbol>NULL</symbol>.
+       Otherwise, if there is an error producing the host information (perhaps
+       if the connection has not been fully established or there was an
+       error), it returns an empty string.
+      </para>
+
+      <para>
+       If multiple hosts were specified in the connection parameters, it is
+       not possible to rely on the result of <function>PQhost</function> until
+       the connection is established.  The status of the connection can be
+       checked using the function <function>PQstatus</function>.
+      </para>
      </listitem>
     </varlistentry>
 
@@ -1641,12 +1665,32 @@ char *PQhost(const PGconn *conn);
 
      <listitem>
       <para>
-       Returns the port of the connection.
+       Returns the port of the active connection.
 
 <synopsis>
 char *PQport(const PGconn *conn);
 </synopsis>
       </para>
+
+      <para>
+       If multiple ports were specified in the connection parameters,
+       <function>PQport</function> returns the port actually connected to.
+      </para>
+
+      <para>
+       <function>PQport</function> returns <symbol>NULL</symbol> if the
+       <parameter>conn</parameter> argument is <symbol>NULL</symbol>.
+       Otherwise, if there is an error producing the port information (perhaps
+       if the connection has not been fully established or there was an
+       error), it returns an empty string.
+      </para>
+
+      <para>
+       If multiple ports were specified in the connection parameters, it is
+       not possible to rely on the result of <function>PQport</function> until
+       the connection is established.  The status of the connection can be
+       checked using the function <function>PQstatus</function>.
+      </para>
      </listitem>
     </varlistentry>