HDF5 1.14.5
API Reference
|
Macros | |
#define | H5Eget_auto H5Eget_auto2 |
#define | H5Eprint H5Eprint2 |
#define | H5Epush H5Epush2 |
#define | H5Eset_auto H5Eset_auto2 |
#define | H5Ewalk H5Ewalk2 |
Functions | |
hid_t | H5Eregister_class (const char *cls_name, const char *lib_name, const char *version) |
Registers a client library or application program to the HDF5 error API. | |
herr_t | H5Eunregister_class (hid_t class_id) |
Removes an error class. | |
herr_t | H5Eclose_msg (hid_t err_id) |
Closes an error message. | |
hid_t | H5Ecreate_msg (hid_t cls, H5E_type_t msg_type, const char *msg) |
Adds a major or minor error message to an error class. | |
hid_t | H5Ecreate_stack (void) |
Creates a new, empty error stack. | |
hid_t | H5Eget_current_stack (void) |
Returns a copy of the current error stack. | |
herr_t | H5Eappend_stack (hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack) |
Appends one error stack to another, optionally closing the source stack. | |
herr_t | H5Eis_paused (hid_t stack_id, hbool_t *is_paused) |
| |
herr_t | H5Epause_stack (hid_t stack_id) |
| |
herr_t | H5Eresume_stack (hid_t stack_id) |
| |
herr_t | H5Eclose_stack (hid_t stack_id) |
Closes an error stack handle. | |
ssize_t | H5Eget_class_name (hid_t class_id, char *name, size_t size) |
Retrieves error class name. | |
herr_t | H5Eset_current_stack (hid_t err_stack_id) |
Replaces the current error stack. | |
herr_t | H5Epush2 (hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, hid_t maj_id, hid_t min_id, const char *msg,...) |
Pushes a new error record onto an error stack. | |
herr_t | H5Epop (hid_t err_stack, size_t count) |
Deletes specified number of error messages from the error stack. | |
herr_t | H5Eprint2 (hid_t err_stack, FILE *stream) |
Prints the specified error stack in a default manner. | |
herr_t | H5Ewalk2 (hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data) |
Walks the specified error stack, calling the specified function. | |
herr_t | H5Eget_auto2 (hid_t estack_id, H5E_auto2_t *func, void **client_data) |
Returns the settings for the automatic error stack traversal function and its data. | |
herr_t | H5Eset_auto2 (hid_t estack_id, H5E_auto2_t func, void *client_data) |
Turns automatic error printing on or off. | |
herr_t | H5Eclear2 (hid_t err_stack) |
Clears the specified error stack or the error stack for the current thread. | |
herr_t | H5Eauto_is_v2 (hid_t err_stack, unsigned *is_stack) |
Determines the type of error stack. | |
ssize_t | H5Eget_msg (hid_t msg_id, H5E_type_t *type, char *msg, size_t size) |
Retrieves an error message. | |
ssize_t | H5Eget_num (hid_t error_stack_id) |
Retrieves the number of error messages in an error stack. | |
herr_t | H5Eclear1 (void) |
Clears the error stack for the current thread. | |
herr_t | H5Eget_auto1 (H5E_auto1_t *func, void **client_data) |
Returns the current settings for the automatic error stack traversal function and its data. | |
herr_t | H5Epush1 (const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str) |
Pushes a new error record onto the error stack. | |
herr_t | H5Eprint1 (FILE *stream) |
Prints the current error stack in a default manner. | |
herr_t | H5Eset_auto1 (H5E_auto1_t func, void *client_data) |
Turns automatic error printing on or off. | |
herr_t | H5Ewalk1 (H5E_direction_t direction, H5E_walk1_t func, void *client_data) |
Walks the current error stack, calling the specified function. | |
char * | H5Eget_major (H5E_major_t maj) |
Returns a character string describing an error specified by a major error number. | |
char * | H5Eget_minor (H5E_minor_t min) |
Returns a character string describing an error specified by a minor error number. | |
#define H5Eget_auto H5Eget_auto2 |
H5Eget_auto() is a macro that is mapped to either H5Eget_auto1() or H5Eget_auto2().
#define H5Eprint H5Eprint2 |
H5Eprint() is a macro that is mapped to either H5Eprint1() or H5Eprint2().
#define H5Epush H5Epush2 |
H5Epush() is a macro that is mapped to either H5Epush1() or H5Epush2().
#define H5Eset_auto H5Eset_auto2 |
H5Eset_auto() is a macro that is mapped to either H5Eset_auto1() or H5Eset_auto2().
#define H5Ewalk H5Ewalk2 |
H5Ewalk() is a macro that is mapped to either H5Ewalk1() or H5Ewalk2().
Appends one error stack to another, optionally closing the source stack.
[in] | dst_stack_id | Error stack identifier |
[in] | src_stack_id | Error stack identifier |
[in] | close_source_stack | Flag to indicate whether to close the source stack |
H5Eappend_stack() appends the messages from error stack src_stack_id
to the error stack dst_stack_id
. If close_source_stack
is true
, the source error stack will be closed.
Determines the type of error stack.
[in] | err_stack | Error stack identifier |
[out] | is_stack | A flag indicating which error stack typedef the specified error stack conforms to |
H5Eauto_is_v2() determines whether the error auto reporting function for an error stack conforms to the H5E_auto2_t typedef
or the H5E_auto1_t typedef
.
The is_stack
parameter is set to 1 if the error stack conforms to H5E_auto2_t and 0 if it conforms to H5E_auto1_t.
herr_t H5Eclear1 | ( | void | ) |
Clears the error stack for the current thread.
H5Eclear1() clears the error stack for the current thread.
The stack is also cleared whenever an API function is called, with certain exceptions (for instance, H5Eprint1()).
Clears the specified error stack or the error stack for the current thread.
[in] | err_stack | Error stack identifier |
H5Eclear2() clears the error stack specified by err_stack
, or, if err_stack
is set to H5E_DEFAULT, the error stack for the current thread.
err_stack
is an error stack identifier, such as that returned by H5Eget_current_stack().
The current error stack is also cleared whenever an API function is called, with certain exceptions (for instance, H5Eprint1() or H5Eprint2()).
Closes an error message.
[in] | err_id | An error message identifier |
H5Eclose_msg() closes an error message identifier, which can be either a major or minor message.
Closes an error stack handle.
[in] | stack_id | Error stack identifier |
H5Eclose_stack() closes the error stack handle stack_id
and releases its resources. H5E_DEFAULT cannot be closed.
hid_t H5Ecreate_msg | ( | hid_t | cls, |
H5E_type_t | msg_type, | ||
const char * | msg | ||
) |
Adds a major or minor error message to an error class.
[in] | cls | An error class identifier |
[in] | msg_type | The type of the error message |
[in] | msg | Error message |
H5Ecreate_msg() adds an error message to an error class defined by client library or application program. The error message can be either major or minor as indicated by the parameter msg_type
.
Use H5Eclose_msg() to close the message identifier returned by this function.
hid_t H5Ecreate_stack | ( | void | ) |
Creates a new, empty error stack.
H5Ecreate_stack() creates a new empty error stack and returns the new stack's identifier. Use H5Eclose_stack() to close the error stack identifier returned by this function.
herr_t H5Eget_auto1 | ( | H5E_auto1_t * | func, |
void ** | client_data | ||
) |
Returns the current settings for the automatic error stack traversal function and its data.
[out] | func | Current setting for the function to be called upon an error condition |
[out] | client_data | Current setting for the data passed to the error function |
H5Eget_auto1() 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.
The library initializes its default error stack traversal functions to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns H5Eprint2() or the user-defined function passed in through H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the user-defined function passed in through H5Eset_auto1(). However, if the application passes in a user-defined function through H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal function. If the application passes in a user-defined function through H5Eset_auto2(), it should call H5Eget_auto2() to query the traversal function.
Mixing the new style and the old style functions will cause a failure. For example, if the application sets a user-defined old-style traversal function through H5Eset_auto1(), a call to H5Eget_auto2() will fail and will indicate that the application has mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if the traversal functions are the library's default H5Eprint1() or H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing H5Eset_auto2() and H5Eget_auto1() does not fail.
herr_t H5Eget_auto2 | ( | hid_t | estack_id, |
H5E_auto2_t * | func, | ||
void ** | client_data | ||
) |
Returns the settings for the automatic error stack traversal function and its data.
[in] | estack_id | Error stack identifier |
[out] | func | The function currently set to be called upon an error condition |
[out] | client_data | Data currently set to be passed to the error function |
H5Eget_auto2() returns the settings for the automatic error stack traversal function, func
, and its data, client_data
, that are associated with the error stack specified by estack_id
.
Either or both of the func
and client_data
arguments may be NULL
, in which case the value is not returned.
The library initializes its default error stack traversal functions to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns H5Eprint2() or the user-defined function passed in through H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the user-defined function passed in through H5Eset_auto1(). However, if the application passes in a user-defined function through H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal function. If the application passes in a user-defined function through H5Eset_auto2(), it should call H5Eget_auto2() to query the traversal function.
Mixing the new style and the old style functions will cause a failure. For example, if the application sets a user-defined old-style traversal function through H5Eset_auto1(), a call to H5Eget_auto2() will fail and will indicate that the application has mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if the traversal functions are the library's default H5Eprint1() or H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing H5Eset_auto2() and H5Eget_auto1() does not fail.
Retrieves error class name.
[in] | class_id | Error class identifier |
[out] | name | Buffer for the error class name |
[in] | size | The maximum number of characters of the class name to be returned by this function in name . |
H5Eget_class_name() retrieves the name of the error class specified by the class identifier. If a non-NULL pointer is passed in for name
and size
is greater than zero, the class name of size
long is returned. The length of the error class name is also returned.
Up to size
characters of the error class name are returned in name
; additional characters, if any, are not returned to the user application.
If the length of the error class name, which determines the required value of size
, is unknown, a preliminary call to H5Eget_class_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the error class name. That value, plus 1 for a NULL terminator, must then be assigned to size
for a second H5Eget_class_name() call, which will retrieve the actual error class name.
If zero is returned, it means the error class has no name.
hid_t H5Eget_current_stack | ( | void | ) |
Returns a copy of the current error stack.
H5Eget_current_stack() copies the current error stack and returns an error stack identifier for the new copy.
char * H5Eget_major | ( | H5E_major_t | maj | ) |
Returns a character string describing an error specified by a major error number.
[in] | maj | Major error number |
H5Eget_major() returns a constant character string that describes the error, given a major error number.
char
array). An application calling this function must free the memory associated with the return value to prevent a memory leak.char * H5Eget_minor | ( | H5E_minor_t | min | ) |
Returns a character string describing an error specified by a minor error number.
[in] | min | Minor error number |
H5Eget_minor() returns a constant character string that describes the error, given a minor error number.
char
array. An application calling this function from an HDF5 library of Release 1.8.0 or later must free the memory associated with the return value to prevent a memory leak. This is a change from the 1.6.x release series.ssize_t H5Eget_msg | ( | hid_t | msg_id, |
H5E_type_t * | type, | ||
char * | msg, | ||
size_t | size | ||
) |
Retrieves an error message.
[in] | msg_id | Error message identifier |
[out] | type | The type of the error message. Valid values are H5E_MAJOR and H5E_MINOR. |
[out] | msg | Error message buffer |
[in] | size | The length of error message to be returned by this function |
H5Eget_msg() retrieves the error message including its length and type. The error message is specified by msg_id
. The user is responsible for passing in sufficient buffer space for the message. If msg
is not NULL and size
is greater than zero, the error message of size
long is returned. The length of the message is also returned. If NULL is passed in as msg
, only the length and type of the message is returned. If the return value is zero, it means there is no message.
Retrieves the number of error messages in an error stack.
[in] | error_stack_id | Error stack identifier |
H5Eget_num() retrieves the number of error records in the error stack specified by error_stack_id
(including major, minor messages and description).
[in] | stack_id | Error stack identifier |
[out] | is_paused | Flag whether stack is paused |
H5Eis_paused() can be used within HDF5 VOL connectors and other dynamically loaded components to check if the HDF5 library, or other component has paused pushing error on the default error stack or an application stack.
The library may pause pushing errors on the default error stack when performing "speculative" operations, such as testing for the existence of something that could be located at one of many locations. stack_id
is the error stack to query, and the value pointed to by is_paused
is set to TRUE/FALSE.
If an error occurs while attempting to query the status of stack_id
, the value pointed to by is_paused
is unchanged.
[in] | stack_id | Error stack identifier |
H5Epause_stack() pauses pushing errors on an error stack. Pushing an error on a paused error stack will be ignored (not fail).
H5Eresume_stack() is used to allow errors to be pushed on a stack. Calls to H5Epause_stack() and H5Eresume_stack() must be matched.
Calls to H5Epause_stack()/H5Eresume_stack() may be nested.
Deletes specified number of error messages from the error stack.
[in] | err_stack | Error stack identifier |
[in] | count | The number of error messages to be deleted from the top of error stack |
H5Epop() deletes the number of error records specified in count
from the top of the error stack specified by err_stack
(including major, minor messages and description). The number of error messages to be deleted is specified by count
.
herr_t H5Eprint1 | ( | FILE * | stream | ) |
Prints the current error stack in a default manner.
[in] | stream | File pointer, or NULL for stderr |
H5Eprint1() prints the error stack for the current thread on the specified stream, stream
. Even if the error stack is empty, a one-line message of the following form will be printed:
H5Eprint1() is a convenience function for H5Ewalk1() with a function that prints error messages. Users are encouraged to write their own more specific error handlers.
Prints the specified error stack in a default manner.
[in] | err_stack | Error stack identifier |
[in] | stream | File pointer, or NULL for stderr |
H5Eprint2() prints the error stack specified by err_stack
on the specified stream, stream
. Even if the error stack is empty, a one-line message of the following form will be printed:
A similar line will appear before the error messages of each error class stating the library name, library version number, and thread identifier.
If err_stack
is H5E_DEFAULT, the current error stack will be printed.
H5Eprint2() is a convenience function for H5Ewalk2() with a function that prints error messages. Users are encouraged to write their own more specific error handlers.
herr_t H5Epush1 | ( | const char * | file, |
const char * | func, | ||
unsigned | line, | ||
H5E_major_t | maj, | ||
H5E_minor_t | min, | ||
const char * | str | ||
) |
Pushes a new error record onto the error stack.
[in] | file | Name of the file in which the error was detected |
[in] | func | Name of the function in which the error was detected |
[in] | line | Line number in the file where the error was detected |
[in] | maj | Major error identifier |
[in] | min | Minor error identifier |
[in] | str | Error description string |
H5Epush1() pushes a new error record onto the error stack for the current thread.
The error has major and minor numbers maj_num
and min_num
, the function func
where the error was detected, the name of the file file
where the error was detected, the line line
within that file, and an error description string str
.
The function name, filename, and error description strings must be statically allocated.
herr_t H5Epush2 | ( | hid_t | err_stack, |
const char * | file, | ||
const char * | func, | ||
unsigned | line, | ||
hid_t | cls_id, | ||
hid_t | maj_id, | ||
hid_t | min_id, | ||
const char * | msg, | ||
... | |||
) |
Pushes a new error record onto an error stack.
[in] | err_stack | Error stack identifier. If the identifier is H5E_DEFAULT, the error record will be pushed to the current stack. |
[in] | file | Name of the file in which the error was detected |
[in] | func | Name of the function in which the error was detected |
[in] | line | Line number in the file where the error was detected |
[in] | cls_id | Error class identifier |
[in] | maj_id | Major error identifier |
[in] | min_id | Minor error identifier |
[in] | msg | Error description string |
H5Epush2() pushes a new error record onto the error stack specified by err_stack
.
The error record contains the error class identifier cls_id
, the major and minor message identifiers maj_id
and min_id
, the function name func
where the error was detected, the file name file
and line number line
in the file where the error was detected, and an error description msg
.
The major and minor errors must be in the same error class.
The function name, filename, and error description strings must be statically allocated.
msg
can be a format control string with additional arguments. This design of appending additional arguments is similar to the system and C functions printf() and fprintf().
hid_t H5Eregister_class | ( | const char * | cls_name, |
const char * | lib_name, | ||
const char * | version | ||
) |
Registers a client library or application program to the HDF5 error API.
[in] | cls_name | Name of the error class |
[in] | lib_name | Name of the client library or application to which the error class belongs |
[in] | version | Version of the client library or application to which the error class belongs. It can be NULL . |
H5Eregister_class() registers a client library or application program to the HDF5 error API so that the client library or application program can report errors together with the HDF5 library. It receives an identifier for this error class for further error operations. The library name and version number will be printed out in the error message as a preamble.
[in] | stack_id | Error stack identifier |
H5Eresume_stack() resumes pushing errors on an error stack.
Calls to H5Epause_stack() and H5Eresume_stack() must be matched. Calls to H5Epause_stack()/H5Eresume_stack() may be nested.
herr_t H5Eset_auto1 | ( | H5E_auto1_t | func, |
void * | client_data | ||
) |
Turns automatic error printing on or off.
[in] | func | Function to be called upon an error condition |
[in] | client_data | Data passed to the error function |
H5Eset_auto1() turns on or off automatic printing of errors. 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.
func
, a function conforming to the H5E_auto1_t prototype, is defined in the H5Epublic.h source code file as:
When the library is first initialized, the auto printing function is set to H5Eprint1() (cast appropriately) and client_data
is the standard error stream pointer, stderr
.
Automatic stack traversal is always in the H5E_WALK_DOWNWARD direction.
herr_t H5Eset_auto2 | ( | hid_t | estack_id, |
H5E_auto2_t | func, | ||
void * | client_data | ||
) |
Turns automatic error printing on or off.
[in] | estack_id | Error stack identifier |
[in] | func | Function to be called upon an error condition |
[in] | client_data | Data passed to the error function |
H5Eset_auto2() turns on or off automatic printing of errors for the error stack specified with estack_id
. An estack_id
value of H5E_DEFAULT indicates the current stack.
When automatic printing is turned on, by the use of a non-null func
pointer, any API function which returns an error indication will first call func
, passing it client_data
as an argument.
func
, a function compliant with the H5E_auto2_t prototype, is defined in the H5Epublic.h source code file as:
When the library is first initialized, the auto printing function is set to H5Eprint2() (cast appropriately) and client_data
is the standard error stream pointer, stderr
.
Automatic stack traversal is always in the H5E_WALK_DOWNWARD direction.
Automatic error printing is turned off with a H5Eset_auto2() call with a NULL
func
pointer.
Replaces the current error stack.
[in] | err_stack_id | Error stack identifier |
H5Eset_current_stack() replaces the content of the current error stack with a copy of the content of the error stack specified by err_stack_id
, and it closes the error stack specified by err_stack_id
.
Removes an error class.
[in] | class_id | Error class identifier. |
H5Eunregister_class() removes the error class specified by class_id
. All the major and minor errors in this class will also be closed.
herr_t H5Ewalk1 | ( | H5E_direction_t | direction, |
H5E_walk1_t | func, | ||
void * | client_data | ||
) |
Walks the current error stack, calling the specified function.
[in] | direction | Direction in which the error stack is to be walked |
[in] | func | Function to be called for each error encountered |
[in] | client_data | Data to be passed to func |
H5Ewalk1() walks the error stack for the current thread and calls the function specified in func
for each error along the way.
direction
specifies whether the stack is walked from the inside out or the outside in. A value of H5E_WALK_UPWARD means to begin 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 innermost function where the error was first detected.
func
, a function conforming to the H5E_walk1_t prototype, will be called for each error in the error stack. Its arguments will include an index number n
(beginning at zero regardless of stack traversal direction), an error stack entry err_desc
, and the client_data
pointer passed to H5Eprint(). The H5E_walk1_t prototype is as follows:
herr_t H5Ewalk2 | ( | hid_t | err_stack, |
H5E_direction_t | direction, | ||
H5E_walk2_t | func, | ||
void * | client_data | ||
) |
Walks the specified error stack, calling the specified function.
[in] | err_stack | Error stack identifier |
[in] | direction | Direction in which the error stack is to be walked |
[in] | func | Function to be called for each error encountered |
[in] | client_data | Data to be passed to func |
H5Ewalk2() walks the error stack specified by err_stack for the current thread and calls the function specified in func
for each error along the way.
If the value of err_stack
is H5E_DEFAULT, then H5Ewalk2() walks the current error stack.
direction
specifies whether the stack is walked from the inside out or the outside in. A value of H5E_WALK_UPWARD means to begin 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 innermost function where the error was first detected.
func
, a function conforming to the H5E_walk2_t prototype, will be called for each error in the error stack. Its arguments will include an index number n
(beginning at zero regardless of stack traversal direction), an error stack entry err_desc
, and the client_data
pointer passed to H5Eprint(). The H5E_walk2_t prototype is as follows: