Sends data to the server duringCOPY_IN state.

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

Transmits theCOPY data in the specifiedbuffer, of lengthnbytes, to the server. The result is 1 if the data was sent, zero if it was not sent because the attempt would block (this case is only possible if the connection is in nonblocking mode), or -1 if an error occurred. (UsePQerrorMessage to retrieve details if the return value is -1. If the value is zero, wait for write-ready and try again.)

The application can divide theCOPY data stream into buffer loads of any convenient size. Buffer-load boundaries have no semantic significance when sending. The contents of the data stream must match the data format expected by theCOPY command; seeCOPY for details.

Sends end-of-data indication to the server duringCOPY_IN state.

int PQputCopyEnd(PGconn *conn,                 const char *errormsg);

Ends theCOPY_IN operation successfully iferrormsg isNULL. Iferrormsg is notNULL then theCOPY is forced to fail, with the string pointed to byerrormsg used as the error message. (One should not assume that this exact error message will come back from the server, however, as the server might have already failed theCOPY for its own reasons. Also note that the option to force failure does not work when using pre-3.0-protocol connections.)

The result is 1 if the termination data was sent, zero if it was not sent because the attempt would block (this case is only possible if the connection is in nonblocking mode), or -1 if an error occurred. (UsePQerrorMessage to retrieve details if the return value is -1. If the value is zero, wait for write-ready and try again.)

After successfully callingPQputCopyEnd, callPQgetResult to obtain the final result status of theCOPY command. One can wait for this result to be available in the usual way. Then return to normal operation.

Receives data from the server duringCOPY_OUT state.

int PQgetCopyData(PGconn *conn,                  char **buffer,                  int async);

Attempts to obtain another row of data from the server during aCOPY. Data is always returned one data row at a time; if only a partial row is available, it is not returned. Successful return of a data row involves allocating a chunk of memory to hold the data. Thebuffer parameter must be non-NULL.*buffer is set to point to the allocated memory, or toNULL in cases where no buffer is returned. A non-NULL result buffer should be freed usingPQfreemem when no longer needed.

When a row is successfully returned, the return value is the number of data bytes in the row (this will always be greater than zero). The returned string is always null-terminated, though this is probably only useful for textualCOPY. A result of zero indicates that theCOPY is still in progress, but no row is yet available (this is only possible whenasync is true). A result of -1 indicates that theCOPY is done. A result of -2 indicates that an error occurred (consultPQerrorMessage for the reason).

Whenasync is true (not zero),PQgetCopyData will not block waiting for input; it will return zero if theCOPY is still in progress but no complete row is available. (In this case wait for read-ready and then callPQconsumeInput before callingPQgetCopyData again.) Whenasync is false (zero),PQgetCopyData will block until data is available or the operation completes.

AfterPQgetCopyData returns -1, callPQgetResult to obtain the final result status of theCOPY command. One can wait for this result to be available in the usual way. Then return to normal operation.

Reads a newline-terminated line of characters (transmitted by the server) into a buffer string of sizelength.

int PQgetline(PGconn *conn,              char *buffer,              int length);

This function copies up tolength-1 characters into the buffer and converts the terminating newline into a zero byte.PQgetline returnsEOF at the end of input, 0 if the entire line has been read, and 1 if the buffer is full but the terminating newline has not yet been read.

Note that the application must check to see if a new line consists of the two characters\., which indicates that the server has finished sending the results of theCOPY command. If the application might receive lines that are more thanlength-1 characters long, care is needed to be sure it recognizes the\. line correctly (and does not, for example, mistake the end of a long data line for a terminator line).

Reads a row ofCOPY data (transmitted by the server) into a buffer without blocking.

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

This function is similar toPQgetline, but it can be used by applications that must readCOPY data asynchronously, that is, without blocking. Having issued theCOPY command and gotten aPGRES_COPY_OUT response, the application should callPQconsumeInput andPQgetlineAsync until the end-of-data signal is detected.

UnlikePQgetline, this function takes responsibility for detecting end-of-data.

On each call,PQgetlineAsync will return data if a complete data row is available inlibpq's input buffer. Otherwise, no data is returned until the rest of the row arrives. The function 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 callPQendcopy, and then return to normal processing.

The data returned will not extend beyond a data-row boundary. If possible a whole row will be returned at one time. But if the buffer offered by the caller is too small to hold a row sent by the server, then a partial data row will be returned. With textual data this can be detected by testing whether the last returned byte is\n or not. (In a binaryCOPY, actual parsing of theCOPY data format will be needed to make the equivalent determination.) The returned string is not null-terminated. (If you want to add a terminating null, be sure to pass abufsize one smaller than the room actually available.)

Sends a null-terminated string to the server. Returns 0 if OK andEOF if unable to send the string.

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

TheCOPY data stream sent by a series of calls toPQputline has the same format as that returned byPQgetlineAsync, except that applications are not obliged to send exactly one data row perPQputline call; it is okay to send a partial line or multiple lines per call.

Sends a non-null-terminated string to the server. Returns 0 if OK andEOF if unable to send the string.

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

This is exactly likePQputline, except that the data buffer need not be null-terminated since the number of bytes to send is specified directly. Use this procedure when sending binary data.

Synchronizes with the server.

int PQendcopy(PGconn *conn);

This function waits until the server has finished the copying. It should either be issued when the last string has been sent to the server usingPQputline or when the last string has been received from the server usingPGgetline. It must be issued or the server will get"out of sync" with the client. Upon return from this function, the server is ready to receive the next SQL command. The return value is 0 on successful completion, nonzero otherwise. (UsePQerrorMessage to retrieve details if the return value is nonzero.)

When usingPQgetResult, the application should respond to aPGRES_COPY_OUT result by executingPQgetline repeatedly, followed byPQendcopy after the terminator line is seen. It should then return to thePQgetResult loop untilPQgetResult returns a null pointer. Similarly aPGRES_COPY_IN result is processed by a series ofPQputline calls followed byPQendcopy, then return to thePQgetResult loop. This arrangement will ensure that aCOPY command embedded in a series ofSQL commands will be executed correctly.

Older applications are likely to submit aCOPY viaPQexec and assume that the transaction is done afterPQendcopy. This will work correctly only if theCOPY is the onlySQL command in the command string.