The Error Handling Interface (H5E)

1. Introduction

When an error occurs deep within the HDF5 library a record is pushed onto an error stack and that function returns a failure indication. Its caller detects the failure, pushes another record onto the stack, and returns a failure indication. This continues until the application-called API function returns a failure indication (a negative integer or null pointer). The next API function which is called (with a few exceptions) resets the stack.

2. Error Handling Operations

In normal circumstances, an error causes the stack to be printed on the standard error stream. The first item, number "#000" is produced by the API function itself and is usually sufficient to indicate to the application programmer what went wrong.

HDF5-DIAG: Error detected in thread 0.  Back trace follows.
  #000: H5T.c line 462 in H5Tclose(): predefined datatype
    major(01): Function argument
    minor(05): Bad value
	      

The error stack can also be printed and manipulated by these functions, but if an application wishes make explicit calls to H5Eprint() then the automatic printing should be turned off to prevent error messages from being displayed twice (see H5Eset_auto() below).

herr_t H5Eprint (FILE *stream)

The error stack is printed on the specified stream. Even if the error stack is empty a one-line message will be printed: HDF5-DIAG: Error detected in thread 0.

herr_t H5Eclear (void)

The error stack can be explicitly cleared by calling this function. The stack is also cleared whenever an API function is called, with certain exceptions (for instance, H5Eprint()).

Sometimes an application will call a function for the sake of its return value, fully expecting the function to fail. Under these conditions, it would be misleading if an error message were automatically printed. Automatic printing of messages is controlled by the H5Eset_auto() function:

herr_t H5Eset_auto (herr_t(*func)(void*), void *client_data)

If func is not a null pointer, then the function to which it points will be called automatically when an API function is about to return an indication of failure. The function is called with a single argument, the client_data pointer. When the library is first initialized the auto printing function is set to H5Eprint() (cast appropriately) and client_data is the standard error stream pointer, stderr.

herr_t H5Eget_auto (herr_t(**func)(void*), void **client_data)

This function returns the current automatic error traversal settings through the func and client_data arguments. Either (or both) arguments may be null pointers in which case the corresponding information is not returned.

/* Save old error handler */
herr_t (*old_func)(void*);
void *old_client_data;
H5Eget_auto(&old_func, &old_client_data);

/* Turn off error handling */
H5Eset_auto(NULL, NULL);

/* Probe. Likely to fail, but that's okay */
status = H5Fopen (......);

/* Restore previous error handler */
H5Eset_auto(old_func, old_client_data);
	      

/* Turn off error handling permanently */
H5Eset_auto (NULL, NULL);

/* If failure, print error message */
if (H5Fopen (....)<0) {
    H5Eprint (stderr);
    exit (1);
}
	      

The application is allowed to define an automatic error traversal function other than the default H5Eprint(). For instance, one could define a function that prints a simple, one-line error message to the standard error stream and then exits.

herr_t
my_hdf5_error_handler (void *unused)
{
   fprintf (stderr, "An HDF5 error was detected. Bye.\n");
   exit (1);
}
	      

H5Eset_auto (my_hdf5_error_handler, NULL);
	      

The H5Eprint() function is actually just a wrapper around the more complex H5Ewalk() function which traverses an error stack and calls a user-defined function for each member of the stack.

herr_t H5Ewalk (H5E_direction_t direction, H5E_walk_t func, void *client_data)

The error stack is traversed and func is called for each member of the stack. Its arguments are an integer sequence number beginning at zero (regardless of direction), a pointer to an error description record, and the client_data pointer. If direction is H5E_WALK_UPWARD then traversal begins at the inner-most function that detected the error and concludes with the API function. The opposite order is H5E_WALK_DOWNWARD.

typedef herr_t (*H5E_walk_t)(int n, H5E_error_t *eptr, void *client_data)

An error stack traversal callback function takes three arguments: n is a sequence number beginning at zero for each traversal, eptr is a pointer to an error stack member, and client_data is the same pointer passed to H5Ewalk().

typedef struct {
    H5E_major_t maj_num;
    H5E_minor_t min_num;
    const char  *func_name;
    const char  *file_name;
    unsigned    line;
    const char  *desc;
} H5E_error_t;

The maj_num and min_num are major and minor error numbers, func_name is the name of the function where the error was detected, file_name and line locate the error within the HDF5 library source code, and desc points to a description of the error.

const char *H5Eget_major (H5E_major_t num)

const char *H5Eget_minor (H5E_minor_t num)

These functions take a major or minor error number and return a constant string which describes the error. If num is out of range than a string like "Invalid major error number" is returned.

herr_t
H5Ewalk_cb(int n, H5E_error_t *err_desc, void *client_data)
{
    FILE		*stream = (FILE *)client_data;
    const char		*maj_str = NULL;
    const char		*min_str = NULL;
    const int		indent = 2;

    /* Check arguments */
    assert (err_desc);
    if (!client_data) client_data = stderr;

    /* Get descriptions for the major and minor error numbers */
    maj_str = H5Eget_major (err_desc->maj_num);
    min_str = H5Eget_minor (err_desc->min_num);

    /* Print error message */
    fprintf (stream, "%*s#%03d: %s line %u in %s(): %s\n",
	     indent, "", n, err_desc->file_name, err_desc->line,
	     err_desc->func_name, err_desc->desc);
    fprintf (stream, "%*smajor(%02d): %s\n",
	     indent*2, "", err_desc->maj_num, maj_str);
    fprintf (stream, "%*sminor(%02d): %s\n",
	     indent*2, "", err_desc->min_num, min_str);

    return 0;
}