Detailed Description

Provides standardized error numbers and error handling routines.

Error reporting follows the design and conventions used in the GNU Scientific Library (GSL) error handling routines. Much of ESIO's error code is a direct copy of GSL's API and source code. Notable exceptions are the MPI error handling macros which are an improved copy of ideas found in PETSc.

Go to the source code of this file.

Typedefs
typedef void	esio_error_handler_t (const char reason, const char file, int line, int esio_errno)
	Defines the function prototype necessary for an error handler.

typedef void	esio_stream_handler_t (const char label, const char file, int line, const char *reason)
	Defines the function prototype necessary for a stream handler.

Enumerations
enum	esio_status { ESIO_SUCCESS = 0, ESIO_EFAULT = 3, ESIO_EINVAL = 4, ESIO_EFAILED = 5, ESIO_ESANITY = 7, ESIO_ENOMEM = 8, ESIO_NOTFOUND = 9 }
	Standardized error status codes used throughout ESIO. More...

Functions
void	esio_error (const char reason, const char file, int line, int esio_errno)
	Calls the error handler last set using esio_set_error_handler when invoked.

void	esio_stream_printf (const char label, const char file, int line, const char *reason)
	Print an error message to the current error stream.

const char *	esio_strerror (const int esio_errno)
	Look up a human-readable error message for the given error status.

esio_error_handler_t *	esio_set_error_handler (esio_error_handler_t *new_handler)
	Sets the current error handler for the process.

esio_error_handler_t *	esio_set_error_handler_off (void)
	An error handler implementation that disables all error reporting.

esio_stream_handler_t *	esio_set_stream_handler (esio_stream_handler_t *new_handler)
	Sets the current stream handler for the process.

FILE *	esio_set_stream (FILE *new_stream)
	Set the default stream for error message display.

Macros
#define	ESIO_ERROR(reason, esio_errno)
	Invokes esio_error and returns the value `esio_errno`.

#define	ESIO_ERROR_VAL(reason, esio_errno, value)
	Invokes esio_error using `esio_errno` and returns the value `value`.

#define	ESIO_ERROR_VOID(reason, esio_errno)
	Invokes esio_error using `esio_errno` and returns from the current function.

#define	ESIO_ERROR_NULL(reason, esio_errno) ESIO_ERROR_VAL(reason, esio_errno, 0)
	Invokes esio_error using `esio_errno` and returns NULL from the current function.

#define	ESIO_ERROR_REPORT(reason, esio_errno)
	Invokes esio_error using `esio_errno` but does not return from the current function.

#define	ESIO_MPICHKQ(stmt) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR,stmt)
	Executes `stmt` once handling any resulting MPI error per `ESIO_ERROR`.

#define	ESIO_MPICHKN(stmt) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR_NULL,stmt)
	Executes `stmt` once handling any resulting MPI error per `ESIO_ERROR_NULL`.

#define	ESIO_MPICHKV(stmt) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR_VOID,stmt)
	Executes `stmt` once handling any resulting MPI error per `ESIO_ERROR_VOID`.

#define	ESIO_MPICHKR(stmt) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR_REPORT,stmt)
	Executes `stmt` once handling any resulting MPI error per `ESIO_ERROR_REPORT`.

Typedef Documentation

typedef void esio_error_handler_t(const char *reason, const char *file, int line, int esio_errno)

Defines the function prototype necessary for an error handler.

Error handlers should be reentrant safe if possible.

Parameters

reason	Reason for the error.
file	File in which the error was reported.
line	Line at which the error was reported.
esio_errno	Error code to report.

See Also: esio_set_error_handler

typedef void esio_stream_handler_t(const char *label, const char *file, int line, const char *reason)

Defines the function prototype necessary for a stream handler.

Stream handlers should be reentrant safe if possible.

Parameters

reason	Reason for the error.
file	File in which the error was reported.
line	Line at which the error was reported.
esio_errno	Error code to report.

See Also: esio_set_stream_handler

Enumeration Type Documentation

enum esio_status

Standardized error status codes used throughout ESIO.

Where possible these codes are numerically equivalent to GSL's error codes.

Note that ESIO_SUCCESS is zero to allow code like if (!status) { some_error_handling() }.

Enumerator:

ESIO_SUCCESS	Success.
ESIO_EFAULT	Invalid pointer.
ESIO_EINVAL	Invalid argument supplied by user.
ESIO_EFAILED	Generic failure.
ESIO_ESANITY	Sanity check failed - shouldn't happen.
ESIO_ENOMEM	Memory allocation failed.
ESIO_NOTFOUND	Object not found.

Function Documentation

void esio_error	(	const char *	reason,
		const char *	file,
		int	line,
		int	esio_errno
	)

Calls the error handler last set using esio_set_error_handler when invoked.

This is the entry point to the error handling system.

The default behavior is to log the error to the stream specified using esio_set_stream. The functions esio_set_stream, esio_set_stream_handler, and esio_set_error_handler can be used to modify this behavior.

Parameters

reason	Reason for the error.
file	File in which the error was reported.
line	Line at which the error was reported.
esio_errno	Error code to report. Should be one of esio_status if at all possible.

See Also: Most clients should not use this function directly; instead use one of the convenience macros: ESIO_ERROR, ESIO_ERROR_VAL, ESIO_ERROR_VOID, ESIO_ERROR_NULL

esio_error_handler_t* esio_set_error_handler ( esio_error_handler_t * new_handler )

Sets the current error handler for the process.

Invoked by esio_error when an error occurs.

Parameters

new_handler New error handler to use.

Returns: the previous error handler in use.

esio_error_handler_t* esio_set_error_handler_off ( void )

An error handler implementation that disables all error reporting.

Primarily intended for use in test environments.

Returns: the previous error handler in use.

FILE* esio_set_stream ( FILE * new_stream )

Set the default stream for error message display.

Default behavior is to use stderr.

Parameters

new_stream New stream to use.

Returns: the previous stream in use.

esio_stream_handler_t* esio_set_stream_handler ( esio_stream_handler_t * new_handler )

Sets the current stream handler for the process.

Used by the default error handling behavior, and possibly by other custom error handling routines.

Parameters

new_handler New stream handler to use.

Returns: the previous stream handler in use.

void esio_stream_printf	(	const char *	label,
		const char *	file,
		int	line,
		const char *	reason
	)

Print an error message to the current error stream.

If a esio_stream_handler_t has been specified, it is used. If a stream has been set using esio_set_stream, it is used. Lastly, the routine prints the error message to standard error.

Parameters

label	Label used to identify the error.
file	File in which the error was reported.
line	Line at which the error was reported.
reason	Reason for the error.

const char* esio_strerror ( const int esio_errno )

Look up a human-readable error message for the given error status.

Parameters

esio_errno Error code to look up.

Returns: A message suitable for use in logging or error messages.

Macro Definition Documentation

#define ESIO_ERROR	(	reason,
		esio_errno
	)

Value:

do { \
       esio_error (reason, __FILE__, __LINE__, esio_errno) ; \
       return esio_errno ; \
       } while (0)

Invokes esio_error and returns the value esio_errno.

Automatically provides file and line information.

Parameters

reason	Message to report.
esio_errno	Error status to report and returned from the current function.

#define ESIO_ERROR_NULL	(	reason,
		esio_errno
	)	ESIO_ERROR_VAL(reason, esio_errno, 0)

Invokes esio_error using esio_errno and returns NULL from the current function.

Useful for out-of-memory conditions. Automatically provides file and line information.

Parameters

reason	Message to report.
esio_errno	Error status to report.

#define ESIO_ERROR_REPORT	(	reason,
		esio_errno
	)

Value:

do { \
       esio_error (reason, __FILE__, __LINE__, esio_errno) ; \
       } while (0)

Invokes esio_error using esio_errno but does not return from the current function.

Automatically provides file and line information.

Parameters

reason	Message to report.
esio_errno	Error status to report.

#define ESIO_ERROR_VAL	(	reason,
		esio_errno,
		value
	)

Value:

do { \
       esio_error (reason, __FILE__, __LINE__, esio_errno) ; \
       return value ; \
       } while (0)

Invokes esio_error using esio_errno and returns the value value.

Automatically provides file and line information.

Parameters

reason	Message to report.
esio_errno	Error status to report.
value	Value to return from the current function.

#define ESIO_ERROR_VOID	(	reason,
		esio_errno
	)

Value:

do { \
       esio_error (reason, __FILE__, __LINE__, esio_errno) ; \
       return ; \
       } while (0)

Invokes esio_error using esio_errno and returns from the current function.

Automatically provides file and line information.

Parameters

reason	Message to report.
esio_errno	Error status to report.

#define ESIO_MPICHKN ( stmt ) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR_NULL,stmt)

Executes stmt once handling any resulting MPI error per ESIO_ERROR_NULL.

Any relevant message is looked up using MPI_Error_string and reported.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: esio/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See Also: PETSc's CHKERRQ for the original inspiration for this macro.

#define ESIO_MPICHKQ ( stmt ) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR,stmt)

Executes stmt once handling any resulting MPI error per ESIO_ERROR.

Any relevant message is looked up using MPI_Error_string and reported. ESIO_EFAILED is the return value provided to ESIO_ERROR.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: esio/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See Also: PETSc's CHKERRQ for the original inspiration for this macro.

#define ESIO_MPICHKR ( stmt ) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR_REPORT,stmt)

Executes stmt once handling any resulting MPI error per ESIO_ERROR_REPORT.

The current function continues executing. Any relevant message is looked up using MPI_Error_string and reported.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: esio/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See Also: PETSc's CHKERRV for the original inspiration for this macro.

#define ESIO_MPICHKV ( stmt ) ESIO_MPICHKx_TEMPLATE(ESIO_ERROR_VOID,stmt)

Executes stmt once handling any resulting MPI error per ESIO_ERROR_VOID.

Any relevant message is looked up using MPI_Error_string and reported.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: esio/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See Also: PETSc's CHKERRV for the original inspiration for this macro.

Detailed Description

Typedefs

Enumerations

Functions

Macros

Typedef Documentation

Enumeration Type Documentation

Function Documentation

Macro Definition Documentation