MySQL :: MySQL 8.4 C API Developer Guide :: 5.4.78 mysql_set_local_infile_handler() (original) (raw)

5.4.78 mysql_set_local_infile_handler()

Description

This function installs callbacks to be used during the execution of LOAD DATA LOCAL statements. It enables application programs to exert control over local (client-side) data file reading. The arguments are the connection handler, a set of pointers to callback functions, and a pointer to a data area that the callbacks can use to share information.

To usemysql_set_local_infile_handler(), you must write the following callback functions:

int
local_infile_init(void **ptr, const char *filename, void *userdata);

The initialization function. This is called once to do any setup necessary, open the data file, allocate data structures, and so forth. The first void** argument is a pointer to a pointer. You can set the pointer (that is,*ptr) to a value that will be passed to each of the other callbacks (as a void*). The callbacks can use this pointed-to value to maintain state information. The userdata argument is the same value that is passed tomysql_set_local_infile_handler().

Make the initialization function return zero for success, nonzero for an error.

int
local_infile_read(void *ptr, char *buf, unsigned int buf_len);

The data-reading function. This is called repeatedly to read the data file. buf points to the buffer where the read data is stored, and buf_len is the maximum number of bytes that the callback can read and store in the buffer. (It can read fewer bytes, but should not read more.)

The return value is the number of bytes read, or zero when no more data could be read (this indicates EOF). Return a value less than zero if an error occurs.

void
local_infile_end(void *ptr)

The termination function. This is called once afterlocal_infile_read() has returned zero (EOF) or an error. Within this function, deallocate any memory allocated by local_infile_init() and perform any other cleanup necessary. It is invoked even if the initialization function returns an error.

int
local_infile_error(void *ptr,
                   char *error_msg,
                   unsigned int error_msg_len);

The error-handling function. This is called to get a textual error message to return to the user in case any of your other functions returns an error. error_msg points to the buffer into which the message is written, anderror_msg_len is the length of the buffer. Write the message as a null-terminated string, at mosterror_msg_len−1 bytes long.

The return value is the error number.

Typically, the other callbacks store the error message in the data structure pointed to by ptr, so thatlocal_infile_error() can copy the message from there into error_msg.

After callingmysql_set_local_infile_handler() in your C code and passing pointers to your callback functions, you can then issue aLOAD DATA LOCAL statement (for example, by usingmysql_real_query() ormysql_query()). The client library automatically invokes your callbacks. The file name specified in LOAD DATA LOCAL will be passed as the second parameter to the local_infile_init() callback.