Describes HDF5 Release 1.8.20, November 2017.
and the Board of Trustees of the University of Illinois
The C Interfaces:
| * Use of these functions is deprecated in Release 1.8.0. | ||||
| * Use of these functions is deprecated in Release 1.8.0. | ||||
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.
H5Eauto_is_v2(
hid_t estack_id,
unsigned *is_stack
)
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.
hid_t estack_id |
IN: The error stack identifier |
unsigned *is_stack |
OUT: A flag indicating which error stack typedef the specified error stack conforms to. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eclear1(
void
)
H5Eclear2(
hid_t estack_id
)
H5Eclear is a macro that is mapped to either
H5Eclear1 or
H5Eclear2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Eclear is mapped to the most recent version of
the function, currently
H5Eclear2.
If the library and/or application is compiled for Release 1.6
emulation, H5Eclear will be mapped to
H5Eclear1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Eclear mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Eclear2 |
| Enable deprecated symbols | H5Eclear2 |
| Disable deprecated symbols | H5Eclear2 |
Emulate Release 1.6 interface |
H5Eclear1 |
Function-level macros |
|
H5Eclear_vers = 2 |
H5Eclear2 |
H5Eclear_vers = 1 |
H5Eclear1 |
SUBROUTINE h5eclear_f(hdferr)
IMPLICIT NONE
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5eclear_f
| Release | C |
| 1.8.0 | The function
H5Eclear renamed to H5Eclear1
and deprecated in this release.
The macro H5Eclear
and the function H5Eclear2
introduced in this release. |
H5Eclear1(void)
H5Eclear2
or the macro
H5Eclear.
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).
| None |
H5Eclear.
| Release | C |
| 1.8.0 |
Function H5Eclear renamed to
H5Eclear1 and deprecated
in this release. |
H5Eclear2(hid_t estack_id)
H5Eclear2 clears the error stack specified
by estack_id, or,
if estack_id is set to H5E_DEFAULT,
the error stack for the current thread.
estack_id 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).
hid_t estack_id |
IN: Error stack identifier. |
H5Eclear.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eclose_msg(hid_t
mesg_id)
H5Eclose_msg closes an error message identifier.,
which can be either a major or minor message.
hid_t mesg_id |
IN: Error message identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eclose_stack(hid_t
estack_id)
H5Eclose_stack closes the object handle for an
error stack and releases its resources. H5E_DEFAULT
cannot be closed.
hid_t estack_id |
IN: Error stack identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ecreate_msg(hid_t
class, H5E_type_t msg_type,
const char* mesg)
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 which is indicated
by parameter msg_type.
Use H5Eclose_msg to close the message identifier
returned by this function.
hid_t class |
IN: Error class identifier. |
H5E_type_t msg_type |
IN: The type of the error message.
Valid values are H5E_MAJOR and
H5E_MINOR. |
const char* mesg |
IN: Major error message. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ecreate_stack(void)
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.
| None |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eget_auto(
H5E_auto_t * func,
void **client_data
)
H5Eget_auto(
hid_t estack_id,
H5E_auto_t * func,
void **client_data
)
H5Eget_auto is a macro that is mapped to either
H5Eget_auto1 or
H5Eget_auto2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Eget_auto is mapped to the most recent version of
the function, currently
H5Eget_auto2.
If the library and/or application is compiled for Release 1.6
emulation, H5Eget_auto will be mapped to
H5Eget_auto1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Eget_auto mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Eget_auto2 |
| Enable deprecated symbols | H5Eget_auto2 |
| Disable deprecated symbols | H5Eget_auto2 |
Emulate Release 1.6 interface |
H5Eget_auto1 |
Function-level macros |
|
H5Eget_auto_vers = 2 |
H5Eget_auto2 |
H5Eget_auto_vers = 1 |
H5Eget_auto1 |
| Release | C |
| 1.8.0 | The function
H5Eget_auto renamed to H5Eget_auto1
and deprecated in this release.
The macro H5Eget_auto
and the function H5Eget_auto2
introduced in this release. |
H5Eget_auto1(
H5E_auto1_t * func,
void **client_data
)
H5Eget_auto2
or the macro
H5Eget_auto.
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.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. 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.
H5E_auto1_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. |
| Release | C |
| 1.8.0 |
Function H5Eget_auto renamed to
H5Eget_auto1 and deprecated
in this release. |
H5Eget_auto2(
hid_t estack_id,
H5E_auto2_t * func,
void **client_data
)
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.func and client_data
arguments may be null, in which case the value is not returned.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. 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.
hid_t estack_id
|
IN: Error stack identifier.
H5E_DEFAULT indicates the current stack. |
H5E_auto2_t * func |
OUT: The function currently set to be called upon an error condition. |
void **client_data |
OUT: Data currently set to be passed to the error function. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eget_class_name(hid_t
class_id, char* name,
size_t size)
H5Eget_class_name retrieves the name of the error class
specified by the class identifier.
If 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.
If NULL is passed in as name, only the length of
class name is returned. If zero is returned, it means no name.
User is responsible for allocated enough buffer for the name.
hid_t class_id |
IN: Error class identifier. |
char* name |
OUT: The name of the class to be queried. |
size_t size |
IN: The length of class name to be returned by this function. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eget_current_stack(void)
H5Eget_current_stack copies the current error stack
and returns an error stack identifier for the new copy.
| None. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eget_major(H5E_major_t n)
H5Eget_major returns a
constant character string that describes the error.
H5E_major_t n |
IN: Major error number. |
SUBROUTINE h5eget_major_f(error_no, name, hdferr) INTEGER, INTENT(IN) :: error_no !Major error number CHARACTER(LEN=*), INTENT(OUT) :: name ! File name INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5eget_major_f
| Release | C |
| 1.8.0 | Function deprecated in this release. |
H5Eget_minor(H5E_minor_t n)
H5Eget_minor returns a
constant character string that describes the error.
H5Eget_minor returns
a string of dynamic allocated 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.
H5E_minor_t n |
IN: Minor error number. |
SUBROUTINE h5eget_minor_f(error_no, name, hdferr)
INTEGER, INTENT(IN) :: error_no !Major error number
CHARACTER(LEN=*), INTENT(OUT) :: name ! File name
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5eget_minor_f
| Release | Change |
| 1.8.0 | Function deprecated and return type changed in this release. |
H5Eget_msg(hid_t
mesg_id, H5E_type_t* mesg_type,
char* mesg, size_t size)
H5Eget_msg retrieves the error message including its
length and type. The error message is specified by mesg_id.
User is responsible for passing in enough buffer for the message.
If mesg 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 mesg, only the
length and type of the message is returned. If the return value is zero,
it means no message.
hid_t mesg_id |
IN: Idenfier for error message to be queried. |
H5E_type_t* mesg_type |
OUT: The type of the error message.
Valid values are H5E_MAJOR and
H5E_MINOR. |
char* mesg |
OUT: Error message buffer. |
size_t size |
IN: The length of error message to be returned by this function. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eget_num(hid_t estack_id)
H5Eget_num retrieves the number of error records
in the error stack specified by estack_id
(including major, minor messages and description).
hid_t estack_id
|
IN: Error stack identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Epop(hid_t
estack_id, size_t count)
H5Epop deletes the number of error records specified
in count from the top of the error stack
specified by estack_id
(including major, minor messages and description).
The number of error messages to be deleted is specified by
count.
hid_t estack_id
|
IN: Error stack identifier. |
size_t count |
IN: The number of error messages to be deleted from the top of error stack. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eprint1(
FILE * stream
)
H5Eprint2(
hid_t estack_id,
FILE * stream)
)
H5Eprint is a macro that is mapped to either
H5Eprint1 or
H5Eprint2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Eprint is mapped to the most recent version of
the function, currently
H5Eprint2.
If the library and/or application is compiled for Release 1.6
emulation, H5Eprint will be mapped to
H5Eprint1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Eprint mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Eprint2 |
| Enable deprecated symbols | H5Eprint2 |
| Disable deprecated symbols | H5Eprint2 |
Emulate Release 1.6 interface |
H5Eprint1 |
Function-level macros |
|
H5Eprint_vers = 2 |
H5Eprint2 |
H5Eprint_vers = 1 |
H5Eprint1 |
SUBROUTINE h5eprint_f(hdferr, name)
CHARACTER(LEN=*), OPTIONAL, INTENT(IN) :: name ! File name
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5eprint_f
| Release | C |
| 1.8.0 | The function
H5Eprint renamed to H5Eprint1
and deprecated in this release.
The macro H5Eprint
and the function H5Eprint2
introduced in this release. |
H5Eprint1(FILE * stream)
H5Eprint2
or the macro
H5Eprint.
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 will be printed:
HDF5-DIAG: Error detected in thread 0.
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.
FILE * stream |
IN: File pointer, or stderr if NULL. |
H5Eprint.
| Release | C |
| 1.8.0 |
Function H5Eprint renamed to
H5Eprint1 and deprecated
in this release. |
H5Eprint2(
hid_t estack_id,
FILE * stream)
H5Eprint2 prints the error stack specified by
estack_id on the specified stream, stream.
Even if the error stack is empty, a one-line message of the
following form will be printed:
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 stating the library name, library version number, and thread identifier.
If estack_id 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.
hid_t estack_id |
IN: Identifier of the error stack to be printed.
If the identifier is H5E_DEFAULT,
the current error stack will be printed. |
FILE * stream |
IN: File pointer, or stderr if NULL. |
H5Eprint.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Epush(
const char *file,
const char *func,
unsigned line,
H5E_major_t maj_num,
H5E_minor_t min_num,
const char *str
)
H5Epush(
hid_t estack_id,
const char *file,
const char *func,
unsigned line,
hid_t class_id,
hid_t major_id,
hid_t minor_id,
const char *msg,
...)
H5Epush is a macro that is mapped to either
H5Epush1 or
H5Epush2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Epush is mapped to the most recent version of
the function, currently
H5Epush2.
If the library and/or application is compiled for Release 1.6
emulation, H5Epush will be mapped to
H5Epush1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Epush mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Epush2 |
| Enable deprecated symbols | H5Epush2 |
| Disable deprecated symbols | H5Epush2 |
Emulate Release 1.6 interface |
H5Epush1 |
Function-level macros |
|
H5Epush_vers = 2 |
H5Epush2 |
H5Epush_vers = 1 |
H5Epush1 |
| Release | C |
| 1.8.0 | The function
H5Epush renamed to H5Epush1
and deprecated in this release.
The macro H5Epush
and the function H5Epush2
introduced in this release. |
H5Epush1(
const char *file,
const char *func,
unsigned line,
H5E_major_t maj_num,
H5E_minor_t min_num,
const char *str
)
H5Epush2
or the macro
H5Epush.
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.
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 within the file at which the error was detected. |
H5E_major_t maj_num |
IN: Major error number. |
H5E_minor_t min_num |
IN: Minor error number. |
const char *str |
IN: Error description string. |
| Release | C |
| 1.4.0 | Function introduced in this release. |
| 1.8.0 |
Function H5Epush renamed to
H5Epush1 and deprecated
in this release. |
H5Epush2(
hid_t estack_id,
const char *file,
const char *func,
unsigned line,
hid_t class_id,
hid_t major_id,
hid_t minor_id,
const char *msg,
...)
H5Epush2 pushes a new error record onto the
error stack specified by estack_id.
The error record contains
the error class identifier class_id,
the major and minor message identifiers major_id and
minor_id,
the function name func where the error was detected,
the filename file and line number line
within that 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 estack_id |
IN: Identifier of the error stack to which
the error record is to be pushed.
If the identifier is H5E_DEFAULT, the error record
will be pushed to the current stack. |
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 within the file at which the error was detected. |
hid_t class_id |
IN: Error class identifier. |
hid_t major_id |
IN: Major error identifier. |
hid_t minor_id |
IN: Minor error identifier. |
const char *msg |
IN: Error description string. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eregister_class(const char*
cls_name, const char* lib_name,
const char* version)
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 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 preamble.
const char* cls_name |
IN: Name of the error class. |
const char* lib_name |
IN: Name of the client library or application to which the error class belongs. |
const char* version |
IN: Version of the client library or application to which the error class belongs. A NULL can be passed in. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eset_auto(
H5E_auto_t func,
void *client_data
)
H5Eset_auto(
hid_t estack_id,
H5E_auto_t func,
void *client_data
)
H5Eset_auto is a macro that is mapped to either
H5Eset_auto1 or
H5Eset_auto2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. Their use and mappings are fully described in “API Compatibility Macros in HDF5”; we urge you to read that document closely.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Eset_auto is mapped to the most recent version of
the function, currently
H5Eset_auto2.
If the library and/or application is compiled for Release 1.6
emulation, H5Eset_auto will be mapped to
H5Eset_auto1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Eset_auto mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Eset_auto2 |
| Enable deprecated symbols | H5Eset_auto2 |
| Disable deprecated symbols | H5Eset_auto2 |
Emulate Release 1.6 interface |
H5Eset_auto1 |
Function-level macros |
|
H5Eset_auto_vers = 2 |
H5Eset_auto2 |
H5Eset_auto_vers = 1 |
H5Eset_auto1 |
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
SUBROUTINE h5eset_auto_f(printflag, hdferr)
INTEGER, INTENT(IN) :: printflag !flag to turn automatic error
!printing on or off
!possible values are:
!printon (1)
!printoff(0)
INTEGER, INTENT(OUT) :: hdferr ! Error code
END SUBROUTINE h5eset_auto_f
SUBROUTINE h5eset_auto_f(printflag, hdferr, estack_id, func, client_data)
INTEGER , INTENT(IN) :: printflag
INTEGER , INTENT(OUT) :: hdferr
INTEGER(HID_T), INTENT(IN) , OPTIONAL :: estack_id
TYPE(C_FUNPTR), INTENT(IN) , OPTIONAL :: func
TYPE(C_PTR) , INTENT(IN) , OPTIONAL :: client_data
Inputs:
printflag - Flag to turn automatic error printing on or off;
possible values are:
printon (1)
printoff(0)
estack_id - Error stack identifier.
func - Function to be called upon an error condition.
client_data - Data passed to the error function
Outputs:
hdferr - Returns 0 if successful and -1 if fails
| Release | Change |
| 1.8.0 | The function
H5Eset_auto renamed to H5Eset_auto1
and deprecated in this release.
The macro H5Eset_auto
and the function H5Eset_auto2
introduced in this release. |
| 1.8.8 | Fortran 2003 version of Fortran subroutine added in this release. |
H5Eset_auto1(
H5E_auto1_t func,
void *client_data
)
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.
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.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
H5E_auto1_t func |
IN: Function to be called upon an error condition. |
void *client_data |
IN: Data passed to the error function. |
H5Eset_auto.
| Release | C |
| 1.8.0 |
Function H5Eset_auto renamed to
H5Eset_auto1 and deprecated
in this release. |
H5Eset_auto2(
hid_t estack_id,
H5E_auto2_t func,
void *client_data
)
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.
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.
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t estack_id |
IN: Error stack identifier. |
H5E_auto2_t func |
IN: Function to be called upon an error condition. |
void *client_data |
IN: Data passed to the error function. |
H5Eset_auto.
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eset_current_stack(hid_t
estack_id)
H5Eset_current_stack replaces the content of
the current error stack with a copy of the content of the
error stack specified by estack_id, and it closes
the error stack specified by estack_id.
hid_t estack_id |
IN: Error stack identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Eunregister_class(hid_t
class_id)
H5Eunregister_class removes the error class specified
by class_id.
All the major and minor errors in this class will also be closed.
hid_t class_id |
IN: Error class identifier. |
| Release | C |
| 1.8.0 | Function introduced in this release. |
H5Ewalk(
H5E_direction_t direction,
H5E_walk_t func,
void * client_data
)
H5Ewalk(
hid_t estack_id,
H5E_direction_t direction,
H5E_walk_t func,
void * client_data
)
H5Ewalk is a macro that is mapped to either
H5Ewalk1 or
H5Ewalk2,
depending on the needs of the application.
Such macros are provided to facilitate application compatibility. For more information on macro use and mappings, see the “API Compatibility Macros in HDF5” document.
When both the HDF5 Library and the application are built and
installed with no specific compatibility flags,
H5Ewalk is mapped to the most recent version of
the function, currently
H5Ewalk2.
If the library and/or application is compiled for Release 1.6
emulation, H5Ewalk will be mapped to
H5Ewalk1.
Function-specific flags are available to override these settings
on a function-by-function basis when the application is compiled.
Specific compile-time compatibility flags and the resulting mappings are as follows:
| Compatibility setting | H5Ewalk mapping |
|---|---|
Global settings |
|
| No compatibility flag | H5Ewalk2 |
| Enable deprecated symbols | H5Ewalk2 |
| Disable deprecated symbols | H5Ewalk2 |
Emulate Release 1.6 interface |
H5Ewalk1 |
Function-level macros |
|
H5Ewalk_vers = 2 |
H5Ewalk2 |
H5Ewalk_vers = 1 |
H5Ewalk1 |
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
| Release | C |
| 1.8.0 | The function
H5Ewalk renamed to H5Ewalk1
and deprecated in this release.
The macro H5Ewalk
and the function H5Ewalk2
introduced in this release. |
H5Ewalk1(
H5E_direction_t direction,
H5E_walk1_t func,
void * client_data
)
H5Ewalk2
or the macro
H5Ewalk.
H5Ewalk1 walks the error stack for the current thread
and calls the specified function for each error along the way.
direction determines whether the stack is walked
from the inside out or the outside in.
A value of H5E_WALK_UPWARD means 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 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_walk1_t prototype is as follows:
typedef herr_t (*H5E_walk1_t)(int n,
H5E_error1_t *err_desc,
void *client_data)
where the parameters have the following meanings:
n
err_desc
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.)
client_data
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
H5E_direction_t direction |
IN: Direction in which the error stack is to be walked. |
H5E_walk1_t func |
IN: Function to be called for each error encountered. |
void * client_data |
IN: Data to be passed with func. |
| Release | C |
| 1.8.0 |
Function H5Ewalk renamed to
H5Ewalk1 and deprecated
in this release. |
H5Ewalk2(
hid_t estack_id,
H5E_direction_t direction,
H5E_walk2_t func,
void * client_data
)
H5Ewalk2 walks the error stack specified by
estack_id for the current thread and calls the function
specified in func for each error along the way.
If the value of estack_id 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 compliant with 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
H5E_print.
The H5E_walk2_t prototype is as follows:
typedef herr_t (*H5E_walk2_t)(unsigned n,
const H5E_error2_t *err_desc,
void *client_data)
where the parameters have the following meanings:
n
err_desc
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
HDF5 Reference Manual.)
client_data
If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally.
Examples of this kind of routine include callbacks such as
H5Pset_elink_cb and H5Pset_type_conv_cb
and functions such as H5Tconvert and
H5Ewalk2.
Exiting the routine in its normal fashion allows the HDF5 C Library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ “catch” statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed.
hid_t estack_id |
IN: Error stack identifier. |
H5E_direction_t direction |
IN: Direction in which the error stack is to be walked. |
H5E_walk2_t func |
IN: Function to be called for each error encountered. |
void * client_data |
IN: Data to be passed with func.
|
| Release | C |
| 1.8.0 | Function introduced in this release. |
|
The HDF Group Help Desk:
Describes HDF5 Release 1.8.20, November 2017. |
Copyright by
The HDF Group
and the Board of Trustees of the University of Illinois |