@@ -262,6 +262,41 @@ PGconn *PQsetdb(char *pghost,
262
262
</listitem>
263
263
</varlistentry>
264
264
265
+ <varlistentry id="libpq-PQsocketPoll">
266
+ <term><function>PQsocketPoll</function><indexterm><primary>PQsocketPoll</primary></indexterm></term>
267
+ <listitem>
268
+ <para>
269
+ <indexterm><primary>nonblocking connection</primary></indexterm>
270
+ Poll a connection's underlying socket descriptor retrieved with <xref linkend="libpq-PQsocket"/>.
271
+ <synopsis>
272
+ int PQsocketPoll(int sock, int forRead, int forWrite, time_t end_time);
273
+ </synopsis>
274
+ </para>
275
+
276
+ <para>
277
+ This function sets up polling of a file descriptor. The underlying function is either
278
+ <function>poll(2)</function> or <function>select(2)</function>, depending on platform
279
+ support. The primary use of this function is iterating through the connection sequence
280
+ described in the documentation of <xref linkend="libpq-PQconnectStartParams"/>. If
281
+ <parameter>forRead</parameter> is specified, the function waits for the socket to be ready
282
+ for reading. If <parameter>forWrite</parameter> is specified, the function waits for the
283
+ socket to be ready for write. See <literal>POLLIN</literal> and <literal>POLLOUT</literal>
284
+ from <function>poll(2)</function>, or <parameter>readfds</parameter> and
285
+ <parameter>writefds</parameter> from <function>select(2)</function> for more information. If
286
+ <parameter>end_time</parameter> is not <literal>-1</literal>, it specifies the time at which
287
+ this function should stop waiting for the condition to be met.
288
+ </para>
289
+
290
+ <para>
291
+ The function returns a value greater than <literal>0</literal> if the specified condition
292
+ is met, <literal>0</literal> if a timeout occurred, or <literal>-1</literal> if an error
293
+ occurred. The error can be retrieved by checking the <literal>errno(3)</literal> value. In
294
+ the event <literal>forRead</literal> and <literal>forWrite</literal> are not set, the
295
+ function immediately returns a timeout condition.
296
+ </para>
297
+ </listitem>
298
+ </varlistentry>
299
+
265
300
<varlistentry id="libpq-PQconnectStartParams">
266
301
<term><function>PQconnectStartParams</function><indexterm><primary>PQconnectStartParams</primary></indexterm></term>
267
302
<term><function>PQconnectStart</function><indexterm><primary>PQconnectStart</primary></indexterm></term>
@@ -358,7 +393,10 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
358
393
Loop thus: If <function>PQconnectPoll(conn)</function> last returned
359
394
<symbol>PGRES_POLLING_READING</symbol>, wait until the socket is ready to
360
395
read (as indicated by <function>select()</function>, <function>poll()</function>, or
361
- similar system function).
396
+ similar system function). Note that <function>PQsocketPoll</function>
397
+ can help reduce boilerplate by abstracting the setup of
398
+ <function>select(2)</function> or <function>poll(2)</function> if it is
399
+ available on your system.
362
400
Then call <function>PQconnectPoll(conn)</function> again.
363
401
Conversely, if <function>PQconnectPoll(conn)</function> last returned
364
402
<symbol>PGRES_POLLING_WRITING</symbol>, wait until the socket is ready
0 commit comments