Modified Existing Error API Specifications

Name: H5Epush

Signature:

herr_t H5Epush(hid_t error_stack, const char* file, const char* func, unsigned line, hid_t major_id, hid_t minor_id, const char* desc, … )

Purpose:

Pushes new error record onto error stack.

Description:

H5Epush pushes a new error record onto the error stack for the current thread.

The error record has major message major_id and minor message minor_id, the function name `func` where the error was detected, the file name file where the error was detected, the line `line` within that file, and an error description desc. The desc can be a format control string with additional argument. This design of appending additional argument is similar to the system function and C function printf and fprintf.

The function name, file name, error description strings and optional extra description string must be statically allocated.

The major and minor errors must be in the same error class.

Parameters:

hid_t error_stack,

IN: the ID of the error stack to be pushed. If this ID is H5E_DEFAULT,

the current error stack is being pushed an error record.

const char* file,

IN: Name of the file in which the error was detected.

const char* func,

IN: Name of the function in which the error was detected.

unsigned line,

IN: Line number in the file where the error was detected.

hid_t major_id,

IN: Major error ID.

hid_t minor_id,

IN: Minor error ID.

const char* desc,

IN: Error description string.

Returns:

Returns a non-negative value if succeeds; otherwise returns a negative value.

Name: H5Eprint

Signature:

herr_t `H5Eprint`(hid_t error_stack, FILE * `stream`)

Purpose:

Prints the error stack in a default manner.

Description:

`H5Eprint` prints the error stack specified by error_stack on the specified stream, `stream`. Even if the error stack is empty, a one-line message will be printed like this if the error is in HDF5 library:
`HDF5-DIAG: Error detected in HDF5 library version: 1.5.62`

`thread 0.`

``

`A similar line will appear before the error messages of each error class. It states the information of library name, version number and thread ID.`

`If error_stack is H5E_DEFAULT, the current error stack is printed.`

`H5Eprint` is a convenience function for `H5Ewalk()` with a function that prints error messages. Users are encouraged to write there own more specific error handlers.

Parameters:

hid_t error_stack,

IN: ID of the error stack to be printed.

FILE * `stream`

IN: File pointer, or stderr if NULL.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5Ewalk

Signature:

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

Purpose:

Walks the error stack for the current thread, calling a specified function.

Description:

`H5Ewalk` walks the error stack specified by error_stack for the current thread and calls the specified function for each error along the way.

If the error_stack is H5E_DEFAULT, the current error stack is walked through.

`direction` determines whether the stack is walked from the inside out or the outside in. A value of `H5E_WALK_UPWARD` means beginning with the most specific error and end at the API; a value of `H5E_WALK_DOWNWARD` means to start at the API and end at the inner-most function where the error was first detected.

`func` will be called for each error in the error stack. Its arguments will include an index number (beginning at zero regardless of stack traversal direction), an error stack entry, and the `client_data` pointer passed to `H5E_print`. The `H5E_walk_t` prototype is as follows:

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

where the parameters have the following meanings:

int `n`

Indexed position of the error in the stack.

H5E_error_t *`err_desc`

Pointer to a data structure describing the error. (This structure is currently described only in the source code file `hdf5/src/H5Epublic.h`. That file also contains the definitive list of major and minor error codes. That information will eventually be presented as an appendix to this Reference Manual.)

void *`client_data`

Pointer to client data in the format expected by the user-defined function.

`H5Ewalk` can fail if there are problems initializing the library.

Parameters:

hid_t error_stack

IN: ID of the error stack.

H5E_direction_t `direction`

IN: Direction in which the error stack is to be walked.

H5E_walk_t `func`

IN: Function to be called for each error encountered.

void * `client_data`

IN: Data to be passed with `func`.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5Eclear

Signature:

herr_t `H5Eclear`(`hid_t` `error_stack`)

Purpose:

Clears the error stack.

Description:

`H5Eclear` clears the error stack specified by error_stack. H5E_DEFAULT can be passed in to clear the current error stack.

The current stack is also cleared whenever an API function is called, with certain exceptions (for instance, `H5Eprint()`).

`H5Eclear` can fail if there are problems initializing the library.

Parameters:

hid_t error_stack,

IN: the ID of the error stack to be cleared.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5Eset_auto

Signature:

herr_t `H5Eset_auto`(hid_t error_stack, H5E_auto_t `func`,

void *`client_data` )

Purpose:

Turns automatic error printing on or off.

Description:

`H5Eset_auto` turns on or off automatic printing of errors for the error stack specified by error_stack. When turned on (non-null `func` pointer), any API function which returns an error indication will first call `func`, passing it `client_data` as an argument.

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`.

Automatic stack traversal is always in the `H5E_WALK_DOWNWARD` direction.

Parameters:

hid_t error_stack,

IN: the ID of the error stack, H5E_DEFAULT for the current stack.

H5E_auto_t `func`

IN: Function to be called upon an error condition.

void *`client_data`

IN: Data passed to the error function.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.

Name: H5Eget_auto

Signature:

herr_t `H5Eget_auto`(hid_t error_stack, H5E_auto_t * `func`,

void **`client_data` )

Purpose:

Returns the current settings for the automatic error stack traversal function and its data.

Description:

`H5Eget_auto` returns the current settings for the automatic error stack traversal function, `func`, and its data, `client_data`. Either (or both) arguments may be null in which case the value is not returned.

Parameters:

hid_t error_stack,

IN: the ID of the error stack, H5E_DEFAULT for the current stack.

H5E_auto_t * `func`

OUT: Current setting for the function to be called upon an error condition.

void **`client_data`

OUT: Current setting for the data passed to the error function.

Returns:

Returns a non-negative value if successful; otherwise returns a negative value.