summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/libpq-status.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/sgml/html/libpq-status.html')
-rw-r--r--doc/src/sgml/html/libpq-status.html427
1 files changed, 427 insertions, 0 deletions
diff --git a/doc/src/sgml/html/libpq-status.html b/doc/src/sgml/html/libpq-status.html
new file mode 100644
index 0000000..fb209ee
--- /dev/null
+++ b/doc/src/sgml/html/libpq-status.html
@@ -0,0 +1,427 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!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>34.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="34.1. Database Connection Control Functions" /><link rel="next" href="libpq-exec.html" title="34.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">34.2. Connection Status Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-connect.html" title="34.1. Database Connection Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-exec.html" title="34.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">34.2. Connection Status Functions</h2></div></div></div><p>
+ These functions can be used to interrogate the status
+ of an existing database connection object.
+ </p><div class="tip"><h3 class="title">Tip</h3><p>
+ <a id="id-1.7.3.9.3.1.1" class="indexterm"></a>
+ <a id="id-1.7.3.9.3.1.2" class="indexterm"></a>
+ <span class="application">libpq</span> application programmers should be careful to
+ maintain the <code class="structname">PGconn</code> abstraction. Use the accessor
+ functions described below to get at the contents of <code class="structname">PGconn</code>.
+ Reference to internal <code class="structname">PGconn</code> fields using
+ <code class="filename">libpq-int.h</code> is not recommended because they are subject to change
+ in the future.
+ </p></div><p>
+ The following functions return parameter values established at connection.
+ These values are fixed for the life of the connection. If a multi-host
+ connection string is used, the values of <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a>,
+ <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
+ is established using the same <code class="structname">PGconn</code> object. Other values
+ are fixed for the lifetime of the <code class="structname">PGconn</code> object.
+
+ </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></dt><dd><p>
+ Returns the database name of the connection.
+</p><pre class="synopsis">
+char *PQdb(const PGconn *conn);
+</pre><p>
+ </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></dt><dd><p>
+ Returns the user name of the connection.
+</p><pre class="synopsis">
+char *PQuser(const PGconn *conn);
+</pre><p>
+ </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></dt><dd><p>
+ Returns the password of the connection.
+</p><pre class="synopsis">
+char *PQpass(const PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> will return either the password specified
+ in the connection parameters, or if there was none and the password
+ was obtained from the <a class="link" href="libpq-pgpass.html" title="34.16. The Password File">password
+ file</a>, it will return that. In the latter case,
+ if multiple hosts were specified in the connection parameters, it is
+ not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> until
+ the connection is established. The status of the connection can be
+ checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
+ </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></dt><dd><p>
+ 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
+ with <code class="literal">/</code>.)
+</p><pre class="synopsis">
+char *PQhost(const PGconn *conn);
+</pre><p>
+ </p><p>
+ If the connection parameters specified both <code class="literal">host</code> and
+ <code class="literal">hostaddr</code>, then <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> will
+ return the <code class="literal">host</code> information. If only
+ <code class="literal">hostaddr</code> was specified, then that is returned.
+ If multiple hosts were specified in the connection parameters,
+ <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> returns the host actually connected to.
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> returns <code class="symbol">NULL</code> if the
+ <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
+ 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.
+ </p><p>
+ If multiple hosts were specified in the connection parameters, it is
+ not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> until
+ the connection is established. The status of the connection can be
+ checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
+ </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></dt><dd><p>
+ Returns the server IP address of the active connection.
+ This can be the address that a host name resolved to,
+ or an IP address provided through the <code class="literal">hostaddr</code>
+ parameter.
+</p><pre class="synopsis">
+char *PQhostaddr(const PGconn *conn);
+</pre><p>
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQHOSTADDR"><code class="function">PQhostaddr</code></a> returns <code class="symbol">NULL</code> if the
+ <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
+ 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.
+ </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></dt><dd><p>
+ Returns the port of the active connection.
+
+</p><pre class="synopsis">
+char *PQport(const PGconn *conn);
+</pre><p>
+ </p><p>
+ If multiple ports were specified in the connection parameters,
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> returns the port actually connected to.
+ </p><p>
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> returns <code class="symbol">NULL</code> if the
+ <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.
+ 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.
+ </p><p>
+ If multiple ports were specified in the connection parameters, it is
+ not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> until
+ the connection is established. The status of the connection can be
+ checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
+ </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></dt><dd><p>
+ This function no longer does anything, but it remains for backwards
+ compatibility. The function always return an empty string, or
+ <code class="symbol">NULL</code> if the <em class="parameter"><code>conn</code></em> argument is
+ <code class="symbol">NULL</code>.
+
+</p><pre class="synopsis">
+char *PQtty(const PGconn *conn);
+</pre><p>
+ </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></dt><dd><p>
+ Returns the command-line options passed in the connection request.
+</p><pre class="synopsis">
+char *PQoptions(const PGconn *conn);
+</pre><p>
+ </p></dd></dl></div><p>
+ </p><p>
+ The following functions return status data that can change as operations
+ are executed on the <code class="structname">PGconn</code> object.
+
+ </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></dt><dd><p>
+ Returns the status of the connection.
+</p><pre class="synopsis">
+ConnStatusType PQstatus(const PGconn *conn);
+</pre><p>
+ </p><p>
+ The status can be one of a number of values. However, only two of
+ these are seen outside of an asynchronous connection procedure:
+ <code class="literal">CONNECTION_OK</code> and
+ <code class="literal">CONNECTION_BAD</code>. A good connection to the database
+ has the status <code class="literal">CONNECTION_OK</code>. A failed
+ connection attempt is signaled by status
+ <code class="literal">CONNECTION_BAD</code>. Ordinarily, an OK status will
+ remain so until <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>, but a communications
+ failure might result in the status changing to
+ <code class="literal">CONNECTION_BAD</code> prematurely. In that case the
+ application could try to recover by calling
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQRESET"><code class="function">PQreset</code></a>.
+ </p><p>
+ See the entry for <a class="xref" href="libpq-connect.html#LIBPQ-PQCONNECTSTARTPARAMS"><code class="function">PQconnectStartParams</code></a>, <code class="function">PQconnectStart</code>
+ and <code class="function">PQconnectPoll</code> with regards to other status codes that
+ might be returned.
+ </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></dt><dd><p>
+ Returns the current in-transaction status of the server.
+
+</p><pre class="synopsis">
+PGTransactionStatusType PQtransactionStatus(const PGconn *conn);
+</pre><p>
+
+ The status can be <code class="literal">PQTRANS_IDLE</code> (currently idle),
+ <code class="literal">PQTRANS_ACTIVE</code> (a command is in progress),
+ <code class="literal">PQTRANS_INTRANS</code> (idle, in a valid transaction block),
+ or <code class="literal">PQTRANS_INERROR</code> (idle, in a failed transaction block).
+ <code class="literal">PQTRANS_UNKNOWN</code> is reported if the connection is bad.
+ <code class="literal">PQTRANS_ACTIVE</code> is reported only when a query
+ has been sent to the server and not yet completed.
+ </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></dt><dd><p>
+ Looks up a current parameter setting of the server.
+
+</p><pre class="synopsis">
+const char *PQparameterStatus(const PGconn *conn, const char *paramName);
+</pre><p>
+
+ Certain parameter values are reported by the server automatically at
+ connection startup or whenever their values change.
+ <a class="xref" href="libpq-status.html#LIBPQ-PQPARAMETERSTATUS"><code class="function">PQparameterStatus</code></a> can be used to interrogate these settings.
+ It returns the current value of a parameter if known, or <code class="symbol">NULL</code>
+ if the parameter is not known.
+ </p><p>
+ Parameters reported as of the current release include
+ <code class="varname">server_version</code>,
+ <code class="varname">server_encoding</code>,
+ <code class="varname">client_encoding</code>,
+ <code class="varname">application_name</code>,
+ <code class="varname">default_transaction_read_only</code>,
+ <code class="varname">in_hot_standby</code>,
+ <code class="varname">is_superuser</code>,
+ <code class="varname">session_authorization</code>,
+ <code class="varname">DateStyle</code>,
+ <code class="varname">IntervalStyle</code>,
+ <code class="varname">TimeZone</code>,
+ <code class="varname">integer_datetimes</code>, and
+ <code class="varname">standard_conforming_strings</code>.
+ (<code class="varname">server_encoding</code>, <code class="varname">TimeZone</code>, and
+ <code class="varname">integer_datetimes</code> were not reported by releases before 8.0;
+ <code class="varname">standard_conforming_strings</code> was not reported by releases
+ before 8.1;
+ <code class="varname">IntervalStyle</code> was not reported by releases before 8.4;
+ <code class="varname">application_name</code> was not reported by releases before
+ 9.0;
+ <code class="varname">default_transaction_read_only</code> and
+ <code class="varname">in_hot_standby</code> were not reported by releases before
+ 14.)
+ Note that
+ <code class="varname">server_version</code>,
+ <code class="varname">server_encoding</code> and
+ <code class="varname">integer_datetimes</code>
+ cannot change after startup.
+ </p><p>
+ If no value for <code class="varname">standard_conforming_strings</code> is reported,
+ applications can assume it is <code class="literal">off</code>, that is, backslashes
+ are treated as escapes in string literals. Also, the presence of
+ this parameter can be taken as an indication that the escape string
+ syntax (<code class="literal">E'...'</code>) is accepted.
+ </p><p>
+ Although the returned pointer is declared <code class="literal">const</code>, it in fact
+ points to mutable storage associated with the <code class="literal">PGconn</code> structure.
+ It is unwise to assume the pointer will remain valid across queries.
+ </p></dd><dt id="LIBPQ-PQPROTOCOLVERSION"><span class="term"><code class="function">PQprotocolVersion</code><a id="id-1.7.3.9.5.2.4.1.2" class="indexterm"></a></span></dt><dd><p>
+ Interrogates the frontend/backend protocol being used.
+</p><pre class="synopsis">
+int PQprotocolVersion(const PGconn *conn);
+</pre><p>
+ Applications might wish to use this function to determine whether certain
+ features are supported. Currently, the possible values are 3
+ (3.0 protocol), or zero (connection bad). The protocol version will
+ not change after connection startup is complete, but it could
+ theoretically change during a connection reset. The 3.0 protocol is
+ supported by <span class="productname">PostgreSQL</span> server versions 7.4
+ and above.
+ </p></dd><dt id="LIBPQ-PQSERVERVERSION"><span class="term"><code class="function">PQserverVersion</code><a id="id-1.7.3.9.5.2.5.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns an integer representing the server version.
+</p><pre class="synopsis">
+int PQserverVersion(const PGconn *conn);
+</pre><p>
+ </p><p>
+ Applications might use this function to determine the version of the
+ database server they are connected to. The result is formed by
+ multiplying the server's major version number by 10000 and adding
+ the minor version number. For example, version 10.1 will be
+ returned as 100001, and version 11.0 will be returned as 110000.
+ Zero is returned if the connection is bad.
+ </p><p>
+ Prior to major version 10, <span class="productname">PostgreSQL</span> used
+ three-part version numbers in which the first two parts together
+ represented the major version. For those
+ versions, <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a> uses two digits for each
+ part; for example version 9.1.5 will be returned as 90105, and
+ version 9.2.0 will be returned as 90200.
+ </p><p>
+ Therefore, for purposes of determining feature compatibility,
+ applications should divide the result of <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a>
+ by 100 not 10000 to determine a logical major version number.
+ In all release series, only the last two digits differ between
+ minor releases (bug-fix releases).
+ </p></dd><dt id="LIBPQ-PQERRORMESSAGE"><span class="term"><code class="function">PQerrorMessage</code><a id="id-1.7.3.9.5.2.6.1.2" class="indexterm"></a></span></dt><dd><p>
+ <a id="id-1.7.3.9.5.2.6.2.1.1" class="indexterm"></a> Returns the error message
+ most recently generated by an operation on the connection.
+
+</p><pre class="synopsis">
+char *PQerrorMessage(const PGconn *conn);
+</pre><p>
+
+ </p><p>
+ Nearly all <span class="application">libpq</span> functions will set a message for
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> if they fail. Note that by
+ <span class="application">libpq</span> convention, a nonempty
+ <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> result can consist of multiple lines,
+ and will include a trailing newline. The caller should not free
+ the result directly. It will be freed when the associated
+ <code class="structname">PGconn</code> handle is passed to
+ <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>. The result string should not be
+ expected to remain the same across operations on the
+ <code class="literal">PGconn</code> structure.
+ </p></dd><dt id="LIBPQ-PQSOCKET"><span class="term"><code class="function">PQsocket</code><a id="id-1.7.3.9.5.2.7.1.2" class="indexterm"></a></span></dt><dd><p>
+ Obtains the file descriptor number of the connection socket to
+ the server. A valid descriptor will be greater than or equal
+ to 0; a result of -1 indicates that no server connection is
+ currently open. (This will not change during normal operation,
+ but could change during connection setup or reset.)
+
+</p><pre class="synopsis">
+int PQsocket(const PGconn *conn);
+</pre><p>
+
+ </p></dd><dt id="LIBPQ-PQBACKENDPID"><span class="term"><code class="function">PQbackendPID</code><a id="id-1.7.3.9.5.2.8.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns the process <acronym class="acronym">ID</acronym> (PID)<a id="id-1.7.3.9.5.2.8.2.1.2" class="indexterm"></a>
+ of the backend process handling this connection.
+
+</p><pre class="synopsis">
+int PQbackendPID(const PGconn *conn);
+</pre><p>
+ </p><p>
+ The backend <acronym class="acronym">PID</acronym> is useful for debugging
+ purposes and for comparison to <code class="command">NOTIFY</code>
+ messages (which include the <acronym class="acronym">PID</acronym> of the
+ notifying backend process). Note that the
+ <acronym class="acronym">PID</acronym> belongs to a process executing on the
+ database server host, not the local host!
+ </p></dd><dt id="LIBPQ-PQCONNECTIONNEEDSPASSWORD"><span class="term"><code class="function">PQconnectionNeedsPassword</code><a id="id-1.7.3.9.5.2.9.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns true (1) if the connection authentication method
+ required a password, but none was available.
+ Returns false (0) if not.
+
+</p><pre class="synopsis">
+int PQconnectionNeedsPassword(const PGconn *conn);
+</pre><p>
+ </p><p>
+ This function can be applied after a failed connection attempt
+ to decide whether to prompt the user for a password.
+ </p></dd><dt id="LIBPQ-PQCONNECTIONUSEDPASSWORD"><span class="term"><code class="function">PQconnectionUsedPassword</code><a id="id-1.7.3.9.5.2.10.1.2" class="indexterm"></a></span></dt><dd><p>
+ Returns true (1) if the connection authentication method
+ used a password. Returns false (0) if not.
+
+</p><pre class="synopsis">
+int PQconnectionUsedPassword(const PGconn *conn);
+</pre><p>
+ </p><p>
+ This function can be applied after either a failed or successful
+ connection attempt to detect whether the server demanded a password.
+ </p></dd></dl></div><p>
+ </p><p>
+ The following functions return information related to SSL. This information
+ usually doesn't change after a connection is established.
+
+ </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></dt><dd><p>
+ Returns true (1) if the connection uses SSL, false (0) if not.
+
+</p><pre class="synopsis">
+int PQsslInUse(const PGconn *conn);
+</pre><p>
+ </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></dt><dd><p>
+ Returns SSL-related information about the connection.
+
+</p><pre class="synopsis">
+const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
+</pre><p>
+ </p><p>
+ The list of available attributes varies depending on the SSL library
+ being used and the type of connection. Returns NULL if the connection
+ does not use SSL or the specified attribute name is not defined for the
+ library in use.
+ </p><p>
+ The following attributes are commonly available:
+ </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">library</code></span></dt><dd><p>
+ Name of the SSL implementation in use. (Currently, only
+ <code class="literal">"OpenSSL"</code> is implemented)
+ </p></dd><dt><span class="term"><code class="literal">protocol</code></span></dt><dd><p>
+ SSL/TLS version in use. Common values
+ are <code class="literal">"TLSv1"</code>, <code class="literal">"TLSv1.1"</code>
+ and <code class="literal">"TLSv1.2"</code>, but an implementation may
+ return other strings if some other protocol is used.
+ </p></dd><dt><span class="term"><code class="literal">key_bits</code></span></dt><dd><p>
+ Number of key bits used by the encryption algorithm.
+ </p></dd><dt><span class="term"><code class="literal">cipher</code></span></dt><dd><p>
+ A short name of the ciphersuite used, e.g.,
+ <code class="literal">"DHE-RSA-DES-CBC3-SHA"</code>. The names are specific
+ to each SSL implementation.
+ </p></dd><dt><span class="term"><code class="literal">compression</code></span></dt><dd><p>
+ Returns "on" if SSL compression is in use, else it returns "off".
+ </p></dd></dl></div><p>
+ </p><p>
+ As a special case, the <code class="literal">library</code> attribute may be
+ queried without a connection by passing NULL as
+ the <code class="literal">conn</code> argument. The result will be the default
+ SSL library name, or NULL if <span class="application">libpq</span> was
+ compiled without any SSL support. (Prior
+ to <span class="productname">PostgreSQL</span> version 15, passing NULL as
+ the <code class="literal">conn</code> argument always resulted in NULL.
+ Client programs needing to differentiate between the newer and older
+ implementations of this case may check the
+ <code class="literal">LIBPQ_HAS_SSL_LIBRARY_DETECTION</code> feature macro.)
+ </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></dt><dd><p>
+ Returns an array of SSL attribute names available.
+ The array is terminated by a NULL pointer.
+</p><pre class="synopsis">
+const char * const * PQsslAttributeNames(const PGconn *conn);
+</pre><p>
+ </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></dt><dd><p>
+ Returns a pointer to an SSL-implementation-specific object describing
+ the connection. Returns NULL if the connection is not encrypted
+ or the requested type of object is not available from the connection's
+ SSL implementation.
+</p><pre class="synopsis">
+void *PQsslStruct(const PGconn *conn, const char *struct_name);
+</pre><p>
+ </p><p>
+ The struct(s) available depend on the SSL implementation in use.
+ For <span class="productname">OpenSSL</span>, there is one struct,
+ available under the name <code class="literal">OpenSSL</code>,
+ and it returns a pointer to
+ <span class="productname">OpenSSL</span>'s <code class="literal">SSL</code> struct.
+ To use this function, code along the following lines could be used:
+</p><pre class="programlisting">
+#include &lt;libpq-fe.h&gt;
+#include &lt;openssl/ssl.h&gt;
+
+...
+
+ SSL *ssl;
+
+ dbconn = PQconnectdb(...);
+ ...
+
+ ssl = PQsslStruct(dbconn, "OpenSSL");
+ if (ssl)
+ {
+ /* use OpenSSL functions to access ssl */
+ }
+</pre><p>
+ </p><p>
+ This structure can be used to verify encryption levels, check server
+ certificates, and more. Refer to the <span class="productname">OpenSSL</span>
+ documentation for information about this structure.
+ </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></dt><dd><p>
+ <a id="id-1.7.3.9.6.1.5.2.1.1" class="indexterm"></a>
+ Returns the SSL structure used in the connection, or NULL
+ if SSL is not in use.
+
+</p><pre class="synopsis">
+void *PQgetssl(const PGconn *conn);
+</pre><p>
+ </p><p>
+ This function is equivalent to <code class="literal">PQsslStruct(conn, "OpenSSL")</code>. It should
+ not be used in new applications, because the returned struct is
+ specific to <span class="productname">OpenSSL</span> and will not be
+ available if another <acronym class="acronym">SSL</acronym> implementation is used.
+ To check if a connection uses SSL, call
+ <a class="xref" href="libpq-status.html#LIBPQ-PQSSLINUSE"><code class="function">PQsslInUse</code></a> instead, and for more details about the
+ connection, use <a class="xref" href="libpq-status.html#LIBPQ-PQSSLATTRIBUTE"><code class="function">PQsslAttribute</code></a>.
+ </p></dd></dl></div><p>
+ </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="34.1. Database Connection Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-exec.html" title="34.3. Command Execution Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.1. Database Connection Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.3. Command Execution Functions</td></tr></table></div></body></html> \ No newline at end of file