diff options
Diffstat (limited to 'doc/src/sgml/html/libpq-status.html')
| -rw-r--r-- | doc/src/sgml/html/libpq-status.html | 420 |
1 files changed, 420 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..ee8fab4 --- /dev/null +++ b/doc/src/sgml/html/libpq-status.html @@ -0,0 +1,420 @@ +<?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>33.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 V1.79.1" /><link rel="prev" href="libpq-connect.html" title="33.1. Database Connection Control Functions" /><link rel="next" href="libpq-exec.html" title="33.3. Command Execution Functions" /></head><body id="docContent" class="container-fluid col-10"><div xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">33.2. Connection Status Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-connect.html" title="33.1. Database Connection Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 33. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 33. <span xmlns="http://www.w3.org/1999/xhtml" class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-exec.html" title="33.3. Command Execution Functions">Next</a></td></tr></table><hr></hr></div><div class="sect1" id="LIBPQ-STATUS"><div class="titlepage"><div><div><h2 class="title" style="clear: both">33.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="33.15. 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> + Returns the debug <acronym class="acronym">TTY</acronym> of the connection. + (This is obsolete, since the server no longer pays attention + to the <acronym class="acronym">TTY</acronym> setting, but the function remains + for backward compatibility.) + +</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">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.) + 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> + Pre-3.0-protocol servers do not report parameter settings, but + <span class="application">libpq</span> includes logic to obtain values for + <code class="varname">server_version</code> and <code class="varname">client_encoding</code> anyway. + Applications are encouraged to use <a class="xref" href="libpq-status.html#LIBPQ-PQPARAMETERSTATUS"><code class="function">PQparameterStatus</code></a> + rather than <span class="foreignphrase"><em class="foreignphrase">ad hoc</em></span> code to determine these values. + (Beware however that on a pre-3.0 connection, changing + <code class="varname">client_encoding</code> via <code class="command">SET</code> after connection + startup will not be reflected by <a class="xref" href="libpq-status.html#LIBPQ-PQPARAMETERSTATUS"><code class="function">PQparameterStatus</code></a>.) + For <code class="varname">server_version</code>, see also + <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a>, which returns the information in a + numeric form that is much easier to compare against. + </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 2 (2.0 + protocol), 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 + will normally be used when communicating with + <span class="productname">PostgreSQL</span> 7.4 or later servers; pre-7.4 servers + support only protocol 2.0. (Protocol 1.0 is obsolete and not + supported by <span class="application">libpq</span>.) + </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. If an attribute is not + available, returns NULL. + </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> + If SSL compression is in use, returns the name of the compression + algorithm, or "on" if compression is used but the algorithm is + not known. If compression is not in use, returns "off". + </p></dd></dl></div><p> + </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> + Return 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> + Return a pointer to an SSL-implementation-specific object describing + the connection. +</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 OpenSSL, there is one struct, available under the name "OpenSSL", + and it returns a pointer to the OpenSSL <code class="literal">SSL</code> struct. + To use this function, code along the following lines could be used: +</p><pre class="programlisting"> +#include <libpq-fe.h> +#include <openssl/ssl.h> + +... + + 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 OpenSSL and will not be available if another SSL + 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 xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-connect.html" title="33.1. Database Connection Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 33. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-exec.html" title="33.3. Command Execution Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">33.1. Database Connection Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 13.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 33.3. Command Execution Functions</td></tr></table></div></body></html>
\ No newline at end of file |