rcutils  master
C API providing common utilities and data structures.
Classes | Macros | Typedefs | Functions
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_trcutils_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)
#define RCUTILS_CHECK_FOR_NULL_WITH_MSG(value, msg, error_statement, allocator)
Check a value for null, with an error message and error statement.
Definition: error_handling.h:127

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]argumentThe argument to test.
[in]error_return_typeThe type to return if the argument is NULL.
[in]allocatorThe 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]valueThe value to test.
[in]msgThe error message if value is NULL.
[in]error_statementThe statement to evaluate if value is NULL.
[in]allocatorThe 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]msgThe error message to be set.
[in]allocatorThe 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)
#define rcutils_format_string(allocator, format_string,...)
Return a newly allocated string, created with a format string.
Definition: format_string.h:35

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]allocatorThe allocator to be used when allocating space for the error state.
[in]format_stringThe string to be used as the format of the error message.
[in]...Arguments for the format string.

Typedef Documentation

◆ 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]srcthe error state to copy from
[out]dstthe 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_msgThe error message to set.
[in]fileThe path to the file in which the error occurred.
[in]line_numberThe line number on which the error occurred.
[in]allocatorThe 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.