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
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>28.2.Connection Status Functions</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="libpq.html" title="Chapter28.libpq - C Library">
<link rel="prev" href="libpq.html" title="Chapter28.libpq - C Library">
<link rel="next" href="libpq-exec.html" title="28.3.Command Execution Functions">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="libpq-status"></a>28.2.Connection Status Functions</h2></div></div></div>
<p> These functions may be used to interrogate the status
of an existing database connection object.
</p>
<div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Tip</h3>
<p><a name="id677429"></a>
<a name="id677436"></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>. Avoid directly referencing the fields of the
<code class="structname">PGconn</code> structure because they are subject to change in the future.
(Beginning in <span class="productname">PostgreSQL</span> release 6.4, the
definition of the <code class="type">struct</code> behind <code class="structname">PGconn</code> is not even provided in <code class="filename">libpq-fe.h</code>.
If you have old code that accesses <code class="structname">PGconn</code> fields directly, you can keep using it
by including <code class="filename">libpq-int.h</code> too, but you are encouraged to fix the code
soon.)</p>
</div>
<p>The following functions return parameter values established at connection.
These values are fixed for the life of the <code class="structname">PGconn</code> object.
</p>
<div class="variablelist"><dl>
<dt><span class="term"><code class="function">PQdb</code><a name="id677520"></a></span></dt>
<dd>
<p> Returns the database name of the connection.
</p>
<pre class="synopsis">char *PQdb(const PGconn *conn);</pre>
</dd>
<dt><span class="term"><code class="function">PQuser</code><a name="id677544"></a></span></dt>
<dd>
<p> Returns the user name of the connection.
</p>
<pre class="synopsis">char *PQuser(const PGconn *conn);</pre>
</dd>
<dt><span class="term"><code class="function">PQpass</code><a name="id677568"></a></span></dt>
<dd>
<p> Returns the password of the connection.
</p>
<pre class="synopsis">char *PQpass(const PGconn *conn);</pre>
</dd>
<dt><span class="term"><code class="function">PQhost</code><a name="id677593"></a></span></dt>
<dd>
<p> Returns the server host name of the connection.
</p>
<pre class="synopsis">char *PQhost(const PGconn *conn);</pre>
</dd>
<dt><span class="term"><code class="function">PQport</code><a name="id677617"></a></span></dt>
<dd>
<p> Returns the port of the connection.
</p>
<pre class="synopsis">char *PQport(const PGconn *conn);</pre>
</dd>
<dt><span class="term"><code class="function">PQtty</code><a name="id677641"></a></span></dt>
<dd>
<p> Returns the debug <acronym class="acronym">TTY</acronym> of the connection.
(This is obsolete, since the server no longer pays attention
to the <acronym class="acronym">TTY</acronym> setting, but the function remains
for backwards compatibility.)
</p>
<pre class="synopsis">char *PQtty(const PGconn *conn);</pre>
</dd>
<dt><span class="term"><code class="function">PQoptions</code><a name="id677675"></a></span></dt>
<dd>
<p> Returns the command-line options passed in the connection request.
</p>
<pre class="synopsis">char *PQoptions(const PGconn *conn);</pre>
</dd>
</dl></div>
<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>
<dt><span class="term"><code class="function">PQstatus</code><a name="id677710"></a></span></dt>
<dd>
<p> Returns the status of the connection.
</p>
<pre class="synopsis">ConnStatusType PQstatus(const PGconn *conn);</pre>
<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
<code class="function">PQfinish</code>, 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 <code class="function">PQreset</code>.
</p>
<p> See the entry for <code class="function">PQconnectStart</code> and <code class="function">PQconnectPoll</code> with regards
to other status codes
that might be seen.
</p>
</dd>
<dt><span class="term"><code class="function">PQtransactionStatus</code><a name="id677810"></a></span></dt>
<dd>
<p> Returns the current in-transaction status of the server.
</p>
<pre class="synopsis">PGTransactionStatusType PQtransactionStatus(const PGconn *conn);</pre>
<p>
The status can be <code class="literal">PQTRANS_IDLE</code> (currently idle),
<code class="literal">PQTRANS_ACTIVE</code> (a command is in progress),
<code class="literal">PQTRANS_INTRANS</code> (idle, in a valid transaction block),
or <code class="literal">PQTRANS_INERROR</code> (idle, in a failed transaction block).
<code class="literal">PQTRANS_UNKNOWN</code> is reported if the connection is bad.
<code class="literal">PQTRANS_ACTIVE</code> is reported only when a query
has been sent to the server and not yet completed.</p>
<div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Caution</h3>
<p><code class="function">PQtransactionStatus</code> will give incorrect results when using
a <span class="productname">PostgreSQL</span> 7.3 server that has the parameter <code class="literal">autocommit</code>
set to off. The server-side autocommit feature has been
deprecated and does not exist in later server versions.</p>
</div>
</dd>
<dt><span class="term"><code class="function">PQparameterStatus</code><a name="id677907"></a></span></dt>
<dd>
<p> Looks up a current parameter setting of the server.
</p>
<pre class="synopsis">const char *PQparameterStatus(const PGconn *conn, const char *paramName);</pre>
<p>
Certain parameter values are reported by the server automatically at
connection startup or whenever their values change.
<code class="function">PQparameterStatus</code> can be used to interrogate these settings.
It returns the current value of a parameter if known, or <code class="symbol">NULL</code>
if the parameter is not known.</p>
<p>Parameters reported as of the current release include
<code class="literal">server_version</code>,
<code class="literal">server_encoding</code>,
<code class="literal">client_encoding</code>,
<code class="literal">is_superuser</code>,
<code class="literal">session_authorization</code>,
<code class="literal">DateStyle</code>,
<code class="literal">TimeZone</code>,
<code class="literal">integer_datetimes</code>, and
<code class="literal">standard_conforming_strings</code>.
(<code class="literal">server_encoding</code>, <code class="literal">TimeZone</code>, and
<code class="literal">integer_datetimes</code> were not reported by releases before 8.0;
<code class="literal">standard_conforming_strings</code> was not reported by releases
before 8.1.)
Note that
<code class="literal">server_version</code>,
<code class="literal">server_encoding</code> and
<code class="literal">integer_datetimes</code>
cannot change after startup.</p>
<p>Pre-3.0-protocol servers do not report parameter settings, but
<span class="application">libpq</span> includes logic to obtain values for
<code class="literal">server_version</code> and <code class="literal">client_encoding</code> anyway.
Applications are encouraged to use <code class="function">PQparameterStatus</code>
rather than <span class="foreignphrase"><em class="foreignphrase">ad hoc</em></span> code to determine these values.
(Beware however
that on a pre-3.0 connection, changing <code class="literal">client_encoding</code> via
<code class="command">SET</code> after connection startup will not be reflected by
<code class="function">PQparameterStatus</code>.) For <code class="literal">server_version</code>,
see also <code class="function">PQserverVersion</code>, which returns the information
in a numeric form that is much easier to compare against.</p>
<p>If no value for <code class="literal">standard_conforming_strings</code> is reported,
applications may assume it is <code class="literal">false</code>, that is, backslashes
are treated as escapes in string literals. Also, the presence of this
parameter may 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><span class="term"><code class="function">PQprotocolVersion</code><a name="id678177"></a></span></dt>
<dd>
<p> Interrogates the frontend/backend protocol being used.
</p>
<pre class="synopsis">int PQprotocolVersion(const PGconn *conn);</pre>
<p>
Applications may wish to use this to determine whether certain features
are supported.
Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol),
or zero (connection bad). This will not change after connection
startup is complete, but it could theoretically change during a connection
reset. The 3.0 protocol will normally be used when communicating with
<span class="productname">PostgreSQL</span> 7.4 or later servers; pre-7.4 servers support
only protocol 2.0. (Protocol 1.0 is obsolete and not supported by <span class="application">libpq</span>.)</p>
</dd>
<dt><span class="term"><code class="function">PQserverVersion</code><a name="id678224"></a></span></dt>
<dd>
<p> Returns an integer representing the backend version.
</p>
<pre class="synopsis">int PQserverVersion(const PGconn *conn);</pre>
<p>
Applications may use this to determine the version of the database server they
are connected to. The number is formed by converting the major, minor, and
revision numbers into two-decimal-digit numbers and appending them
together. For example, version 7.4.2 will be returned as 70402, and version
8.1 will be returned as 80100 (leading zeroes are not shown). Zero is
returned if the connection is bad.</p>
</dd>
<dt><span class="term"><code class="function">PQerrorMessage</code><a name="id678257"></a></span></dt>
<dd>
<p> <a name="id678267"></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
<code class="function">PQerrorMessage</code> if they fail.
Note that by <span class="application">libpq</span> convention, a nonempty
<code class="function">PQerrorMessage</code> result 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 <code class="function">PQfinish</code>. The result string
should not be expected to remain the same across operations on the
<code class="literal">PGconn</code> structure.
</p>
</dd>
<dt><span class="term"><code class="function">PQsocket</code><a name="id678344"></a></span></dt>
<dd>
<p> Obtains the file descriptor number of the connection socket to
the server. A valid descriptor will be greater than or equal
to 0; a result of -1 indicates that no server connection is
currently open. (This will not change during normal operation,
but could change during connection setup or reset.)
</p>
<pre class="synopsis">int PQsocket(const PGconn *conn);</pre>
<p>
</p>
</dd>
<dt><span class="term"><code class="function">PQbackendPID</code><a name="id678374"></a></span></dt>
<dd>
<p> Returns the process <acronym class="acronym">ID</acronym>
(PID)<a name="id678389"></a> of the backend server
process handling this connection.
</p>
<pre class="synopsis">int PQbackendPID(const PGconn *conn);</pre>
<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><span class="term"><code class="function">PQgetssl</code><a name="id678442"></a></span></dt>
<dd>
<p> <a name="id678452"></a>
Returns the SSL structure used in the connection, or null
if SSL is not in use.
</p>
<pre class="synopsis">SSL *PQgetssl(const PGconn *conn);</pre>
<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>
<p> You must define <code class="symbol">USE_SSL</code> in order to get the
correct prototype for this function. Doing this will also
automatically include <code class="filename">ssl.h</code> from <span class="productname">OpenSSL</span>.
</p>
</dd>
</dl></div>
</div></body>
</html>
|
