|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |
The C Interfaces:
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 H5Eprint,
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_stack(hid_t
estack_id, unsigned *is_stack)
H5Eauto_is_stack determines whether the error auto
reporting function for an error stack conforms to the
H5E_auto_stack_t typedef or the
H5E_auto_t typedef.
The is_stack parameter is set to 11
if the error stack conforms to H5E_auto_stack_t
and 0 for if H5E_auto_t.
hid_t estack_id |
The error stack identifier |
unsigned* is_stack |
A flag indicating which error stack typedef the specified error stack conforms to. |
H5Eclear(void)
H5Eclear clears the error stack for the current thread.
The 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.
Note:
As of HDF5 Release 1.8, H5Eclear_stack
replaces H5Eclear and H5Eclear is designated
a deprecated function. H5Eclear may be removed
from the library at a future release.
| None |
SUBROUTINE h5eclear_f(hdferr) IMPLICIT NONE INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5eclear_f
H5Eclear_stack(hid_t estack_id)
H5Eclear_stack clears the error stack specified
by estack_id for the current thread.
If the value of estack_id is H5E_DEFAULT,
the current current error stack will be cleared.
The current error stack is also cleared whenever an API function
is called, with certain exceptions
(for instance, H5Eprint).
H5Eclear_stack can fail if there are problems initializing
the library.
hid_t mesg_id |
IN: Error message identifier. |
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. |
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. |
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.
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. |
H5Eget_auto(H5E_auto_t * func,
void **client_data
)
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.
Note:
As of HDF5 Release 1.8, H5Eget_auto_stack
replaces H5Eget_auto and H5Eget_auto is designated
a deprecated function. H5Eget_auto may be removed
from the library at a future release.
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. |
H5Eget_auto_stack(
hid_t estack_id,
H5E_auto_stack_t * func,
void **client_data
)
H5Eget_auto_stack returns the current 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.
hid_t estack_id
|
IN: Error stack identifier.
H5E_DEFAULT indicates the current stack. |
H5E_auto_stack_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. |
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. |
H5Eget_current_stack(void)
H5Eget_current_stack registers the current error stack,
returns an object identifier, and clears the current error stack.
An empty error stack will also be assigned an identifier.
| None. |
H5Eget_major(H5E_major_t n)
H5Eget_major returns a
constant character string that describes the error.
Note:
As of HDF5 Release 1.8, H5Eget_msg
replaces H5Eget_major and H5Eget_major is designated
a deprecated function. H5Eget_major may be removed
from the library at a future release.
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
H5Eget_minor(H5E_minor_t n)
H5Eget_minor returns a
constant character string that describes the error.
Note:
As of HDF5 Release 1.8, H5Eget_msg
replaces H5Eget_minor and H5Eget_minor is designated
a deprecated function. H5Eget_minor may be removed
from the library at a future release.
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
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. |
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. |
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. |
H5Eprint(FILE * stream)
H5Eprint prints the error stack 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.
H5Eprint is a convenience function for
H5Ewalk with a function that prints error messages.
Users are encouraged to write their own more specific error handlers.
Note:
As of HDF5 Release 1.8, H5Eprint_stack
replaces H5Eprint and H5Eprint is designated
a deprecated function. H5Eprint may be removed
from the library at a future release.
FILE * stream |
IN: File pointer, or stderr if NULL. |
SUBROUTINE h5eprint_f(hdferr, name) CHARACTER(LEN=*), OPTIONAL, INTENT(IN) :: name ! File name INTEGER, INTENT(OUT) :: hdferr ! Error code END SUBROUTINE h5eprint_f
H5Eprint(
hid_t estack_id,
FILE * stream)
H5Eprint_stack 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.
H5Eprint_stack is a convenience function for
H5Ewalk_stack 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. |
H5Epush(
const char *file,
const char *func,
unsigned line,
H5E_major_t maj_num,
H5E_minor_t min_num,
const char *str
)
H5Epush 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.
Note:
As of HDF5 Release 1.8, H5Epush_stack
replaces H5Epush and H5Epush is designated
a deprecated function. H5Epush may be removed
from the library at a future release.
H5Epush:
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. |
H5Epush_stack(
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_stack pushes a new error record onto the
error stack for the current thread.
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. |
H5Eregister_class(const char*
cls_name, const char* lib_name,
const char* version)
H5Eregister_class registers a client library or
application program to HDF5 error API so that the client library
or application program can report error 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. |
H5Eset_auto(H5E_auto_t func,
void *client_data
)
H5Eset_auto 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 H5Eprint (cast appropriately) and
client_data is the standard error stream pointer,
stderr.
Automatic stack traversal is always in the
H5E_WALK_DOWNWARD direction.
Note:
As of HDF5 Release 1.8, H5Eset_auto_stack
replaces H5Eset_auto and H5Eset_auto is designated
a deprecated function. H5Eset_auto may be removed
from the library at a future release.
H5E_auto_t func |
IN: Function to be called upon an error condition. |
void *client_data |
IN: Data passed to the error function. |
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
H5Eset_auto_stack(
hid_t estack_id,
H5E_auto_stack_t func,
void *client_data
)
H5Eset_auto_stack 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 H5Eprint_stack (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_auto_stack call with a NULL
func pointer.
hid_t estack_id |
IN: Error stack identifier. |
H5E_auto_stack_t func |
IN: Function to be called upon an error condition. |
void *client_data |
IN: Data passed to the error function. |
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 error stack
specified by estack_id.
hid_t estack_id |
IN: Error stack identifier. |
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. |
H5Ewalk(H5E_direction_t direction,
H5E_walk_t func,
void * client_data
)
H5Ewalk 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_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:
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
H5Ewalk can fail if there are problems initializing
the library.
Note:
As of HDF5 Release 1.8, H5Ewalk_stack
replaces H5Ewalk and H5Ewalk is designated
a deprecated function. H5Ewalk may be removed
from the library at a future release.
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. |
H5Ewalk_stack(
hid_t estack_id,
H5E_direction_t direction,
H5E_walk_t func,
void * client_data
)
H5Ewalk_stack 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 H5Ewalk_stack 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_walk_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_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:
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
H5Ewalk_stack can fail if there are problems initializing
the library.
hid_t estack_id |
IN: Error stack identifier. |
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.
|
H5Ewalk_cb(int n,
H5E_error_t *err_desc,
void *client_data
)
H5Ewalk_cb is a default error stack traversal callback
function that prints error messages to the specified output stream.
It is not meant to be called directly but rather as an
argument to the H5Ewalk function.
This function is called also by H5Eprint.
Application writers are encouraged to use this function as a
model for their own error stack walking functions.
n is a counter for how many times this function
has been called for this particular traversal of the stack.
It always begins at zero for the first error on the stack
(either the top or bottom error, or even both, depending on
the traversal direction and the size of the stack).
err_desc is an error description. It contains all the
information about a particular error.
client_data is the same pointer that was passed as the
client_data argument of H5Ewalk.
It is expected to be a file pointer (or stderr if NULL).
int n |
IN/OUT: Number of times this function has been called for this traversal of the stack. |
H5E_error_t *err_desc |
OUT: Error description. |
void *client_data |
IN: A file pointer, or stderr if NULL. |
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |