Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 45.2Mb
PDF (A4) - 45.2Mb
PDF (RPM) - 40.9Mb
HTML Download (TGZ) - 10.6Mb
HTML Download (Zip) - 10.6Mb
HTML Download (RPM) - 9.2Mb
Man Pages (TGZ) - 207.8Kb
Man Pages (Zip) - 309.9Kb
Info (Gzip) - 4.0Mb
Info (Zip) - 4.0Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  C API Binary Log Data Structures

28.7.19 C API Binary Log Data Structures

C API functions for processing a replication event stream from a server require a connection handler (a MYSQL * pointer) and a pointer to a MYSQL_RPL structure that describes the steam of replication events to read from the server binary log. For example:

MYSQL *mysql = mysql_real_connect(...);


# ... initialize MYSQL_RPL members ...

int result = mysql_binlog_open(mysql, &rpl);

This section describes the MYSQL_RPL structure members. Connection handlers are described in Section 28.7.5, “C API Data Structures”.

The applicable MYSQL_RPL members depend on the binary log operation to be performed:

  • Before calling mysql_binlog_open(), the caller must set the MYSQL_RPL members from file_name_length through flags. In addition, if flags has the MYSQL_RPL_GTID flag set, the caller must set the members from gtid_set_encoded_size through gtid_set_arg.

  • After a successful mysql_binlog_fetch() call, the caller examines the size and buffer members.

MYSQL_RPL structure member descriptions:

  • file_name_length

    The length of the name of the binary log file to read. This member is used in conjunction with file_name; see the file_name description.

  • file_name

    The name of the binary log file to read:

    • If file_name is NULL, the client library sets it to the empty string and sets file_name_length to 0.

    • If file_name is not NULL, file_name_length must either be the length of the name or 0. If file_name_length is 0, the client library sets it to the length of the name, in which case, file_name must be given as a null-terminated string.

    To read from the beginning of the binary log without having to know the name of the oldest binary log file, set file_name to NULL or the empty string, and start_position to 4.

  • start_position

    The position at which to start reading the binary log. The position of the first event in any given binary log file is 4.

  • server_id

    The server ID to use for identifying to the server from which the binary log is read.

  • flags

    The union of flags that affect binary log reading, or 0 if no flags are set. These flag values are permitted:


      Set this flag to cause mysql_binlog_fetch() to skip heartbeat events.


      Set this flag to read GTID (global transaction ID) data. If set, you must initialize the MYSQL_RPL structure GTID-related members from gtid_set_encoded_size to gtid_set_arg before calling mysql_binlog_open().

      It is beyond the scope of this documentation to describe in detail how client programs use those GTID-related members. For more information, examine the source file. For information about GTID-based replication, see Section 17.1.3, “Replication with Global Transaction Identifiers”.

  • gtid_set_encoded_size

    The size of GTID set data, or 0.

  • fix_gtid_set

    The address of a callback function for mysql_binlog_open() to call to fill the command packet GTID set, or NULL if there is no such function. The callback function, if used, should have this calling signature:

    void my_callback(MYSQL_RPL *rpl, unsigned char *packet_gtid_set);
  • gtid_set_arg

    Either a pointer to GTID set data (if fix_gtid_set is NULL), or a pointer to a value to be made available for use within the callback function (if fix_gtid_set is not NULL). gtid_set_arg is a generic pointer, so it can point to any kind of value (for example, a string, a structure, or a function). Its interpretation within the callback depends on how the callback intends to use it.

  • size

    After a successful mysql_binlog_fetch() call, the size of the returned binary log event. The value is 0 for an EOF event, greater than 0 for a non-EOF event.

  • buffer

    After a successful mysql_binlog_fetch() call, a pointer to the binary log event contents.

User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.