mysql_set_local_infile_handler()

You can call the mysql_set_local_infile_handler() function to install callbacks to be used during the execution of LOAD DATA LOCAL statements.

Syntax

void
mysql_set_local_infile_handler(MYSQL *mysql,
  int (*local_infile_init)(void **, const char *, void *),
  int (*local_infile_read)(void *, char *, unsigned int),
  void (*local_infile_end)(void *),
  int (*local_infile_error)(void *, char*, unsigned int),
  void *userdata);

Return values

None.

Errors

None.

Notes

mysql_set_local_infile_handler() enables application programs to control 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 use mysql_set_local_infile_handler(), you must write the following callback functions:

• Initialization function: It is called once to perform necessary settings, open the data file, allocate data structures, and so on.

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

  The first void** argument is a pointer to a pointer. You can set the pointer (that is, *ptr) to a value to be passed to other callbacks (as a void*). The callbacks can use this pointed-to value to maintain status information. The value of the userdata argument is the same as that passed to mysql_set_local_infile_handler(). The initialization function returns 0 for an operation success, a non-zero value if an error occurred.

• Data reading function: It is called repeatedly to read the data file.

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

  buf points to the buffer that stores the read data, and buf_len indicates the maximum number of bytes that can be read during a callback and are stored in the buffer. The return value is the number of bytes that have been read, or 0 when no more data could be read (indicating EOF). If an error occurs, a value smaller than 0 is returned.

• Termination function: It is called once after local_infile_read() returns 0 (EOF) or an error.

  void
  local_infile_end(void *ptr)
  

  Within this function, the memory allocated by local_infile_init() is freed and necessary cleanup is performed. It is called even if the initialization function returns an error.

• Error handling function: It is called to obtain a textual error message and return the error message to the user when any of other functions returns an error.

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

  error_msg points to the buffer into which the message is written, and error_msg_len indicates the length of the buffer. The message is written as a null-terminated string, with a maximum length of error_msg_len−1 bytes. The return value is an error number.

  Generally, other callbacks store an error message in the data structure that ptr points to, so that local_infile_error() can copy the message to error_msg.

After calling mysql_set_local_infile_handler() in C code and passing pointers to the callback functions, you can issue a LOAD DATA LOCAL statement by using mysql_real_query() or mysql_query(). The client library automatically calls the callbacks. The file name specified in LOAD DATA LOCAL will be passed as the second argument to the local_infile_init() callback.