Error message handling


Detailed Description

Error propagation is an important and often poorly solved issue in any program. In this library, errors are propagated by employing a dedicated data structure fid_Error plus supporting function.

Data Structures

struct  fid_Error
 Structure for error message handling. More...

Defines

#define fid_ERROR_MAX   ((int)16)
 This is the maximum number of errors that can be stored in an fid_Error structure.
#define fid_ERROR_OCCURRED(ERR)   ((ERR)->num_of_errors > 0)
 Check if an error is stored in fid_Error ERR.
#define fid_OUTOFMEM(ERR)   fid_error_throw(ERR,"Out of memory (%s[%d])",__FILE__,__LINE__)
 Append an out-of-memory error to ERR.

Enumerations

enum  fid_Errormode { fid_ERRORMODE_FIFO = 0, fid_ERRORMODE_DEEPEST, fid_ERRORMODE_KEEP_LAST }
 Error message overflow handling mode. More...

Functions

void fid_error_init (fid_Error *error, fid_Errormode mode)
 Initialize an error structure for detailed error reporting.
void fid_error_init_default (fid_Error *error)
 Initialize an error structure for detailed error reporting.
void fid_error_free (fid_Error *error)
 Free an error structure.
void fid_error_throw (fid_Error *error, const char *fmt,...)
 Append an error message to the error structure.
void fid_error_throw_errno (fid_Error *error, int errnum, const char *fmt,...)
 Append an error message generated from error code to error structure.
int fid_error_dump (const fid_Error *error, FILE *stream)
 Simple error reporting function.

Define Documentation

#define fid_ERROR_MAX   ((int)16)

This is the maximum number of errors that can be stored in an fid_Error structure.

Definition at line 39 of file error.h.

Referenced by fid_error_dump(), fid_error_init(), and fid_error_throw().

#define fid_ERROR_OCCURRED ( ERR   )     ((ERR)->num_of_errors > 0)

Check if an error is stored in fid_Error ERR.

Parameters:
ERR An fid_Error structure.
Returns:
True if an error is available, false otherwise.

Definition at line 89 of file error.h.

Referenced by fid_error_dump().

#define fid_OUTOFMEM ( ERR   )     fid_error_throw(ERR,"Out of memory (%s[%d])",__FILE__,__LINE__)

Append an out-of-memory error to ERR.

Definition at line 94 of file error.h.

Referenced by fid_alphabet_transform_string_new(), fid_filenamebuffer_init(), fid_projectfile_init(), and fid_suffixarray_traverse().


Enumeration Type Documentation

Error message overflow handling mode.

See also:
fid_Error documentation for more details.

Definition at line 46 of file error.h.


Function Documentation

void fid_error_init ( fid_Error error,
fid_Errormode  mode 
)

Initialize an error structure for detailed error reporting.

Parameters:
error The structure to be initialized. This may also be NULL, in which case nothing will happen.
mode Mode of overflow handling. See fid_Error documentation for more details.

Definition at line 47 of file error.c.

References fid_Error::errors, fid_ERROR_MAX, fid_Error::first_error, fid_Error::mode, fid_Error::num_of_errors, fid_Error::outofmem, and fid_Error::overflow.

Referenced by fid_error_init_default().

void fid_error_init_default ( fid_Error error  ) 

Initialize an error structure for detailed error reporting.

Overflow handling mode will be set to the default mode, which is fid_ERRORMODE_FIFO in this version.

Parameters:
error The structure to be initialized. This may also be NULL, in which case nothing will happen.

Definition at line 78 of file error.c.

References fid_error_init().

void fid_error_free ( fid_Error error  ) 

Free an error structure.

This function has reset characteristics, i.e., after this function has been called for a previously initialized fid_Error structure, an extra call of fid_error_init() is not necessary.

Parameters:
error The structure to be freed. This may also be NULL, in which case nothing will happen.

Definition at line 95 of file error.c.

References fid_Error::errors, fid_Error::first_error, fid_Error::num_of_errors, fid_Error::outofmem, and fid_Error::overflow.

void fid_error_throw ( fid_Error error,
const char *  fmt,
  ... 
)

Append an error message to the error structure.

The error structure can be filled with multiple error messages to provide a more detailed picture of the error than a single error message could.

Parameters:
error The error structure that the new error should be appended to. This may also be NULL to disable error reporting.
fmt Format string like that you would pass to printf(), followed by values filled into the format.

Definition at line 249 of file error.c.

References fid_ERROR_MAX, fid_Error::mode, fid_Error::num_of_errors, fid_Error::outofmem, and fid_Error::overflow.

Referenced by fid_alphabet_add_wildcard(), fid_alphabet_init_from_specfile(), fid_alphabet_init_from_speclines(), fid_alphabet_init_from_string(), fid_alphabet_transform_string_new(), fid_error_throw_errno(), fid_file_dump_to_file(), fid_file_ensure_free_space(), fid_file_grow_by_size(), fid_file_make_readonly(), fid_projectfile_init(), fid_sequences_realize(), fid_suffixarray_load_special(), fid_utils_parse_uint_32(), and fid_utils_parse_uint_64().

void fid_error_throw_errno ( fid_Error error,
int  errnum,
const char *  fmt,
  ... 
)

Append an error message generated from error code to error structure.

The generated error message will look very much like what perror() would print. The error code is converted into an error string using strerror(), which is appended to the passed error structure. Optionally, similar to perror(), the error message is generated from the string passed in as fmt, followed by ": ", followed by the error string. As an extension to plain perror(), fmt may be a format string.

Parameters:
error The error structure that the new error should be appended to. This may also be NULL to disable error reporting.
errnum The error code, typically the value of the global errno variable. If set to 0, then error will remain unchanged. This function does not use errno directly.
fmt Optional format string containing an error description, followed by a variable argument list. The message is formatted and appended to error. Pass NULL to add just the raw error string as returned by strerror() to the error structure.

Definition at line 301 of file error.c.

References fid_error_throw().

Referenced by fid_file_dump_to_file().

int fid_error_dump ( const fid_Error error,
FILE *  stream 
)

Simple error reporting function.

This function prints all errors collected in error to stream and tries to visualize them according to overflow handling mode in case too many errors have occurred.

Parameters:
error The error structure containing error messages. It is safe to call this function without checking if errors are available beforehand. This may also be NULL to disable error reporting.
stream The output stream the errors should be written to. If NULL, then the errors are not printed.
Returns:
The return value of fid_ERROR_OCCURRED(error) is returned to make this function suitable for use in conditionals. If error is NULL, then the return value is 0.

Definition at line 372 of file error.c.

References fid_Error::errors, fid_ERROR_MAX, fid_ERROR_OCCURRED, fid_Error::first_error, fid_Error::mode, fid_Error::num_of_errors, fid_Error::outofmem, and fid_Error::overflow.


Generated on Wed Jul 8 17:21:16 2009 for Full-text Index Data structure library by  doxygen 1.5.9