Event_reader class purpose is to avoid out-of-buffer reads when deserializing binary log events and increase robustness when dealing with corrupted event buffers. More...

#include <event_reader.h>

Public Member Functions
	Event_reader (const char *buffer, unsigned long long length)
	Event_reader constructor. More...

bool	has_error ()
	Returns if the Event_reader is in an error state or not. More...

const char *	get_error ()
	Returns the pointer to the error message. More...

void	set_error (const char *error)
	Sets Event_reader error state by setting the error message. More...

unsigned long long	length ()
	Returns the Event_reader buffer length. More...

void	set_length (unsigned long long length)
	Sets Event_reader buffer length and limit. More...

void	shrink_limit (unsigned long long bytes)
	Shrinks the Event_reader buffer limit. More...

const char *	buffer ()
	Returns the Event_reader buffer pointer. More...

const char *	ptr ()
	Returns a pointer to the Event_reader cursor (next position to be read by the Event_reader functions). More...

const char *	ptr (unsigned long long length)
	Returns a pointer to the Event_reader cursor (next position to be read) and moves the cursor forward. More...

unsigned long long	position ()
	Returns the current Event_reader cursor position in bytes. More...

unsigned long long	available_to_read ()
	Returns the amount of bytes still available to read from cursor position. More...

bool	can_read (unsigned long long bytes)
	Returns if the Event_reader can read a given amount of bytes from cursor position. More...

const char *	go_to (unsigned long long position)
	Moves cursor to a given absolute buffer position and returns the pointer to the cursor. More...

const char *	forward (unsigned long long bytes)
	Moves the buffer position forward to a given relative position and returns the pointer to the buffer on the specified position. More...

template<class T >
T	memcpy ()
	Copies a basic type - bool, char, int, long, double, etc - from the buffer, moves the cursor forward the number of bytes returned by sizeof(T)) and returns the copied value. More...

template<typename T >
T	read (unsigned char bytes=sizeof(T))
	Copies a basic arithmetic type - uint8_t, [u]int16_t, [u]int32_t, [u]int64_t - from the buffer, moves the cursor forward using specified bytes parameter (or the number of bytes returned by sizeof(T) when not specified) and returns the copied value transformed from little endian if necessary). More...

template<typename T >
T	strndup (size_t length)
	Returns a pointer to a new string which is a duplicate of the input string. More...

template<typename T >
void	memcpy (T destination, size_t length)
	Copies from the cursor to an already existent (and allocated) buffer and moves forward the cursor. More...

void	alloc_and_memcpy (unsigned char **destination, size_t length, int flags)
	Allocates memory to a destination buffer, copies from the cursor to the destination buffer using memcpy() and moves forward the cursor. More...

void	alloc_and_strncpy (char **destination, size_t length, int flags)
	Allocates memory to a destination buffer, copies from the cursor to the destination buffer using strncpy() and moves forward the cursor. More...

void	read_str_at_most_255_bytes (const char *destination, uint8_t length)
	Reads string from cursor. More...

uint64_t	net_field_length_ll ()
	Reads a packed value. More...

void	read_data_set (uint32_t set_len, std::list< const char * > *set)
	Reads a transaction context data set. More...

void	read_data_map (uint32_t map_len, std::map< std::string, std::string > *map)
	Reads a view change certification map. More...

void	strncpyz (char *destination, size_t max_length, size_t dest_length)
	Copy a string into the destination buffer up to a max length. More...

void	assign (std::vector< uint8_t > *destination, size_t length)
	Fills a vector with a sequence of bytes from the cursor. More...

Private Member Functions
uint16_t	letoh (uint16_t value)
	Wrapper to le16toh to be used by read function. More...

int32_t	letoh (int32_t value)
	Wrapper to le32toh to be used by read function. More...

uint32_t	letoh (uint32_t value)
	Wrapper to le32toh to be used by read function. More...

int64_t	letoh (int64_t value)
	Wrapper to le64toh to be used by read function. More...

uint64_t	letoh (uint64_t value)
	Wrapper to le64toh to be used by read function. More...

Private Attributes
const char *	m_buffer

const char *	m_ptr

unsigned long long	m_length

unsigned long long	m_limit

const char *	m_error

Detailed Description

Event_reader class purpose is to avoid out-of-buffer reads when deserializing binary log events and increase robustness when dealing with corrupted event buffers.

The Event_reader is composed by a pointer to the beginning of the serialized event buffer (m_buffer), a variable containing the buffer length (m_length), a cursor pointer that tells the current position to be read from the buffer (m_ptr) and the buffer limit the reader shall respect (m_limit <= m_length).

All buffer reading functions shall move the cursor forward.

Before reading from the buffer, the Event_reader will check if the amount of bytes expected to be read are less or equal to the remaining bytes to read:

remaining = m_limit - (m_ptr - m_buffer)

When there are no enough bytes to read from the buffer, Event_reader enters in error state, so its owner can take an action.

Constructor & Destructor Documentation

◆ Event_reader()

binary_log::Event_reader::Event_reader	(	const char *	buffer,
		unsigned long long	length
	)

inline

Event_reader constructor.

It sets the cursor to the first position of the buffer.

Parameters

[in]	buffer	buffer holding a serialized event
[in]	length	known buffer length.

Member Function Documentation

◆ alloc_and_memcpy()

void binary_log::Event_reader::alloc_and_memcpy	(	unsigned char **	destination,
		size_t	length,
		int	flags
	)

Allocates memory to a destination buffer, copies from the cursor to the destination buffer using memcpy() and moves forward the cursor.

This function is useful for pairs of fields when a first field describes the second field size and the deserialization procedure must allocate a buffer for the second field and then copy the event buffer content to the new allocated buffer.

Before implementing this function and the Event_reader, the deserialization process did like:

memcpy(length, ptr, sizeof(length); ptr+=sizeof(length); field = malloc(length); memcpy(field, ptr, length);

Allocating the memory for the field before knowing if the content can be read from the event buffer is a mistake, as it might allocate a very large amount of memory that will not be used.

So, alloc_and_memcpy ensures that it will only allocate memory for the field if it can be read from the event buffer, avoiding allocating a memory that will not be used.

Parameters

[out]	destination	the destination buffer.
[in]	length	the amount of bytes to allocate and read from the buffer (and to move forward).
[in]	flags	flags to pass to MySQL server my_malloc() function.

◆ alloc_and_strncpy()

void binary_log::Event_reader::alloc_and_strncpy	(	char **	destination,
		size_t	length,
		int	flags
	)

Allocates memory to a destination buffer, copies from the cursor to the destination buffer using strncpy() and moves forward the cursor.

See comments on alloc_and_memcpy() for more details.

Parameters

[out]	destination	the destination buffer.
[in]	length	the amount of bytes to allocate and read from the buffer (and to forward).
[in]	flags	flags to pass to MySQL server my_malloc() function.

◆ assign()

void binary_log::Event_reader::assign	(	std::vector< uint8_t > *	destination,
		size_t	length
	)

Fills a vector with a sequence of bytes from the cursor.

Parameters

[out]	destination	the vector be filled.
[in]	length	the amount of bytes to read from the cursor (and to move forward).

◆ available_to_read()

unsigned long long binary_log::Event_reader::available_to_read ( )

inline

Returns the amount of bytes still available to read from cursor position.

Returns: the amount of bytes still available to read.

◆ buffer()

const char * binary_log::Event_reader::buffer ( )

inline

Returns the Event_reader buffer pointer.

Returns: the Event_reader buffer pointer.

◆ can_read()

bool binary_log::Event_reader::can_read ( unsigned long long bytes )

inline

Returns if the Event_reader can read a given amount of bytes from cursor position.

Parameters

bytes the amount of bytes expected to be read.

Return values

true	if the Event_reader can read the specified amount of bytes.
false	if the Event_reader cannot read the specified amount of bytes.

◆ forward()

const char * binary_log::Event_reader::forward ( unsigned long long bytes )

inline

Moves the buffer position forward to a given relative position and returns the pointer to the buffer on the specified position.

Parameters

bytes the amount of bytes to move forward.

Return values

pointer	a pointer to the new buffer position.
nullptr	if the cursor is out of buffer boundaries.

◆ get_error()

const char * binary_log::Event_reader::get_error ( )

inline

Returns the pointer to the error message.

Returns: the pointer to the error message when Event_reader is in error state, or a nullptr otherwise.

◆ go_to()

const char * binary_log::Event_reader::go_to ( unsigned long long position )

Moves cursor to a given absolute buffer position and returns the pointer to the cursor.

Parameters

position the position to jump to.

Return values

pointer	a pointer to the new cursor position.
nullptr	if the position is out of buffer boundaries.

◆ has_error()

bool binary_log::Event_reader::has_error ( )

inline

Returns if the Event_reader is in an error state or not.

Return values

true	if the Event_reader is in error state.
false	if the Event_reader is not in error state.

◆ length()

unsigned long long binary_log::Event_reader::length ( )

inline

Returns the Event_reader buffer length.

Note: the buffer length might be larger than reader allowed buffer limit, but the Event_reader will enter error state when trying to read above the limit.

Example: an event buffer may contain the serialized event + checksum. The event reader object will be configured with a buffer length that contains both the serialized event and the checksum information, but once Log_event_footer is instantiated, it shall adjust the event reader buffer limit to the buffer position right before the checksum. This will avoid some event deserialization relying on event buffer size to assume the checksum as serialized event content.

Returns: the Event_reader buffer length.

◆ letoh() [1/5]

int32_t binary_log::Event_reader::letoh ( int32_t value )

inlineprivate

Wrapper to le32toh to be used by read function.

Parameters

[in] value the value to be converted.

Returns: the converted value.

◆ letoh() [2/5]

int64_t binary_log::Event_reader::letoh ( int64_t value )

inlineprivate

Wrapper to le64toh to be used by read function.

Parameters

[in] value the value to be converted.

Returns: the converted value.

◆ letoh() [3/5]

uint16_t binary_log::Event_reader::letoh ( uint16_t value )

inlineprivate

Wrapper to le16toh to be used by read function.

Parameters

[in] value the value to be converted.

Returns: the converted value.

◆ letoh() [4/5]

uint32_t binary_log::Event_reader::letoh ( uint32_t value )

inlineprivate

Wrapper to le32toh to be used by read function.

Parameters

[in] value the value to be converted.

Returns: the converted value.

◆ letoh() [5/5]

uint64_t binary_log::Event_reader::letoh ( uint64_t value )

inlineprivate

Wrapper to le64toh to be used by read function.

Parameters

[in] value the value to be converted.

Returns: the converted value.

◆ memcpy() [1/2]

template<class T >

T binary_log::Event_reader::memcpy ( )

inline

Copies a basic type - bool, char, int, long, double, etc - from the buffer, moves the cursor forward the number of bytes returned by sizeof(T)) and returns the copied value.

Return values

value	the T copied from the cursor position.
0	if the cursor was out of buffer boundaries.

◆ memcpy() [2/2]

template<typename T >

void binary_log::Event_reader::memcpy	(	T	destination,
		size_t	length
	)

inline

Copies from the cursor to an already existent (and allocated) buffer and moves forward the cursor.

Parameters

[out]	destination	a pointer to the destination buffer.
[in]	length	the amount of bytes to read from the buffer (and to move forward).

◆ net_field_length_ll()

uint64_t binary_log::Event_reader::net_field_length_ll ( )

Reads a packed value.

This function can move the cursor forward by 1, 3, 4 or 9 bytes depending on the value to be returned.

Returns: the packed value.

◆ position()

unsigned long long binary_log::Event_reader::position ( )

inline

Returns the current Event_reader cursor position in bytes.

Return values

m_limit	if cursor position is invalid.
position	current Event_reader cursor position (if valid).

◆ ptr() [1/2]

const char * binary_log::Event_reader::ptr ( )

inline

Returns a pointer to the Event_reader cursor (next position to be read by the Event_reader functions).

Returns: the pointer to the Event_reader cursor.

◆ ptr() [2/2]

const char * binary_log::Event_reader::ptr ( unsigned long long length )

Returns a pointer to the Event_reader cursor (next position to be read) and moves the cursor forward.

This function is used when the buffer contains a field of a known size and the deserialization procedure must keep the pointer to the field but moving the cursor to after it.

Parameters

[in] length the amount of bytes to move the cursor forward.

Returns: the pointer to the Event_reader cursor before forwarding it.

◆ read()

template<typename T >

T binary_log::Event_reader::read ( unsigned char bytes = sizeof(T) )

inline

Copies a basic arithmetic type - uint8_t, [u]int16_t, [u]int32_t, [u]int64_t - from the buffer, moves the cursor forward using specified bytes parameter (or the number of bytes returned by sizeof(T) when not specified) and returns the copied value transformed from little endian if necessary).

Parameters

[in] bytes the amount of bytes to read from the buffer (and to move forward). When not specified, will use sizeof(T).

Return values

value	the T copied from the cursor position.
0	if the cursor was out of buffer boundaries or there was no memory to allocate to the new string..

◆ read_data_map()

void binary_log::Event_reader::read_data_map	(	uint32_t	map_len,
		std::map< std::string, std::string > *	map
	)

Reads a view change certification map.

Parameters

[in]	map_len	the length of the certification info map (and to move forward).
[out]	map	the certification info map to be filled.

◆ read_data_set()

void binary_log::Event_reader::read_data_set	(	uint32_t	set_len,
		std::list< const char * > *	set
	)

Reads a transaction context data set.

Parameters

[in]	set_len	length of the set object (and to move forward).
[out]	set	pointer to the set object to be filled.

◆ read_str_at_most_255_bytes()

void binary_log::Event_reader::read_str_at_most_255_bytes	(	const char **	destination,
		uint8_t *	length
	)

Reads string from cursor.

Reads in the following format: 1) Reads length stored on cursor first index. Moves cursor forward 1 byte. 2) Set destination pointer to the cursor. Moves cursor forward length bytes.

Parameters

[out]	destination	the destination pointer.
[out]	length	the amount of bytes to allocate and read from the buffer (and to move forward).

◆ set_error()

void binary_log::Event_reader::set_error ( const char * error )

Sets Event_reader error state by setting the error message.

Parameters

[in] error pointer to the error message.

◆ set_length()

void binary_log::Event_reader::set_length ( unsigned long long length )

Sets Event_reader buffer length and limit.

The length of the buffer should only be set to values greater or equal to the current buffer length. Trying to set the length to less than current buffer length will make the Event_buffer to enter error state.

The length is initially set in Event_reader constructor to LOG_EVENT_MINIMAL_HEADER_LEN by the Log_event_header when instantiating it. This should be enough to read the event header and determine the correct buffer length. The Log_event_header will adjust the Event_reader length by calling this function based on the value of event data_written header field.

Parameters

[in] length the new Event_reader buffer length.

◆ shrink_limit()

void binary_log::Event_reader::shrink_limit ( unsigned long long bytes )

Shrinks the Event_reader buffer limit.

This function is used by Log_event_footer to remove the checksum payload (if necessary) from the serialized event size, as many event types rely on the serialized event size to determine the size of some fields.

Parameters

[in] bytes the amount of bytes to shrink the Event_reader buffer length.

◆ strncpyz()

void binary_log::Event_reader::strncpyz	(	char *	destination,
		size_t	max_length,
		size_t	dest_length
	)

Copy a string into the destination buffer up to a max length.

Parameters

[out]	destination	the destination buffer.
[in]	max_length	the max length to copy from the cursor.
[in]	dest_length	the max length supported by the destination buffer.

◆ strndup()

template<typename T >

T binary_log::Event_reader::strndup ( size_t length )

inline

Returns a pointer to a new string which is a duplicate of the input string.

The terminating null character is added. See: bapi_strndup().

Parameters

[in] length the amount of bytes to read from the buffer (and to move forward).

Return values

pointer	the T pointer from the cursor position.
nullptr	if the cursor was out of buffer boundaries.

Member Data Documentation

◆ m_buffer

const char* binary_log::Event_reader::m_buffer

private

◆ m_error

const char* binary_log::Event_reader::m_error

private

◆ m_length

unsigned long long binary_log::Event_reader::m_length

private

◆ m_limit

unsigned long long binary_log::Event_reader::m_limit

private

◆ m_ptr

const char* binary_log::Event_reader::m_ptr

private

The documentation for this class was generated from the following files:

libbinlogevents/include/event_reader.h
libbinlogevents/src/event_reader.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Event_reader()

Member Function Documentation

◆ alloc_and_memcpy()

◆ alloc_and_strncpy()

◆ assign()

◆ available_to_read()

◆ buffer()

◆ can_read()

◆ forward()

◆ get_error()

◆ go_to()

◆ has_error()

◆ length()

◆ letoh() [1/5]

◆ letoh() [2/5]

◆ letoh() [3/5]

◆ letoh() [4/5]

◆ letoh() [5/5]

◆ memcpy() [1/2]

◆ memcpy() [2/2]

◆ net_field_length_ll()

◆ position()

◆ ptr() [1/2]

◆ ptr() [2/2]

◆ read()

◆ read_data_map()

◆ read_data_set()

◆ read_str_at_most_255_bytes()

◆ set_error()

◆ set_length()

◆ shrink_limit()

◆ strncpyz()

◆ strndup()

Member Data Documentation

◆ m_buffer

◆ m_error

◆ m_length

◆ m_limit

◆ m_ptr