codekingpro/portable-devtools
114k
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>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 16.3 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 <a href="#LIBPQ-STATUS" class="id_link">#</a></h2></div></div></div><p>3 These functions can be used to interrogate the status4 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 to9 maintain the <code class="structname">PGconn</code> abstraction. Use the accessor10 functions described below to get at the contents of <code class="structname">PGconn</code>.11 Reference to internal <code class="structname">PGconn</code> fields using12 <code class="filename">libpq-int.h</code> is not recommended because they are subject to change13 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-host17 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 connection19 is established using the same <code class="structname">PGconn</code> object. Other values20 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">25char *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">30char *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">35char *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 specified39 in the connection parameters, or if there was none and the password40 was obtained from the <a class="link" href="libpq-pgpass.html" title="34.16. The Password File">password41 file</a>, it will return that. In the latter case,42 if multiple hosts were specified in the connection parameters, it is43 not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> until44 the connection is established. The status of the connection can be45 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 the49 connection is via Unix socket. (The path case can be distinguished50 because it will always be an absolute path, beginning51 with <code class="literal">/</code>.)52</p><pre class="synopsis">53char *PQhost(const PGconn *conn);54</pre><p>55 </p><p>56 If the connection parameters specified both <code class="literal">host</code> and57 <code class="literal">hostaddr</code>, then <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> will58 return the <code class="literal">host</code> information. If only59 <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 the64 <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 (perhaps66 if the connection has not been fully established or there was an67 error), it returns an empty string.68 </p><p>69 If multiple hosts were specified in the connection parameters, it is70 not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQHOST"><code class="function">PQhost</code></a> until71 the connection is established. The status of the connection can be72 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">79char *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 the83 <em class="parameter"><code>conn</code></em> argument is <code class="symbol">NULL</code>.84 Otherwise, if there is an error producing the host information85 (perhaps if the connection has not been fully established or86 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">91char *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 the98 <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 (perhaps100 if the connection has not been fully established or there was an101 error), it returns an empty string.102 </p><p>103 If multiple ports were specified in the connection parameters, it is104 not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPORT"><code class="function">PQport</code></a> until105 the connection is established. The status of the connection can be106 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 backwards109 compatibility. The function always return an empty string, or110 <code class="symbol">NULL</code> if the <em class="parameter"><code>conn</code></em> argument is111 <code class="symbol">NULL</code>.112 113</p><pre class="synopsis">114char *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">119char *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 operations124 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">129ConnStatusType PQstatus(const PGconn *conn);130</pre><p>131 </p><p>132 The status can be one of a number of values. However, only two of133 these are seen outside of an asynchronous connection procedure:134 <code class="literal">CONNECTION_OK</code> and135 <code class="literal">CONNECTION_BAD</code>. A good connection to the database136 has the status <code class="literal">CONNECTION_OK</code>. A failed137 connection attempt is signaled by status138 <code class="literal">CONNECTION_BAD</code>. Ordinarily, an OK status will139 remain so until <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>, but a communications140 failure might result in the status changing to141 <code class="literal">CONNECTION_BAD</code> prematurely. In that case the142 application could try to recover by calling143 <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 that147 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">152PGTransactionStatusType 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 query161 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">166const char *PQparameterStatus(const PGconn *conn, const char *paramName);167</pre><p>168 169 Certain parameter values are reported by the server automatically at170 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">is_superuser</code></td></tr><tr><td><code class="varname">client_encoding</code></td><td><code class="varname">scram_iterations</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></table><p>177 (<code class="varname">server_encoding</code>, <code class="varname">TimeZone</code>, and178 <code class="varname">integer_datetimes</code> were not reported by releases before 8.0;179 <code class="varname">standard_conforming_strings</code> was not reported by releases180 before 8.1;181 <code class="varname">IntervalStyle</code> was not reported by releases before 8.4;182 <code class="varname">application_name</code> was not reported by releases before183 9.0;184 <code class="varname">default_transaction_read_only</code> and185 <code class="varname">in_hot_standby</code> were not reported by releases before186 14; <code class="varname">scram_iterations</code> was not reported by releases187 before 16.)188 Note that189 <code class="varname">server_version</code>,190 <code class="varname">server_encoding</code> and191 <code class="varname">integer_datetimes</code>192 cannot change after startup.193 </p><p>194 If no value for <code class="varname">standard_conforming_strings</code> is reported,195 applications can assume it is <code class="literal">off</code>, that is, backslashes196 are treated as escapes in string literals. Also, the presence of197 this parameter can be taken as an indication that the escape string198 syntax (<code class="literal">E'...'</code>) is accepted.199 </p><p>200 Although the returned pointer is declared <code class="literal">const</code>, it in fact201 points to mutable storage associated with the <code class="literal">PGconn</code> structure.202 It is unwise to assume the pointer will remain valid across queries.203 </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> <a href="#LIBPQ-PQPROTOCOLVERSION" class="id_link">#</a></dt><dd><p>204 Interrogates the frontend/backend protocol being used.205</p><pre class="synopsis">206int PQprotocolVersion(const PGconn *conn);207</pre><p>208 Applications might wish to use this function to determine whether certain209 features are supported. Currently, the possible values are 3210 (3.0 protocol), or zero (connection bad). The protocol version will211 not change after connection startup is complete, but it could212 theoretically change during a connection reset. The 3.0 protocol is213 supported by <span class="productname">PostgreSQL</span> server versions 7.4214 and above.215 </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> <a href="#LIBPQ-PQSERVERVERSION" class="id_link">#</a></dt><dd><p>216 Returns an integer representing the server version.217</p><pre class="synopsis">218int PQserverVersion(const PGconn *conn);219</pre><p>220 </p><p>221 Applications might use this function to determine the version of the222 database server they are connected to. The result is formed by223 multiplying the server's major version number by 10000 and adding224 the minor version number. For example, version 10.1 will be225 returned as 100001, and version 11.0 will be returned as 110000.226 Zero is returned if the connection is bad.227 </p><p>228 Prior to major version 10, <span class="productname">PostgreSQL</span> used229 three-part version numbers in which the first two parts together230 represented the major version. For those231 versions, <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a> uses two digits for each232 part; for example version 9.1.5 will be returned as 90105, and233 version 9.2.0 will be returned as 90200.234 </p><p>235 Therefore, for purposes of determining feature compatibility,236 applications should divide the result of <a class="xref" href="libpq-status.html#LIBPQ-PQSERVERVERSION"><code class="function">PQserverVersion</code></a>237 by 100 not 10000 to determine a logical major version number.238 In all release series, only the last two digits differ between239 minor releases (bug-fix releases).240 </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> <a href="#LIBPQ-PQERRORMESSAGE" class="id_link">#</a></dt><dd><p>241 <a id="id-1.7.3.9.5.2.6.2.1.1" class="indexterm"></a> Returns the error message242 most recently generated by an operation on the connection.243 244</p><pre class="synopsis">245char *PQerrorMessage(const PGconn *conn);246</pre><p>247 248 </p><p>249 Nearly all <span class="application">libpq</span> functions will set a message for250 <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> if they fail. Note that by251 <span class="application">libpq</span> convention, a nonempty252 <a class="xref" href="libpq-status.html#LIBPQ-PQERRORMESSAGE"><code class="function">PQerrorMessage</code></a> result can consist of multiple lines,253 and will include a trailing newline. The caller should not free254 the result directly. It will be freed when the associated255 <code class="structname">PGconn</code> handle is passed to256 <a class="xref" href="libpq-connect.html#LIBPQ-PQFINISH"><code class="function">PQfinish</code></a>. The result string should not be257 expected to remain the same across operations on the258 <code class="literal">PGconn</code> structure.259 </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> <a href="#LIBPQ-PQSOCKET" class="id_link">#</a></dt><dd><p>260 Obtains the file descriptor number of the connection socket to261 the server. A valid descriptor will be greater than or equal262 to 0; a result of -1 indicates that no server connection is263 currently open. (This will not change during normal operation,264 but could change during connection setup or reset.)265 266</p><pre class="synopsis">267int PQsocket(const PGconn *conn);268</pre><p>269 270 </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> <a href="#LIBPQ-PQBACKENDPID" class="id_link">#</a></dt><dd><p>271 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>272 of the backend process handling this connection.273 274</p><pre class="synopsis">275int PQbackendPID(const PGconn *conn);276</pre><p>277 </p><p>278 The backend <acronym class="acronym">PID</acronym> is useful for debugging279 purposes and for comparison to <code class="command">NOTIFY</code>280 messages (which include the <acronym class="acronym">PID</acronym> of the281 notifying backend process). Note that the282 <acronym class="acronym">PID</acronym> belongs to a process executing on the283 database server host, not the local host!284 </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> <a href="#LIBPQ-PQCONNECTIONNEEDSPASSWORD" class="id_link">#</a></dt><dd><p>285 Returns true (1) if the connection authentication method286 required a password, but none was available.287 Returns false (0) if not.288 289</p><pre class="synopsis">290int PQconnectionNeedsPassword(const PGconn *conn);291</pre><p>292 </p><p>293 This function can be applied after a failed connection attempt294 to decide whether to prompt the user for a password.295 </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> <a href="#LIBPQ-PQCONNECTIONUSEDPASSWORD" class="id_link">#</a></dt><dd><p>296 Returns true (1) if the connection authentication method297 used a password. Returns false (0) if not.298 299</p><pre class="synopsis">300int PQconnectionUsedPassword(const PGconn *conn);301</pre><p>302 </p><p>303 This function can be applied after either a failed or successful304 connection attempt to detect whether the server demanded a password.305 </p></dd><dt id="LIBPQ-PQCONNECTIONUSEDGSSAPI"><span class="term"><code class="function">PQconnectionUsedGSSAPI</code><a id="id-1.7.3.9.5.2.11.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQCONNECTIONUSEDGSSAPI" class="id_link">#</a></dt><dd><p>306 Returns true (1) if the connection authentication method307 used GSSAPI. Returns false (0) if not.308 309</p><pre class="synopsis">310int PQconnectionUsedGSSAPI(const PGconn *conn);311</pre><p>312 </p><p>313 This function can be applied to detect whether the connection was314 authenticated with GSSAPI.315 </p></dd></dl></div><p>316 </p><p>317 The following functions return information related to SSL. This information318 usually doesn't change after a connection is established.319 320 </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>321 Returns true (1) if the connection uses SSL, false (0) if not.322 323</p><pre class="synopsis">324int PQsslInUse(const PGconn *conn);325</pre><p>326 </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>327 Returns SSL-related information about the connection.328 329</p><pre class="synopsis">330const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);331</pre><p>332 </p><p>333 The list of available attributes varies depending on the SSL library334 being used and the type of connection. Returns NULL if the connection335 does not use SSL or the specified attribute name is not defined for the336 library in use.337 </p><p>338 The following attributes are commonly available:339 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">library</code></span></dt><dd><p>340 Name of the SSL implementation in use. (Currently, only341 <code class="literal">"OpenSSL"</code> is implemented)342 </p></dd><dt><span class="term"><code class="literal">protocol</code></span></dt><dd><p>343 SSL/TLS version in use. Common values344 are <code class="literal">"TLSv1"</code>, <code class="literal">"TLSv1.1"</code>345 and <code class="literal">"TLSv1.2"</code>, but an implementation may346 return other strings if some other protocol is used.347 </p></dd><dt><span class="term"><code class="literal">key_bits</code></span></dt><dd><p>348 Number of key bits used by the encryption algorithm.349 </p></dd><dt><span class="term"><code class="literal">cipher</code></span></dt><dd><p>350 A short name of the ciphersuite used, e.g.,351 <code class="literal">"DHE-RSA-DES-CBC3-SHA"</code>. The names are specific352 to each SSL implementation.353 </p></dd><dt><span class="term"><code class="literal">compression</code></span></dt><dd><p>354 Returns "on" if SSL compression is in use, else it returns "off".355 </p></dd></dl></div><p>356 </p><p>357 As a special case, the <code class="literal">library</code> attribute may be358 queried without a connection by passing NULL as359 the <code class="literal">conn</code> argument. The result will be the default360 SSL library name, or NULL if <span class="application">libpq</span> was361 compiled without any SSL support. (Prior362 to <span class="productname">PostgreSQL</span> version 15, passing NULL as363 the <code class="literal">conn</code> argument always resulted in NULL.364 Client programs needing to differentiate between the newer and older365 implementations of this case may check the366 <code class="literal">LIBPQ_HAS_SSL_LIBRARY_DETECTION</code> feature macro.)367 </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>368 Returns an array of SSL attribute names that can be used369 in <code class="function">PQsslAttribute()</code>.370 The array is terminated by a NULL pointer.371</p><pre class="synopsis">372const char * const * PQsslAttributeNames(const PGconn *conn);373</pre><p>374 </p><p>375 If <code class="literal">conn</code> is NULL, the attributes available for the376 default SSL library are returned, or an empty list377 if <span class="application">libpq</span> was compiled without any SSL378 support. If <code class="literal">conn</code> is not NULL, the attributes379 available for the SSL library in use for the connection are returned,380 or an empty list if the connection is not encrypted.381 </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>382 Returns a pointer to an SSL-implementation-specific object describing383 the connection. Returns NULL if the connection is not encrypted384 or the requested type of object is not available from the connection's385 SSL implementation.386</p><pre class="synopsis">387void *PQsslStruct(const PGconn *conn, const char *struct_name);388</pre><p>389 </p><p>390 The struct(s) available depend on the SSL implementation in use.391 For <span class="productname">OpenSSL</span>, there is one struct,392 available under the name <code class="literal">OpenSSL</code>,393 and it returns a pointer to394 <span class="productname">OpenSSL</span>'s <code class="literal">SSL</code> struct.395 To use this function, code along the following lines could be used:396</p><pre class="programlisting">397#include <libpq-fe.h>398#include <openssl/ssl.h>399 400...401 402 SSL *ssl;403 404 dbconn = PQconnectdb(...);405 ...406 407 ssl = PQsslStruct(dbconn, "OpenSSL");408 if (ssl)409 {410 /* use OpenSSL functions to access ssl */411 }412</pre><p>413 </p><p>414 This structure can be used to verify encryption levels, check server415 certificates, and more. Refer to the <span class="productname">OpenSSL</span>416 documentation for information about this structure.417 </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>418 <a id="id-1.7.3.9.6.1.5.2.1.1" class="indexterm"></a>419 Returns the SSL structure used in the connection, or NULL420 if SSL is not in use.421 422</p><pre class="synopsis">423void *PQgetssl(const PGconn *conn);424</pre><p>425 </p><p>426 This function is equivalent to <code class="literal">PQsslStruct(conn, "OpenSSL")</code>. It should427 not be used in new applications, because the returned struct is428 specific to <span class="productname">OpenSSL</span> and will not be429 available if another <acronym class="acronym">SSL</acronym> implementation is used.430 To check if a connection uses SSL, call431 <a class="xref" href="libpq-status.html#LIBPQ-PQSSLINUSE"><code class="function">PQsslInUse</code></a> instead, and for more details about the432 connection, use <a class="xref" href="libpq-status.html#LIBPQ-PQSSLATTRIBUTE"><code class="function">PQsslAttribute</code></a>.433 </p></dd></dl></div><p>434 </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 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.3. Command Execution Functions</td></tr></table></div></body></html>