Team Ai
Datasetpublic

codekingpro/portable-devtools

sourceHugging Faceupdated 5mo agoView on Hugging Face
1likes14kdownloads
libpq-status.html434 linesDownload Raw Back to 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>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 &lt;libpq-fe.h&gt;398#include &lt;openssl/ssl.h&gt;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>
codekingpro/portable-devtools · Team Ai