error_handling.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.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_SAFE_FWRITE_TO_STDERR(msg)   fwrite(msg, sizeof(char), strlen(msg), stderr)
#define	RCUTILS_CHECK_ARGUMENT_FOR_NULL(argument, error_return_type, allocator)
	Check an argument for a null value. More...
#define	RCUTILS_CHECK_FOR_NULL_WITH_MSG(value, msg, error_statement, allocator)
	Check a value for null, with an error message and error statement. More...
#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...
#define	RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING(allocator, format_string, ...)
	Set the error message using a format string and format arguments. 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_SAFE_FWRITE_TO_STDERR

#define RCUTILS_SAFE_FWRITE_TO_STDERR

(

msg

)

fwrite(msg, sizeof(char), strlen(msg), stderr)

RCUTILS_CHECK_ARGUMENT_FOR_NULL

#define RCUTILS_CHECK_ARGUMENT_FOR_NULL	(		argument,
			error_return_type,
			allocator
	)

Value:

RCUTILS_CHECK_FOR_NULL_WITH_MSG(argument, #argument " argument is null", \
    return error_return_type, allocator)

Check an argument for a null value.

If the argument's value is NULL, set the error message saying so and return the error_return_type.

Parameters

[in]	argument	The argument to test.
[in]	error_return_type	The type to return if the argument is NULL.
[in]	allocator	The allocator to use if an error message needs to be allocated.

RCUTILS_CHECK_FOR_NULL_WITH_MSG

#define RCUTILS_CHECK_FOR_NULL_WITH_MSG	(		value,
			msg,
			error_statement,
			allocator
	)

Value:

if (!(value)) { \
    RCUTILS_SET_ERROR_MSG(msg, allocator); \
    error_statement; \
  }

Check a value for null, with an error message and error statement.

If value is NULL, the error statement will be evaluated after setting the error message.

Parameters

[in]	value	The value to test.
[in]	msg	The error message if value is NULL.
[in]	error_statement	The statement to evaluate if value is NULL.
[in]	allocator	The allocator to use if an error message needs to be allocated.

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.

RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING

#define RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING	(		allocator,
			format_string,
			...
	)

Value:

do { \
    char * output_msg = NULL; \
    output_msg = rcutils_format_string(allocator, format_string, __VA_ARGS__); \
    if (output_msg) { \
      RCUTILS_SET_ERROR_MSG(output_msg, allocator); \
      allocator.deallocate(output_msg, allocator.state); \
    } else { \
      RCUTILS_SAFE_FWRITE_TO_STDERR("Failed to allocate memory for error message\n"); \
    } \
  } while (false)

Set the error message using a format string and format arguments.

This function sets the error message using the given format string and then frees the memory allocated during the string formatting.

Parameters

[in]	allocator	The allocator to be used when allocating space for the error state.
[in]	format_string	The string to be used as the format of the error message.
[in]	...	Arguments for the format string.

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.