begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-status.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.2. Connection Status Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-connect.html" title="32.1. Database Connection Control Functions" /><link rel="next" href="libpq-exec.html" title="32.3. Command Execution Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.2. Connection Status Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-connect.html" title="32.1. Database Connection Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-exec.html" title="32.3. Command Execution Functions">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-STATUS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.2. Connection Status Functions <a href="#LIBPQ-STATUS" class="id_link">#</a></h2></div></div></div><p>
   3    These functions can be used to interrogate the status
   4    of an existing database connection object.
   5   </p><div class="tip"><h3 class="title">Tip</h3><p>
   6     <a id="id-1.7.3.9.3.1.1" class="indexterm"></a>
   7     <a id="id-1.7.3.9.3.1.2" class="indexterm"></a>
   8     <span class="application">libpq</span> application programmers should be careful to
   9     maintain the <code class="structname">PGconn</code> abstraction.  Use the accessor
  10     functions described below to get at the contents of <code class="structname">PGconn</code>.
  11     Reference to internal <code class="structname">PGconn</code> fields using
  12     <code class="filename">libpq-int.h</code> is not recommended because they are subject to change
  13     in the future.
  14    </p></div><p>
  15    The following functions return parameter values established at connection.
  16    These values are fixed for the life of the connection.  If a multi-host
  17    connection string is used, the values of <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a>,
  18    <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a>, and <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> can change if a new connection
  19    is established using the same <code class="structname">PGconn</code> object.  Other values
  20    are fixed for the lifetime of the <code class="structname">PGconn</code> object.
  21
  22    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQDB"><span class="term"><code class="function">PQdb</code><a id="id-1.7.3.9.4.6.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQDB" class="id_link">#</a></dt><dd><p>
  23        Returns the database name of the connection.
  24 </p><pre class="synopsis">
  25 char *PQdb(const PGconn *conn);
  26 </pre><p>
  27       </p></dd><dt id="LIBPQ-PQUSER"><span class="term"><code class="function">PQuser</code><a id="id-1.7.3.9.4.6.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQUSER" class="id_link">#</a></dt><dd><p>
  28        Returns the user name of the connection.
  29 </p><pre class="synopsis">
  30 char *PQuser(const PGconn *conn);
  31 </pre><p>
  32       </p></dd><dt id="LIBPQ-PQPASS"><span class="term"><code class="function">PQpass</code><a id="id-1.7.3.9.4.6.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPASS" class="id_link">#</a></dt><dd><p>
  33        Returns the password of the connection.
  34 </p><pre class="synopsis">
  35 char *PQpass(const PGconn *conn);
  36 </pre><p>
  37       </p><p>
  38        <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> will return either the password specified
  39        in the connection parameters, or if there was none and the password
  40        was obtained from the <a class="link" href="libpq-pgpass.html" title="32.16. The Password File">password
  41        file</a>, it will return that.  In the latter case,
  42        if multiple hosts were specified in the connection parameters, it is
  43        not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> until
  44        the connection is established.  The status of the connection can be
  45        checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
  46       </p></dd><dt id="LIBPQ-PQHOST"><span class="term"><code class="function">PQhost</code><a id="id-1.7.3.9.4.6.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQHOST" class="id_link">#</a></dt><dd><p>
  47        Returns the server host name of the active connection.
  48        This can be a host name, an IP address, or a directory path if the
  49        connection is via Unix socket.  (The path case can be distinguished
  50        because it will always be an absolute path, beginning
  51        with <code class="literal">/</code>.)
  52 </p><pre class="synopsis">
  53 char *PQhost(const PGconn *conn);
  54 </pre><p>
  55       </p><p>
  56        If the connection parameters specified both <code class="literal">host</code> and
  57        <code class="literal">hostaddr</code>, then <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> will
  58        return the <code class="literal">host</code> information.  If only
  59        <code class="literal">hostaddr</code> was specified, then that is returned.
  60        If multiple hosts were specified in the connection parameters,
  61        <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> returns the host actually connected to.
  62       </p><p>
  63        <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> returns <code class="symbol">NULL</code> if the
  64        <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
  65        Otherwise, if there is an error producing the host information (perhaps
  66        if the connection has not been fully established or there was an
  67        error), it returns an empty string.
  68       </p><p>
  69        If multiple hosts were specified in the connection parameters, it is
  70        not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> until
  71        the connection is established.  The status of the connection can be
  72        checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
  73       </p></dd><dt id="LIBPQ-PQHOSTADDR"><span class="term"><code class="function">PQhostaddr</code><a id="id-1.7.3.9.4.6.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQHOSTADDR" class="id_link">#</a></dt><dd><p>
  74        Returns the server IP address of the active connection.
  75        This can be the address that a host name resolved to,
  76        or an IP address provided through the <code class="literal">hostaddr</code>
  77        parameter.
  78 </p><pre class="synopsis">
  79 char *PQhostaddr(const PGconn *conn);
  80 </pre><p>
  81       </p><p>
  82        <a class="xref" href="libpq-status.html#LIBPQ-PQHOSTADDR"><code class="function">PQhostaddr</code></a> returns <code class="symbol">NULL</code> if the
  83        <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
  84        Otherwise, if there is an error producing the host information
  85        (perhaps if the connection has not been fully established or
  86        there was an error), it returns an empty string.
  87       </p></dd><dt id="LIBPQ-PQPORT"><span class="term"><code class="function">PQport</code><a id="id-1.7.3.9.4.6.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPORT" class="id_link">#</a></dt><dd><p>
  88        Returns the port of the active connection.
  89
  90 </p><pre class="synopsis">
  91 char *PQport(const PGconn *conn);
  92 </pre><p>
  93       </p><p>
  94        If multiple ports were specified in the connection parameters,
  95        <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> returns the port actually connected to.
  96       </p><p>
  97        <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> returns <code class="symbol">NULL</code> if the
  98        <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
  99        Otherwise, if there is an error producing the port information (perhaps
 100        if the connection has not been fully established or there was an
 101        error), it returns an empty string.
 102       </p><p>
 103        If multiple ports were specified in the connection parameters, it is
 104        not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> until
 105        the connection is established.  The status of the connection can be
 106        checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
 107       </p></dd><dt id="LIBPQ-PQTTY"><span class="term"><code class="function">PQtty</code><a id="id-1.7.3.9.4.6.7.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQTTY" class="id_link">#</a></dt><dd><p>
 108        This function no longer does anything, but it remains for backwards
 109        compatibility.  The function always return an empty string, or
 110        <code class="symbol">NULL</code> if the <em class="parameter"><code>conn</code></em> argument is
 111        <code class="symbol">NULL</code>.
 112
 113 </p><pre class="synopsis">
 114 char *PQtty(const PGconn *conn);
 115 </pre><p>
 116       </p></dd><dt id="LIBPQ-PQOPTIONS"><span class="term"><code class="function">PQoptions</code><a id="id-1.7.3.9.4.6.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQOPTIONS" class="id_link">#</a></dt><dd><p>
 117        Returns the command-line options passed in the connection request.
 118 </p><pre class="synopsis">
 119 char *PQoptions(const PGconn *conn);
 120 </pre><p>
 121       </p></dd></dl></div><p>
 122   </p><p>
 123    The following functions return status data that can change as operations
 124    are executed on the <code class="structname">PGconn</code> object.
 125
 126    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSTATUS"><span class="term"><code class="function">PQstatus</code><a id="id-1.7.3.9.5.2.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSTATUS" class="id_link">#</a></dt><dd><p>
 127        Returns the status of the connection.
 128 </p><pre class="synopsis">
 129 ConnStatusType PQstatus(const PGconn *conn);
 130 </pre><p>
 131       </p><p>
 132        The status can be one of a number of values.  However, only two of
 133        these are seen outside of an asynchronous connection procedure:
 134        <code class="symbol">CONNECTION_OK</code> and
 135        <code class="symbol">CONNECTION_BAD</code>. A good connection to the database
 136        has the status <code class="symbol">CONNECTION_OK</code>.  A failed
 137        connection attempt is signaled by status
 138        <code class="symbol">CONNECTION_BAD</code>.  Ordinarily, an OK status will
 139        remain so until <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>, but a communications
 140        failure might result in the status changing to
 141        <code class="symbol">CONNECTION_BAD</code> prematurely.  In that case the
 142        application could try to recover by calling
 143        <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a>.
 144       </p><p>
 145        See the entry for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>
 146        and <code class="function">PQconnectPoll</code> with regards to other status codes that
 147        might be returned.
 148       </p></dd><dt id="LIBPQ-PQTRANSACTIONSTATUS"><span class="term"><code class="function">PQtransactionStatus</code><a id="id-1.7.3.9.5.2.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQTRANSACTIONSTATUS" class="id_link">#</a></dt><dd><p>
 149        Returns the current in-transaction status of the server.
 150
 151 </p><pre class="synopsis">
 152 PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
 153 </pre><p>
 154
 155        The status can be <code class="literal">PQTRANS_IDLE</code> (currently idle),
 156        <code class="literal">PQTRANS_ACTIVE</code> (a command is in progress),
 157        <code class="literal">PQTRANS_INTRANS</code> (idle, in a valid transaction block),
 158        or <code class="literal">PQTRANS_INERROR</code> (idle, in a failed transaction block).
 159        <code class="literal">PQTRANS_UNKNOWN</code> is reported if the connection is bad.
 160        <code class="literal">PQTRANS_ACTIVE</code> is reported only when a query
 161        has been sent to the server and not yet completed.
 162       </p></dd><dt id="LIBPQ-PQPARAMETERSTATUS"><span class="term"><code class="function">PQparameterStatus</code><a id="id-1.7.3.9.5.2.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPARAMETERSTATUS" class="id_link">#</a></dt><dd><p>
 163        Looks up a current parameter setting of the server.
 164
 165 </p><pre class="synopsis">
 166 const char *PQparameterStatus(const PGconn *conn, const char *paramName);
 167 </pre><p>
 168
 169        Certain parameter values are reported by the server automatically at
 170        connection startup or whenever their values change.
 171        <a class="xref" href="libpq-status.html#LIBPQ-PQPARAMETERSTATUS"><code class="function">PQparameterStatus</code></a> can be used to interrogate these settings.
 172        It returns the current value of a parameter if known, or <code class="symbol">NULL</code>
 173        if the parameter is not known.
 174       </p><p>
 175        Parameters reported as of the current release include:
 176        </p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="varname">application_name</code></td><td><code class="varname">scram_iterations</code></td></tr><tr><td><code class="varname">client_encoding</code></td><td><code class="varname">search_path</code></td></tr><tr><td><code class="varname">DateStyle</code></td><td><code class="varname">server_encoding</code></td></tr><tr><td><code class="varname">default_transaction_read_only</code></td><td><code class="varname">server_version</code></td></tr><tr><td><code class="varname">in_hot_standby</code></td><td><code class="varname">session_authorization</code></td></tr><tr><td><code class="varname">integer_datetimes</code></td><td><code class="varname">standard_conforming_strings</code></td></tr><tr><td><code class="varname">IntervalStyle</code></td><td><code class="varname">TimeZone</code></td></tr><tr><td><code class="varname">is_superuser</code></td><td> </td></tr></table><p>
 177        (<code class="varname">default_transaction_read_only</code> and
 178        <code class="varname">in_hot_standby</code> were not reported by releases before
 179        14; <code class="varname">scram_iterations</code> was not reported by releases
 180        before 16; <code class="varname">search_path</code> was not reported by releases
 181        before 18.)
 182        Note that
 183        <code class="varname">server_version</code>,
 184        <code class="varname">server_encoding</code> and
 185        <code class="varname">integer_datetimes</code>
 186        cannot change after startup.
 187       </p><p>
 188        If no value for <code class="varname">standard_conforming_strings</code> is reported,
 189        applications can assume it is <code class="literal">off</code>, that is, backslashes
 190        are treated as escapes in string literals.  Also, the presence of
 191        this parameter can be taken as an indication that the escape string
 192        syntax (<code class="literal">E'...'</code>) is accepted.
 193       </p><p>
 194        Although the returned pointer is declared <code class="literal">const</code>, it in fact
 195        points to mutable storage associated with the <code class="literal">PGconn</code> structure.
 196        It is unwise to assume the pointer will remain valid across queries.
 197       </p></dd><dt id="LIBPQ-PQFULLPROTOCOLVERSION"><span class="term"><code class="function">PQfullProtocolVersion</code><a id="id-1.7.3.9.5.2.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQFULLPROTOCOLVERSION" class="id_link">#</a></dt><dd><p>
 198        Interrogates the frontend/backend protocol being used.
 199 </p><pre class="synopsis">
 200 int PQfullProtocolVersion(const PGconn *conn);
 201 </pre><p>
 202        Applications might wish to use this function to determine whether certain
 203        features are supported. The result is formed by multiplying the server's
 204        major version number by 10000 and adding the minor version number. For
 205        example, version 3.2 would be returned as 30002, and version 4.0 would
 206        be returned as 40000. Zero is returned if the connection is bad. The 3.0
 207        protocol is supported by <span class="productname">PostgreSQL</span> server
 208        versions 7.4 and above.
 209       </p><p>
 210        The protocol version will not change after connection startup is
 211        complete, but it could theoretically change during a connection reset.
 212       </p></dd><dt id="LIBPQ-PQPROTOCOLVERSION"><span class="term"><code class="function">PQprotocolVersion</code><a id="id-1.7.3.9.5.2.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPROTOCOLVERSION" class="id_link">#</a></dt><dd><p>
 213        Interrogates the frontend/backend protocol major version.
 214 </p><pre class="synopsis">
 215 int PQprotocolVersion(const PGconn *conn);
 216 </pre><p>
 217        Unlike <a class="xref" href="libpq-status.html#LIBPQ-PQFULLPROTOCOLVERSION"><code class="function">PQfullProtocolVersion</code></a>, this returns only
 218        the major protocol version in use, but it is supported by a wider range
 219        of libpq releases back to version 7.4. Currently, the possible values are
 220        3 (3.0 protocol), or zero (connection bad). Prior to release version
 221        14.0, libpq could additionally return 2 (2.0 protocol).
 222       </p></dd><dt id="LIBPQ-PQSERVERVERSION"><span class="term"><code class="function">PQserverVersion</code><a id="id-1.7.3.9.5.2.6.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSERVERVERSION" class="id_link">#</a></dt><dd><p>
 223        Returns an integer representing the server version.
 224 </p><pre class="synopsis">
 225 int PQserverVersion(const PGconn *conn);
 226 </pre><p>
 227       </p><p>
 228        Applications might use this function to determine the version of the
 229        database server they are connected to.  The result is formed by
 230        multiplying the server's major version number by 10000 and adding
 231        the minor version number.  For example, version 10.1 will be
 232        returned as 100001, and version 11.0 will be returned as 110000.
 233        Zero is returned if the connection is bad.
 234       </p><p>
 235        Prior to major version 10, <span class="productname">PostgreSQL</span> used
 236        three-part version numbers in which the first two parts together
 237        represented the major version.  For those
 238        versions, <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a> uses two digits for each
 239        part; for example version 9.1.5 will be returned as 90105, and
 240        version 9.2.0 will be returned as 90200.
 241       </p><p>
 242        Therefore, for purposes of determining feature compatibility,
 243        applications should divide the result of <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a>
 244        by 100 not 10000 to determine a logical major version number.
 245        In all release series, only the last two digits differ between
 246        minor releases (bug-fix releases).
 247       </p></dd><dt id="LIBPQ-PQERRORMESSAGE"><span class="term">
 248       <code class="function">PQerrorMessage</code><a id="id-1.7.3.9.5.2.7.1.2" class="indexterm"></a>
 249       <a id="id-1.7.3.9.5.2.7.1.3" class="indexterm"></a>
 250      </span> <a href="#LIBPQ-PQERRORMESSAGE" class="id_link">#</a></dt><dd><p>
 251        Returns the error message most recently generated by
 252        an operation on the connection.
 253
 254 </p><pre class="synopsis">
 255 char *PQerrorMessage(const PGconn *conn);
 256 </pre><p>
 257       </p><p>
 258        Nearly all <span class="application">libpq</span> functions will set a message for
 259        <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
 260       <code class="function">PQerrorMessage</code>
 261
 262      </a> if they fail.  Note that by
 263        <span class="application">libpq</span> convention, a nonempty
 264        <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE">
 265       <code class="function">PQerrorMessage</code>
 266
 267      </a> result can consist of multiple lines,
 268        and will include a trailing newline. The caller should not free
 269        the result directly. It will be freed when the associated
 270        <code class="structname">PGconn</code> handle is passed to
 271        <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>.  The result string should not be
 272        expected to remain the same across operations on the
 273        <code class="literal">PGconn</code> structure.
 274       </p></dd><dt id="LIBPQ-PQSOCKET"><span class="term"><code class="function">PQsocket</code><a id="id-1.7.3.9.5.2.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSOCKET" class="id_link">#</a></dt><dd><p>
 275        Obtains the file descriptor number of the connection socket to
 276        the server.  A valid descriptor will be greater than or equal
 277        to 0; a result of -1 indicates that no server connection is
 278        currently open.  (This will not change during normal operation,
 279        but could change during connection setup or reset.)
 280
 281 </p><pre class="synopsis">
 282 int PQsocket(const PGconn *conn);
 283 </pre><p>
 284
 285       </p></dd><dt id="LIBPQ-PQBACKENDPID"><span class="term"><code class="function">PQbackendPID</code><a id="id-1.7.3.9.5.2.9.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQBACKENDPID" class="id_link">#</a></dt><dd><p>
 286        Returns the process <acronym class="acronym">ID</acronym> (PID)<a id="id-1.7.3.9.5.2.9.2.1.2" class="indexterm"></a>
 287        of the backend process handling this connection.
 288
 289 </p><pre class="synopsis">
 290 int PQbackendPID(const PGconn *conn);
 291 </pre><p>
 292       </p><p>
 293        The backend <acronym class="acronym">PID</acronym> is useful for debugging
 294        purposes and for comparison to <code class="command">NOTIFY</code>
 295        messages (which include the <acronym class="acronym">PID</acronym> of the
 296        notifying backend process).  Note that the
 297        <acronym class="acronym">PID</acronym> belongs to a process executing on the
 298        database server host, not the local host!
 299       </p></dd><dt id="LIBPQ-PQCONNECTIONNEEDSPASSWORD"><span class="term"><code class="function">PQconnectionNeedsPassword</code><a id="id-1.7.3.9.5.2.10.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTIONNEEDSPASSWORD" class="id_link">#</a></dt><dd><p>
 300        Returns true (1) if the connection authentication method
 301        required a password, but none was available.
 302        Returns false (0) if not.
 303
 304 </p><pre class="synopsis">
 305 int PQconnectionNeedsPassword(const PGconn *conn);
 306 </pre><p>
 307       </p><p>
 308        This function can be applied after a failed connection attempt
 309        to decide whether to prompt the user for a password.
 310       </p></dd><dt id="LIBPQ-PQCONNECTIONUSEDPASSWORD"><span class="term"><code class="function">PQconnectionUsedPassword</code><a id="id-1.7.3.9.5.2.11.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTIONUSEDPASSWORD" class="id_link">#</a></dt><dd><p>
 311        Returns true (1) if the connection authentication method
 312        used a password. Returns false (0) if not.
 313
 314 </p><pre class="synopsis">
 315 int PQconnectionUsedPassword(const PGconn *conn);
 316 </pre><p>
 317       </p><p>
 318        This function can be applied after either a failed or successful
 319        connection attempt to detect whether the server demanded a password.
 320       </p></dd><dt id="LIBPQ-PQCONNECTIONUSEDGSSAPI"><span class="term"><code class="function">PQconnectionUsedGSSAPI</code><a id="id-1.7.3.9.5.2.12.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTIONUSEDGSSAPI" class="id_link">#</a></dt><dd><p>
 321        Returns true (1) if the connection authentication method
 322        used GSSAPI. Returns false (0) if not.
 323
 324 </p><pre class="synopsis">
 325 int PQconnectionUsedGSSAPI(const PGconn *conn);
 326 </pre><p>
 327       </p><p>
 328        This function can be applied to detect whether the connection was
 329        authenticated with GSSAPI.
 330       </p></dd></dl></div><p>
 331   </p><p>
 332     The following functions return information related to SSL. This information
 333     usually doesn't change after a connection is established.
 334
 335     </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSSLINUSE"><span class="term"><code class="function">PQsslInUse</code><a id="id-1.7.3.9.6.1.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSSLINUSE" class="id_link">#</a></dt><dd><p>
 336         Returns true (1) if the connection uses SSL, false (0) if not.
 337
 338 </p><pre class="synopsis">
 339 int PQsslInUse(const PGconn *conn);
 340 </pre><p>
 341       </p></dd><dt id="LIBPQ-PQSSLATTRIBUTE"><span class="term"><code class="function">PQsslAttribute</code><a id="id-1.7.3.9.6.1.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSSLATTRIBUTE" class="id_link">#</a></dt><dd><p>
 342         Returns SSL-related information about the connection.
 343
 344 </p><pre class="synopsis">
 345 const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
 346 </pre><p>
 347       </p><p>
 348        The list of available attributes varies depending on the SSL library
 349        being used and the type of connection.  Returns NULL if the connection
 350        does not use SSL or the specified attribute name is not defined for the
 351        library in use.
 352       </p><p>
 353        The following attributes are commonly available:
 354        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">library</code></span></dt><dd><p>
 355             Name of the SSL implementation in use. (Currently, only
 356             <code class="literal">"OpenSSL"</code> is implemented)
 357            </p></dd><dt><span class="term"><code class="literal">protocol</code></span></dt><dd><p>
 358              SSL/TLS version in use. Common values
 359              are <code class="literal">"TLSv1"</code>, <code class="literal">"TLSv1.1"</code>
 360              and <code class="literal">"TLSv1.2"</code>, but an implementation may
 361              return other strings if some other protocol is used.
 362            </p></dd><dt><span class="term"><code class="literal">key_bits</code></span></dt><dd><p>
 363             Number of key bits used by the encryption algorithm.
 364            </p></dd><dt><span class="term"><code class="literal">cipher</code></span></dt><dd><p>
 365             A short name of the ciphersuite used, e.g.,
 366             <code class="literal">"DHE-RSA-DES-CBC3-SHA"</code>. The names are specific
 367             to each SSL implementation.
 368            </p></dd><dt><span class="term"><code class="literal">compression</code></span></dt><dd><p>
 369             Returns "on" if SSL compression is in use, else it returns "off".
 370            </p></dd><dt><span class="term"><code class="literal">alpn</code></span></dt><dd><p>
 371             Application protocol selected by the TLS Application-Layer
 372             Protocol Negotiation (ALPN) extension.  The only protocol
 373             supported by libpq is <code class="literal">postgresql</code>, so this is
 374             mainly useful for checking whether the server supported ALPN or
 375             not. Empty string if ALPN was not used.
 376            </p></dd></dl></div><p>
 377       </p><p>
 378        As a special case, the <code class="literal">library</code> attribute may be
 379        queried without a connection by passing NULL as
 380        the <code class="literal">conn</code> argument.  The result will be the default
 381        SSL library name, or NULL if <span class="application">libpq</span> was
 382        compiled without any SSL support.  (Prior
 383        to <span class="productname">PostgreSQL</span> version 15, passing NULL as
 384        the <code class="literal">conn</code> argument always resulted in NULL.
 385        Client programs needing to differentiate between the newer and older
 386        implementations of this case may check the
 387        <code class="literal">LIBPQ_HAS_SSL_LIBRARY_DETECTION</code> feature macro.)
 388       </p></dd><dt id="LIBPQ-PQSSLATTRIBUTENAMES"><span class="term"><code class="function">PQsslAttributeNames</code><a id="id-1.7.3.9.6.1.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSSLATTRIBUTENAMES" class="id_link">#</a></dt><dd><p>
 389        Returns an array of SSL attribute names that can be used
 390        in <code class="function">PQsslAttribute()</code>.
 391        The array is terminated by a NULL pointer.
 392 </p><pre class="synopsis">
 393 const char * const * PQsslAttributeNames(const PGconn *conn);
 394 </pre><p>
 395       </p><p>
 396        If <code class="literal">conn</code> is NULL, the attributes available for the
 397        default SSL library are returned, or an empty list
 398        if <span class="application">libpq</span> was compiled without any SSL
 399        support.  If <code class="literal">conn</code> is not NULL, the attributes
 400        available for the SSL library in use for the connection are returned,
 401        or an empty list if the connection is not encrypted.
 402       </p></dd><dt id="LIBPQ-PQSSLSTRUCT"><span class="term"><code class="function">PQsslStruct</code><a id="id-1.7.3.9.6.1.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSSLSTRUCT" class="id_link">#</a></dt><dd><p>
 403        Returns a pointer to an SSL-implementation-specific object describing
 404        the connection.  Returns NULL if the connection is not encrypted
 405        or the requested type of object is not available from the connection's
 406        SSL implementation.
 407 </p><pre class="synopsis">
 408 void *PQsslStruct(const PGconn *conn, const char *struct_name);
 409 </pre><p>
 410       </p><p>
 411        The struct(s) available depend on the SSL implementation in use.
 412        For <span class="productname">OpenSSL</span>, there is one struct,
 413        available under the name <code class="literal">OpenSSL</code>,
 414        and it returns a pointer to
 415        <span class="productname">OpenSSL</span>'s <code class="literal">SSL</code> struct.
 416        To use this function, code along the following lines could be used:
 417 </p><pre class="programlisting">
 418 #include &lt;libpq-fe.h&gt;
 419 #include &lt;openssl/ssl.h&gt;
 420
 421 ...
 422
 423     SSL *ssl;
 424
 425     dbconn = PQconnectdb(...);
 426     ...
 427
 428     ssl = PQsslStruct(dbconn, "OpenSSL");
 429     if (ssl)
 430     {
 431         /* use OpenSSL functions to access ssl */
 432     }
 433 </pre><p>
 434       </p><p>
 435        This structure can be used to verify encryption levels, check server
 436        certificates, and more. Refer to the <span class="productname">OpenSSL</span>
 437        documentation for information about this structure.
 438       </p></dd><dt id="LIBPQ-PQGETSSL"><span class="term"><code class="function">PQgetssl</code><a id="id-1.7.3.9.6.1.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETSSL" class="id_link">#</a></dt><dd><p>
 439        <a id="id-1.7.3.9.6.1.5.2.1.1" class="indexterm"></a>
 440        Returns the SSL structure used in the connection, or NULL
 441        if SSL is not in use.
 442
 443 </p><pre class="synopsis">
 444 void *PQgetssl(const PGconn *conn);
 445 </pre><p>
 446       </p><p>
 447        This function is equivalent to <code class="literal">PQsslStruct(conn, "OpenSSL")</code>. It should
 448        not be used in new applications, because the returned struct is
 449        specific to <span class="productname">OpenSSL</span> and will not be
 450        available if another <acronym class="acronym">SSL</acronym> implementation is used.
 451        To check if a connection uses SSL, call
 452        <a class="xref" href="libpq-status.html#LIBPQ-PQSSLINUSE"><code class="function">PQsslInUse</code></a> instead, and for more details about the
 453        connection, use <a class="xref" href="libpq-status.html#LIBPQ-PQSSLATTRIBUTE"><code class="function">PQsslAttribute</code></a>.
 454       </p></dd></dl></div><p>
 455   </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-connect.html" title="32.1. Database Connection Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-exec.html" title="32.3. Command Execution Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.1. Database Connection Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.3. Command Execution Functions</td></tr></table></div></body></html>