Functions for handling errors that occur within HDF5 (H5E)
- H5E_AUTO_IS_V2 — Determines type of error stack
- H5E_CLEAR — Clears an error stack
- H5E_CLOSE_MSG — Closes an error message identifier
- H5E_CLOSE_STACK — Closes object handle for error stack
- H5E_CREATE_MSG — Adds major error message to an error class
- H5E_CREATE_STACK — Creates a new empty error stack
- H5E_GET_AUTO — Returns settings for automatic error stack traversal function and its data
- H5E_GET_CLASS_NAME — Retrieves error class name
- H5E_GET_CURRENT_STACK — Returns copy of current error stack
- H5E_GET_MAJOR — Returns a character string describing an error specified by a major error number
- H5E_GET_MINOR — Returns a character string describing an error specified by a minor error number
- H5E_GET_MSG — Retrieves an error message
- H5E_GET_NUM — Retrieves the number of error messages in an error stack
- H5E_POP — Deletes specified number of error messages from the error stack
- H5E_PRINT — Prints an error stack in a default manner
- H5E_PUSH — Pushes a new error message onto an error stack
- H5E_REGISTER_CLASS — Registers a client library or application program to the HDF5 error API
- H5E_SET_AUTO — Turns automatic error printing on or off
- H5E_SET_CURRENT_STACK — Replaces the current error stack
- H5E_UNREGISTER_CLASS — Removes an error class
- H5E_WALK — Walks an error stack, calling a specified function
The Error interface provides error handling in the form of a stack. The
FUNC_ENTER() macro clears the error stack whenever an interface function is entered. When an error is detected, an entry is pushed onto the stack. As the functions unwind, additional entries are pushed onto the stack. The API function will return some indication that an error occurred and the application can print the error stack.
Certain API functions in the H5E package, such as
H5Eprint1, do not clear the error stack. Otherwise, any function which does not have an underscore immediately after the package name will clear the error stack. For instance,
H5Fopen clears the error stack while
H5F_open does not.
An error stack has a fixed maximum size. If this size is exceeded then the stack will be truncated and only the inner-most functions will have entries on the stack. This is expected to be a rare condition.
Each thread has its own error stack, but since multi-threading has not been added to the library yet, this package maintains a single error stack. The error stack is statically allocated to reduce the complexity of handling errors within the H5E package.