1berry/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: update libpq's PQputCopyData and PQputCopyEnd

Browse Source 
Clarify the meaning of libpq return values for PQputCopyData and
PQputCopyEnd, particularly in non-blocking mode.

Report by Robert Haas
This commit is contained in:
Bruce Momjian 2015-01-22 13:30:08 -05:00
parent d060e07fa9
commit b04d691613
1 changed files with 17 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/src/sgml/libpq.sgml
View File

@ -4318,8 +4318,8 @@ int PQsetnonblocking(PGconn *conn, int arg);
<para> <para>
In the nonblocking state, calls to In the nonblocking state, calls to
<function>PQsendQuery</function>, <function>PQputline</function>, <function>PQsendQuery</function>, <function>PQputline</function>,
<function>PQputnbytes</function>, and <function>PQputnbytes</function>, <function>PQputCopyData</function>,
<function>PQendcopy</function> will not block but instead return and <function>PQendcopy</function> will not block but instead return
an error if they need to be called again. an error if they need to be called again.
</para> </para>
@ -4961,9 +4961,9 @@ int PQputCopyData(PGconn *conn,
<para> <para>
Transmits the <command>COPY</command> data in the specified Transmits the <command>COPY</command> data in the specified
<parameter>buffer</>, of length <parameter>nbytes</>, to the server. <parameter>buffer</>, of length <parameter>nbytes</>, to the server.
The result is 1 if the data was sent, zero if it was not sent The result is 1 if the data was queued, zero if it was not queued
because the attempt would block (this case is only possible if the because of full buffers (this will only happen in nonblocking mode),
connection is in nonblocking mode), or -1 if an error occurred. or -1 if an error occurred.
(Use <function>PQerrorMessage</function> to retrieve details if (Use <function>PQerrorMessage</function> to retrieve details if
the return value is -1. If the value is zero, wait for write-ready the return value is -1. If the value is zero, wait for write-ready
and try again.) and try again.)
@ -5010,12 +5010,17 @@ int PQputCopyEnd(PGconn *conn,
</para> </para>
<para> <para>
The result is 1 if the termination data was sent, zero if it was The result is 1 if the termination message was sent; or in
not sent because the attempt would block (this case is only possible nonblocking mode, this may only indicate that the termination
if the connection is in nonblocking mode), or -1 if an error message was successfully queued. (In nonblocking mode, to be
occurred. (Use <function>PQerrorMessage</function> to retrieve certain that the data has been sent, you should next wait for
details if the return value is -1. If the value is zero, wait for write-ready and call <function>PQflush</>, repeating until it
write-ready and try again.) returns zero.) Zero indicates that the function could not queue
the termination message because of full buffers; this will only
happen in nonblocking mode. (In this case, wait for
write-ready and try the <function>PQputCopyEnd</> call
again.) If a hard error occurs, -1 is returned; you can use
<function>PQerrorMessage</function> to retrieve details.
</para> </para>
<para> <para>