error_handling.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include "rcutils/allocator.h"
#include "rcutils/macros.h"
#include "rcutils/types/rcutils_ret.h"
#include "rcutils/visibility_control.h"

Go to the source code of this file.

Classes
struct	rcutils_error_state_t
	Struct which encapsulates the error state set by RCUTILS_SET_ERROR_MSG(). More...

Macros
#define	RCUTILS_SET_ERROR_MSG(msg, allocator)   rcutils_set_error_state(msg, __FILE__, __LINE__, allocator);
	Set the error message, as well as append the current file and line number. More...

Typedefs
typedef struct rcutils_error_state_t	rcutils_error_state_t
	Struct which encapsulates the error state set by RCUTILS_SET_ERROR_MSG(). More...

Functions
rcutils_ret_t	rcutils_error_state_copy (const rcutils_error_state_t *src, rcutils_error_state_t *dst)
	Copy an error state into a destination error state. More...
void	rcutils_error_state_fini (rcutils_error_state_t *error_state)
	Finalizes a copied error state. More...
void	rcutils_set_error_state (const char *error_msg, const char *file, size_t line_number, rcutils_allocator_t allocator)
	Set the error message, as well as the file and line on which it occurred. More...
bool	rcutils_error_is_set (void)
	Return true if the error is set, otherwise false. More...
const rcutils_error_state_t *	rcutils_get_error_state (void)
	Return an rcutils_error_state_t which was set with rcutils_set_error_state(). More...
const char *	rcutils_get_error_string (void)
	Return the error message followed by , at <file>:<line>, or NULL. More...
const char *	rcutils_get_error_string_safe (void)
	Return the error message followed by , at <file>:<line> if set, else "error not set". More...
void	rcutils_reset_error (void)
	Reset the error state by clearing any previously set error state. More...

Macro Definition Documentation

RCUTILS_SET_ERROR_MSG

#define RCUTILS_SET_ERROR_MSG	(		msg,
			allocator
	)		rcutils_set_error_state(msg, __FILE__, __LINE__, allocator);

Set the error message, as well as append the current file and line number.

If an error message was previously set, and rcutils_reset_error() was not called afterwards, and this library was built with RCUTILS_REPORT_ERROR_HANDLING_ERRORS turned on, then the previously set error message will be printed to stderr. Error state storage is thread local and so all error related functions are also thread local.

Parameters

[in]	msg	The error message to be set.
[in]	allocator	The allocator to be used when allocating space for the error state.

Typedef Documentation

rcutils_error_state_t

typedef struct rcutils_error_state_t rcutils_error_state_t

Struct which encapsulates the error state set by RCUTILS_SET_ERROR_MSG().

Function Documentation

rcutils_error_state_copy()

rcutils_ret_t rcutils_error_state_copy	(	const rcutils_error_state_t *	src,
		rcutils_error_state_t *	dst
	)

Copy an error state into a destination error state.

The destination state must be empty, the memory will not be free'd. The allocator from the source is used to allocate memory in the dst.

The copied error_state should be finalized with rcutils_error_state_fini().

Parameters

[in]	src	the error state to copy from
[out]	dst	the error state to copy into

Returns

RCUTILS_RET_OK if successful, or

RCUTILS_RET_BAD_ALLOC if memory allocation fails, or

RCUTILS_RET_ERROR if an unknown error occurs.

rcutils_error_state_fini()

void rcutils_error_state_fini

(

rcutils_error_state_t *

error_state

)

Finalizes a copied error state.

rcutils_set_error_state()

void rcutils_set_error_state	(	const char *	error_msg,
		const char *	file,
		size_t	line_number,
		rcutils_allocator_t	allocator
	)

Set the error message, as well as the file and line on which it occurred.

This is not meant to be used directly, but instead via the RCUTILS_SET_ERROR_MSG(msg) macro.

The error_msg parameter is copied into the internal error storage and must be null terminated. The file parameter is not copied, but instead is assumed to be a global as it should be set to the FILE preprocessor literal when used with the RCUTILS_SET_ERROR_MSG() macro. It should also be null terminated.

The allocator is kept within the error state so that it can be used to deallocate it in the future. Therefore the allocator state needs to exist until after the last time rcutils_reset_error() is called.

Parameters

[in]	error_msg	The error message to set.
[in]	file	The path to the file in which the error occurred.
[in]	line_number	The line number on which the error occurred.
[in]	allocator	The allocator to be used when allocating space for the error state.

rcutils_error_is_set()

bool rcutils_error_is_set

(

void

)

Return true if the error is set, otherwise false.

rcutils_get_error_state()

const rcutils_error_state_t* rcutils_get_error_state

(

void

)

Return an rcutils_error_state_t which was set with rcutils_set_error_state().

The returned pointer will be NULL if no error has been set in this thread.

The returned pointer is valid until RCUTILS_SET_ERROR_MSG, rcutils_set_error_state, or rcutils_reset_error are called in the same thread.

Returns

A pointer to the current error state struct.

rcutils_get_error_string()

const char* rcutils_get_error_string

(

void

)

Return the error message followed by , at <file>:<line>, or NULL.

The returned pointer is valid until RCUTILS_SET_ERROR_MSG(), rcutils_set_error_state(), or rcutils_reset_error() are called from the same thread.

Returns

The current formatted error string, or NULL if not set.

rcutils_get_error_string_safe()

const char* rcutils_get_error_string_safe

(

void

)

Return the error message followed by , at <file>:<line> if set, else "error not set".

This function is guaranteed to return a valid c-string.

The returned pointer is valid until RCUTILS_SET_ERROR_MSG, rcutils_set_error_state, or rcutils_reset_error are called in the same thread.

Returns

The current error string, with file and line number, or "error not set" if not set.

rcutils_reset_error()

void rcutils_reset_error

(

void

)

Reset the error state by clearing any previously set error state.