The COPY command in Postgres
has options to read from or write to the network connection used by
libpq. Therefore, functions are necessary
to access this network connection directly so applications may take
advantage of this capability.

These functions should be executed only after obtaining a
PGRES_COPY_OUT or PGRES_COPY_IN result object from PQexec or
PQgetResult.

PQgetline Reads a
newline-terminated line of characters (transmitted by the
backend server) into a buffer string of size length.

int PQgetline(PGconn *conn,
char *string,
int length)

Like fgets(3), this routine copies up to length-1 characters
into string. It is like gets(3), however, in that it converts the
terminating newline into a null character. PQgetline returns EOF at
EOF, 0 if the entire line has been read, and 1 if the buffer is
full but the terminating newline has not yet been read. Notice that
the application must check to see if a new line consists of the two
characters "\.", which indicates that the backend server has
finished sending the results of the copy command. If the
application might receive lines that are more than length-1
characters long, care is needed to be sure one recognizes the "\."
line correctly (and does not, for example, mistake the end of a
long data line for a terminator line). The code in ../src/bin/psql/psql.c contains routines that
correctly handle the copy protocol.

PQgetlineAsync Reads a
newline-terminated line of characters (transmitted by the
backend server) into a buffer without blocking.

int PQgetlineAsync(PGconn *conn,
char *buffer,
int bufsize)

This routine is similar to PQgetline, but it can be used by
applications that must read COPY data asynchronously, that is
without blocking. Having issued the COPY command and gotten a
PGRES_COPY_OUT response, the application should call PQconsumeInput
and PQgetlineAsync until the end-of-data signal is detected. Unlike
PQgetline, this routine takes responsibility for detecting
end-of-data. On each call, PQgetlineAsync will return data if a
complete newline- terminated data line is available in libpq's
input buffer, or if the incoming data line is too long to fit in
the buffer offered by the caller. Otherwise, no data is returned
until the rest of the line arrives. The routine returns -1 if the
end-of-copy-data marker has been recognized, or 0 if no data is
available, or a positive number giving the number of bytes of data
returned. If -1 is returned, the caller must next call PQendcopy,
and then return to normal processing. The data returned will not
extend beyond a newline character. If possible a whole line will be
returned at one time. But if the buffer offered by the caller is
too small to hold a line sent by the backend, then a partial data
line will be returned. This can be detected by testing whether the
last returned byte is '\n' or not. The returned string is not
null-terminated. (If you want to add a terminating null, be sure to
pass a bufsize one smaller than the room actually available.)

PQputline Sends a null-terminated
string to the backend server. Returns 0 if OK, EOF if unable to
send the string.

int PQputline(PGconn *conn,
char *string);

Note the application must explicitly send the two characters
"\." on a final line to indicate to the backend that it has
finished sending its data.

PQputnbytes Sends a
non-null-terminated string to the backend server. Returns 0 if
OK, EOF if unable to send the string.

int PQputnbytes(PGconn *conn,
const char *buffer,
int nbytes);

This is exactly like PQputline, except that the data buffer
need not be null-terminated since the number of bytes to send is
specified directly.

PQendcopy Syncs with the backend.
This function waits until the backend has finished the copy. It
should either be issued when the last string has been sent to
the backend using PQputline or when the last string has been
received from the backend using PGgetline. It must be issued or
the backend may get "out of sync" with the frontend. Upon
return from this function, the backend is ready to receive the
next query. The return value is 0 on successful completion,
nonzero otherwise.

When using PQgetResult, the application should respond to a
PGRES_COPY_OUT result by executing PQgetline repeatedly, followed
by PQendcopy after the terminator line is seen. It should then
return to the PQgetResult loop until PQgetResult returns NULL.
Similarly a PGRES_COPY_IN result is processed by a series of
PQputline calls followed by PQendcopy, then return to the
PQgetResult loop. This arrangement will ensure that a copy in or
copy out command embedded in a series of SQL commands will be
executed correctly. Older applications are likely to submit a copy
in or copy out via PQexec and assume that the transaction is done
after PQendcopy. This will work correctly only if the copy in/out
is the only SQL command in the query string.