summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/libpq-status.html
blob: f37920eb653708526efcf95551f4a5eabfff7255 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>34.2. Connection Status Functions</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-connect.html" title="34.1. Database Connection Control Functions" /><link rel="next" href="libpq-exec.html" title="34.3. Command Execution Functions" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">34.2. Connection Status Functions</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-connect.html" title="34.1. Database Connection Control Functions">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 34. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 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>
   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> <a href="#LIBPQ-PQDB" class="id_link">#</a></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> <a href="#LIBPQ-PQUSER" class="id_link">#</a></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> <a href="#LIBPQ-PQPASS" class="id_link">#</a></dt><dd><p>
       Returns the password of the connection.
</p><pre class="synopsis">
char *PQpass(const PGconn *conn);
</pre><p>
      </p><p>
       <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> will return either the password specified
       in the connection parameters, or if there was none and the password
       was obtained from the <a class="link" href="libpq-pgpass.html" title="34.16. The Password File">password
       file</a>, it will return that.  In the latter case,
       if multiple hosts were specified in the connection parameters, it is
       not possible to rely on the result of <a class="xref" href="libpq-status.html#LIBPQ-PQPASS"><code class="function">PQpass</code></a> until
       the connection is established.  The status of the connection can be
       checked using the function <a class="xref" href="libpq-status.html#LIBPQ-PQSTATUS"><code class="function">PQstatus</code></a>.
      </p></dd><dt id="LIBPQ-PQHOST"><span class="term"><code class="function">PQhost</code><a id="id-1.7.3.9.4.6.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQHOST" class="id_link">#</a></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> <a href="#LIBPQ-PQHOSTADDR" class="id_link">#</a></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> <a href="#LIBPQ-PQPORT" class="id_link">#</a></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> <a href="#LIBPQ-PQTTY" class="id_link">#</a></dt><dd><p>
       This function no longer does anything, but it remains for backwards
       compatibility.  The function always return an empty string, or
       <code class="symbol">NULL</code> if the <em class="parameter"><code>conn</code></em> argument is
       <code class="symbol">NULL</code>.

</p><pre class="synopsis">
char *PQtty(const PGconn *conn);
</pre><p>
      </p></dd><dt id="LIBPQ-PQOPTIONS"><span class="term"><code class="function">PQoptions</code><a id="id-1.7.3.9.4.6.8.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQOPTIONS" class="id_link">#</a></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> <a href="#LIBPQ-PQSTATUS" class="id_link">#</a></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> <a href="#LIBPQ-PQTRANSACTIONSTATUS" class="id_link">#</a></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> <a href="#LIBPQ-PQPARAMETERSTATUS" class="id_link">#</a></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:
       </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>
       (<code class="varname">server_encoding</code>, <code class="varname">TimeZone</code>, and
       <code class="varname">integer_datetimes</code> were not reported by releases before 8.0;
       <code class="varname">standard_conforming_strings</code> was not reported by releases
       before 8.1;
       <code class="varname">IntervalStyle</code> was not reported by releases before 8.4;
       <code class="varname">application_name</code> was not reported by releases before
       9.0;
       <code class="varname">default_transaction_read_only</code> and
       <code class="varname">in_hot_standby</code> were not reported by releases before
       14; <code class="varname">scram_iterations</code> was not reported by releases
       before 16.)
       Note that
       <code class="varname">server_version</code>,
       <code class="varname">server_encoding</code> and
       <code class="varname">integer_datetimes</code>
       cannot change after startup.
      </p><p>
       If no value for <code class="varname">standard_conforming_strings</code> is reported,
       applications can assume it is <code class="literal">off</code>, that is, backslashes
       are treated as escapes in string literals.  Also, the presence of
       this parameter can be taken as an indication that the escape string
       syntax (<code class="literal">E'...'</code>) is accepted.
      </p><p>
       Although the returned pointer is declared <code class="literal">const</code>, it in fact
       points to mutable storage associated with the <code class="literal">PGconn</code> structure.
       It is unwise to assume the pointer will remain valid across queries.
      </p></dd><dt id="LIBPQ-PQPROTOCOLVERSION"><span class="term"><code class="function">PQprotocolVersion</code><a id="id-1.7.3.9.5.2.4.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQPROTOCOLVERSION" class="id_link">#</a></dt><dd><p>
       Interrogates the frontend/backend protocol being used.
</p><pre class="synopsis">
int PQprotocolVersion(const PGconn *conn);
</pre><p>
       Applications might wish to use this function to determine whether certain
       features are supported.  Currently, the possible values are 3
       (3.0 protocol), or zero (connection bad).  The protocol version will
       not change after connection startup is complete, but it could
       theoretically change during a connection reset.  The 3.0 protocol is
       supported by <span class="productname">PostgreSQL</span> server versions 7.4
       and above.
      </p></dd><dt id="LIBPQ-PQSERVERVERSION"><span class="term"><code class="function">PQserverVersion</code><a id="id-1.7.3.9.5.2.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSERVERVERSION" class="id_link">#</a></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> <a href="#LIBPQ-PQERRORMESSAGE" class="id_link">#</a></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> <a href="#LIBPQ-PQSOCKET" class="id_link">#</a></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> <a href="#LIBPQ-PQBACKENDPID" class="id_link">#</a></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> <a href="#LIBPQ-PQCONNECTIONNEEDSPASSWORD" class="id_link">#</a></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> <a href="#LIBPQ-PQCONNECTIONUSEDPASSWORD" class="id_link">#</a></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><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>
       Returns true (1) if the connection authentication method
       used GSSAPI. Returns false (0) if not.

</p><pre class="synopsis">
int PQconnectionUsedGSSAPI(const PGconn *conn);
</pre><p>
      </p><p>
       This function can be applied to detect whether the connection was
       authenticated with GSSAPI.
      </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> <a href="#LIBPQ-PQSSLINUSE" class="id_link">#</a></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> <a href="#LIBPQ-PQSSLATTRIBUTE" class="id_link">#</a></dt><dd><p>
        Returns SSL-related information about the connection.

</p><pre class="synopsis">
const char *PQsslAttribute(const PGconn *conn, const char *attribute_name);
</pre><p>
      </p><p>
       The list of available attributes varies depending on the SSL library
       being used and the type of connection.  Returns NULL if the connection
       does not use SSL or the specified attribute name is not defined for the
       library in use.
      </p><p>
       The following attributes are commonly available:
       </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">library</code></span></dt><dd><p>
            Name of the SSL implementation in use. (Currently, only
            <code class="literal">"OpenSSL"</code> is implemented)
           </p></dd><dt><span class="term"><code class="literal">protocol</code></span></dt><dd><p>
             SSL/TLS version in use. Common values
             are <code class="literal">"TLSv1"</code>, <code class="literal">"TLSv1.1"</code>
             and <code class="literal">"TLSv1.2"</code>, but an implementation may
             return other strings if some other protocol is used.
           </p></dd><dt><span class="term"><code class="literal">key_bits</code></span></dt><dd><p>
            Number of key bits used by the encryption algorithm.
           </p></dd><dt><span class="term"><code class="literal">cipher</code></span></dt><dd><p>
            A short name of the ciphersuite used, e.g.,
            <code class="literal">"DHE-RSA-DES-CBC3-SHA"</code>. The names are specific
            to each SSL implementation.
           </p></dd><dt><span class="term"><code class="literal">compression</code></span></dt><dd><p>
            Returns "on" if SSL compression is in use, else it returns "off".
           </p></dd></dl></div><p>
      </p><p>
       As a special case, the <code class="literal">library</code> attribute may be
       queried without a connection by passing NULL as
       the <code class="literal">conn</code> argument.  The result will be the default
       SSL library name, or NULL if <span class="application">libpq</span> was
       compiled without any SSL support.  (Prior
       to <span class="productname">PostgreSQL</span> version 15, passing NULL as
       the <code class="literal">conn</code> argument always resulted in NULL.
       Client programs needing to differentiate between the newer and older
       implementations of this case may check the
       <code class="literal">LIBPQ_HAS_SSL_LIBRARY_DETECTION</code> feature macro.)
      </p></dd><dt id="LIBPQ-PQSSLATTRIBUTENAMES"><span class="term"><code class="function">PQsslAttributeNames</code><a id="id-1.7.3.9.6.1.3.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSSLATTRIBUTENAMES" class="id_link">#</a></dt><dd><p>
       Returns an array of SSL attribute names that can be used
       in <code class="function">PQsslAttribute()</code>.
       The array is terminated by a NULL pointer.
</p><pre class="synopsis">
const char * const * PQsslAttributeNames(const PGconn *conn);
</pre><p>
      </p><p>
       If <code class="literal">conn</code> is NULL, the attributes available for the
       default SSL library are returned, or an empty list
       if <span class="application">libpq</span> was compiled without any SSL
       support.  If <code class="literal">conn</code> is not NULL, the attributes
       available for the SSL library in use for the connection are returned,
       or an empty list if the connection is not encrypted.
      </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>
       Returns a pointer to an SSL-implementation-specific object describing
       the connection.  Returns NULL if the connection is not encrypted
       or the requested type of object is not available from the connection's
       SSL implementation.
</p><pre class="synopsis">
void *PQsslStruct(const PGconn *conn, const char *struct_name);
</pre><p>
      </p><p>
       The struct(s) available depend on the SSL implementation in use.
       For <span class="productname">OpenSSL</span>, there is one struct,
       available under the name <code class="literal">OpenSSL</code>,
       and it returns a pointer to
       <span class="productname">OpenSSL</span>'s <code class="literal">SSL</code> struct.
       To use this function, code along the following lines could be used:
</p><pre class="programlisting">
#include &lt;libpq-fe.h&gt;
#include &lt;openssl/ssl.h&gt;

...

    SSL *ssl;

    dbconn = PQconnectdb(...);
    ...

    ssl = PQsslStruct(dbconn, "OpenSSL");
    if (ssl)
    {
        /* use OpenSSL functions to access ssl */
    }
</pre><p>
      </p><p>
       This structure can be used to verify encryption levels, check server
       certificates, and more. Refer to the <span class="productname">OpenSSL</span>
       documentation for information about this structure.
      </p></dd><dt id="LIBPQ-PQGETSSL"><span class="term"><code class="function">PQgetssl</code><a id="id-1.7.3.9.6.1.5.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQGETSSL" class="id_link">#</a></dt><dd><p>
       <a id="id-1.7.3.9.6.1.5.2.1.1" class="indexterm"></a>
       Returns the SSL structure used in the connection, or NULL
       if SSL is not in use.

</p><pre class="synopsis">
void *PQgetssl(const PGconn *conn);
</pre><p>
      </p><p>
       This function is equivalent to <code class="literal">PQsslStruct(conn, "OpenSSL")</code>. It should
       not be used in new applications, because the returned struct is
       specific to <span class="productname">OpenSSL</span> and will not be
       available if another <acronym class="acronym">SSL</acronym> implementation is used.
       To check if a connection uses SSL, call
       <a class="xref" href="libpq-status.html#LIBPQ-PQSSLINUSE"><code class="function">PQsslInUse</code></a> instead, and for more details about the
       connection, use <a class="xref" href="libpq-status.html#LIBPQ-PQSSLATTRIBUTE"><code class="function">PQsslAttribute</code></a>.
      </p></dd></dl></div><p>
  </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-connect.html" title="34.1. Database Connection Control Functions">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 34. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-exec.html" title="34.3. Command Execution Functions">Next</a></td></tr><tr><td width="40%" align="left" valign="top">34.1. Database Connection Control Functions </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 16.3 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 34.3. Command Execution Functions</td></tr></table></div></body></html>