Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit b04d691

Browse files
committed
docs: update libpq's PQputCopyData and PQputCopyEnd
Clarify the meaning of libpq return values for PQputCopyData and PQputCopyEnd, particularly in non-blocking mode. Report by Robert Haas
1 parent d060e07 commit b04d691

File tree

1 file changed

+17
-12
lines changed

1 file changed

+17
-12
lines changed

doc/src/sgml/libpq.sgml

+17-12
Original file line numberDiff line numberDiff line change
@@ -4318,8 +4318,8 @@ int PQsetnonblocking(PGconn *conn, int arg);
43184318
<para>
43194319
In the nonblocking state, calls to
43204320
<function>PQsendQuery</function>, <function>PQputline</function>,
4321-
<function>PQputnbytes</function>, and
4322-
<function>PQendcopy</function> will not block but instead return
4321+
<function>PQputnbytes</function>, <function>PQputCopyData</function>,
4322+
and <function>PQendcopy</function> will not block but instead return
43234323
an error if they need to be called again.
43244324
</para>
43254325

@@ -4961,9 +4961,9 @@ int PQputCopyData(PGconn *conn,
49614961
<para>
49624962
Transmits the <command>COPY</command> data in the specified
49634963
<parameter>buffer</>, of length <parameter>nbytes</>, to the server.
4964-
The result is 1 if the data was sent, zero if it was not sent
4965-
because the attempt would block (this case is only possible if the
4966-
connection is in nonblocking mode), or -1 if an error occurred.
4964+
The result is 1 if the data was queued, zero if it was not queued
4965+
because of full buffers (this will only happen in nonblocking mode),
4966+
or -1 if an error occurred.
49674967
(Use <function>PQerrorMessage</function> to retrieve details if
49684968
the return value is -1. If the value is zero, wait for write-ready
49694969
and try again.)
@@ -5009,13 +5009,18 @@ int PQputCopyEnd(PGconn *conn,
50095009
connections.)
50105010
</para>
50115011

5012-
<para>
5013-
The result is 1 if the termination data was sent, zero if it was
5014-
not sent because the attempt would block (this case is only possible
5015-
if the connection is in nonblocking mode), or -1 if an error
5016-
occurred. (Use <function>PQerrorMessage</function> to retrieve
5017-
details if the return value is -1. If the value is zero, wait for
5018-
write-ready and try again.)
5012+
<para>
5013+
The result is 1 if the termination message was sent; or in
5014+
nonblocking mode, this may only indicate that the termination
5015+
message was successfully queued. (In nonblocking mode, to be
5016+
certain that the data has been sent, you should next wait for
5017+
write-ready and call <function>PQflush</>, repeating until it
5018+
returns zero.) Zero indicates that the function could not queue
5019+
the termination message because of full buffers; this will only
5020+
happen in nonblocking mode. (In this case, wait for
5021+
write-ready and try the <function>PQputCopyEnd</> call
5022+
again.) If a hard error occurs, -1 is returned; you can use
5023+
<function>PQerrorMessage</function> to retrieve details.
50195024
</para>
50205025

50215026
<para>

0 commit comments

Comments
 (0)