HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
In the HDF5 Reference Manual 
H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
Tools   Datatypes   Fortran   Compatibility Macros 
Collective Calls in Parallel 

H5E: Error Interface

Error API Functions

These functions provide error handling capabilities in the HDF5 environment.
In the following lists, italic type indicates a configurable macro.

The C Interfaces:
             
Use of these functions is deprecated in Release 1.8.0.

Alphabetical Listing
             
Use of these functions is deprecated in Release 1.8.0.

The Fortran Interface:
In general, each Fortran subroutine performs exactly the same task as the corresponding C 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.


Last modified: 17 August 2010
Name: H5Eauto_is_v2
Signature:
herr_t H5Eauto_is_v2( hid_t estack_id, unsigned *is_stack )

Purpose:
Determines type of error stack.

Description:
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.

Parameters:
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.

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

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 May 2009
Name: H5Eclear
Signature:
herr_t H5Eclear1( void )

herr_t H5Eclear2( hid_t estack_id )
Purpose:
Clears an error stack.
Description:
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

Fortran90 Interface: h5eclear_f
SUBROUTINE h5eclear_f(hdferr) 
  IMPLICIT NONE 
  INTEGER, INTENT(OUT) :: hdferr  ! Error code 

END SUBROUTINE h5eclear_f
        

History:
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.

Last modified: 24 May 2009
Name: H5Eclear1
Signature:
herr_t H5Eclear1(void)
Purpose:
Clears the error stack for the current thread.
Notice:
This function is deprecated in favor of the function H5Eclear2 or the macro H5Eclear.
Description:
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).

Parameters:
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5eclear_f
See H5Eclear.

History:
Release     C
1.8.0 Function H5Eclear renamed to H5Eclear1 and deprecated in this release.

Name: H5Eclear2
Last modified: 24 May 2009
Signature:
herr_t H5Eclear2(hid_t estack_id)
Purpose:
Clears the specified error stack or the error stack for the current thread.
Description:
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).

Parameters:
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface:
See H5Eclear.

History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eclose_msg
Signature:
herr_t H5Eclose_msg(hid_t mesg_id)
Purpose:
Closes an error message identifier.
Description:
H5Eclose_msg closes an error message identifier., which can be either a major or minor message.
Parameters:
Returns:
Returns a non-negative value on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eclose_stack
Signature:
herr_t H5Eclose_stack(hid_t estack_id)
Purpose:
Closes object handle for error stack.
Description:
H5Eclose_stack closes the object handle for an error stack and releases its resources. H5E_DEFAULT cannot be closed.
Parameters:
Returns:
Returns a non-negative value on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 9 October 2014
Name: H5Ecreate_msg

Signature:
hid_t H5Ecreate_msg(hid_t class, H5E_type_t msg_type, const char* mesg)

Purpose:
Add major error message to an error class.

Description:
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.

Parameters:

Returns:
Returns a message identifier on success; otherwise returns a negative value.

Fortran90 Interface:
None

See Also:
“Using Identifiers”

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 9 October 2014
Name: H5Ecreate_stack

Signature:
hid_t H5Ecreate_stack(void)

Purpose:
Creates a new empty error stack.

Description:
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.

Parameters:

Returns:
Returns an error stack identifier on success; otherwise returns a negative value.

Fortran90 Interface:
None

See Also:
“Using Identifiers”

History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 May 2009
Name: H5Eget_auto
Signature:
herr_t H5Eget_auto( H5E_auto_t * func, void **client_data )

herr_t H5Eget_auto( hid_t estack_id, H5E_auto_t * func, void **client_data )
Purpose:
Returns settings for automatic error stack traversal function and its data.
Description:
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

Fortran90 Interface: h5eget_auto_f
None.

History:
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.

Name: H5Eget_auto1
 
Signature:
herr_t H5Eget_auto1( H5E_auto1_t * func, void **client_data )
 
Purpose:
Returns the current settings for the automatic error stack traversal function and its data.
 
Notice:
This function is deprecated in favor of the function H5Eget_auto2 or the macro H5Eget_auto.
 
Description:
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.
 
Parameters:
 
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
 
Fortran90 Interface:
None.
 
History:
Release     C
1.8.0 Function H5Eget_auto renamed to H5Eget_auto1 and deprecated in this release.

Name: H5Eget_auto2
 
Signature:
herr_t H5Eget_auto2( hid_t estack_id, H5E_auto2_t * func, void **client_data )
 
Purpose:
Returns the settings for the automatic error stack traversal function and its data.
 
Description:
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.
 
Parameters:
 
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
 
Fortran90 Interface:
None.
 
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eget_class_name
Signature:
ssize_t H5Eget_class_name(hid_t class_id, char* name, size_t size)
Purpose:
Retrieves error class name.
Description:
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.
Parameters:
Returns:
Returns non-negative value as on success; otherwise returns negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eget_current_stack
Signature:
hid_t H5Eget_current_stack(void)
Purpose:
Returns copy of current error stack.
Description:
H5Eget_current_stack copies the current error stack and returns an error stack identifier for the new copy.
Parameters:
Returns:
Returns an error stack identifier on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eget_major
Signature:
const char * H5Eget_major(H5E_major_t n)
Purpose:
Returns a character string describing an error specified by a major error number.
Notice:
This function has been deprecated.
Description:
Given a major error number, H5Eget_major returns a constant character string that describes the error.

Parameters:
Returns:
Returns a character string describing the error if successful. Otherwise returns "Invalid major error number."
Fortran90 Interface: h5eget_major_f
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
	
History:
Release     C
1.8.0 Function deprecated in this release.

Last modified: 25 November 2009
Name: H5Eget_minor
Signature:
char * H5Eget_minor(H5E_minor_t n)

Purpose:
Returns a character string describing an error specified by a minor error number.

Notice:
This function has been deprecated.

Description:
Given a minor error number, H5Eget_minor returns a constant character string that describes the error.

Note:
In the Release 1.8.x series, 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.

Parameters:
H5E_minor_t n     IN: Minor error number.

Returns:
Returns a character string describing the error if successful. Otherwise returns "Invalid minor error number."

Fortran90 Interface: h5eget_minor_f
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
    

History:
Release     Change
1.8.0 Function deprecated and return type changed in this release.

Name: H5Eget_msg
Signature:
ssize_t H5Eget_msg(hid_t mesg_id, H5E_type_t* mesg_type, char* mesg, size_t size)
Purpose:
Retrieves an error message.
Description:
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.
Parameters:
Returns:
Returns the size of the error message in bytes on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eget_num
Signature:
ssize_t H5Eget_num(hid_t estack_id)
Purpose:
Retrieves the number of error messages in an error stack.
Description:
H5Eget_num retrieves the number of error records in the error stack specified by estack_id (including major, minor messages and description).
Parameters:
Returns:
Returns a non-negative value on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Epop
Signature:
herr_t H5Epop(hid_t estack_id, size_t count)
Purpose:
Deletes specified number of error messages from the error stack.
Description:
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.
Parameters:
Returns:
Returns a non-negative value on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 May 2009
Name: H5Eprint
Signature:
herr_t H5Eprint1( FILE * stream )

herr_t H5Eprint2( hid_t estack_id, FILE * stream) )
Purpose:
Prints an error stack in a default manner.
Description:
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

Fortran90 Interface: h5eprint_f
SUBROUTINE h5eprint_f(hdferr, name)
  CHARACTER(LEN=*), OPTIONAL, INTENT(IN) :: name ! File name 
  INTEGER, INTENT(OUT) :: hdferr                 ! Error code 

END SUBROUTINE h5eprint_f
        

History:
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.

Last modified: 24 May 2009
Name: H5Eprint1
Signature:
herr_t H5Eprint1(FILE * stream)
Purpose:
Prints the current error stack in a default manner.
Notice:
This function is deprecated in favor of the function H5Eprint2 or the macro H5Eprint.
Description:
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.

Parameters:
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface: h5eprint_f
See H5Eprint.
History:
Release     C
1.8.0 Function H5Eprint renamed to H5Eprint1 and deprecated in this release.

Last modified: 24 May 2009
Name: H5Eprint2
Signature:
herr_t H5Eprint2( hid_t estack_id, FILE * stream)
Purpose:
Prints the specified error stack in a default manner.
Description:
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.

Parameters:
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface:
See H5Eprint.
History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 May 2009
Name: H5Epush
Signature:
herr_t H5Epush( const char *file, const char *func, unsigned line, H5E_major_t maj_num, H5E_minor_t min_num, const char *str )

herr_t 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, ...)
Purpose:
Pushes a new error message onto an error stack.
Description:
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

Fortran90 Interface:
None.

History:
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.

Name: H5Epush1
Signature:
herr_t H5Epush1( const char *file, const char *func, unsigned line, H5E_major_t maj_num, H5E_minor_t min_num, const char *str )
Purpose:
Pushes new error record onto error stack.
Notice:
This function is deprecated in favor of the function H5Epush2 or the macro H5Epush.
Description:
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.

Parameters:
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface:
None.
History:

Name: H5Epush2
Signature:
herr_t 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, ...)
Purpose:
Pushes new error record onto error stack.
Description:
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.

Parameters:
Returns:
Returns a non-negative value if successful; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eregister_class
Signature:
hid_t H5Eregister_class(const char* cls_name, const char* lib_name, const char* version)
Purpose:
Registers a client library or application program to the HDF5 error API.
Description:
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.
Parameters:
Returns:
Returns a class identifier on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 August 2012
Name: H5Eset_auto

Signature:
herr_t H5Eset_auto( H5E_auto_t func, void *client_data )

herr_t H5Eset_auto( hid_t estack_id, H5E_auto_t func, void *client_data )

Purpose:
Turns automatic error printing on or off.

Description:
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

Programming Note for C++ Developers Using C Functions:

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.

Fortran90 Interface: h5eset_auto_f
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
        

Fortran2003 Interface: h5eset_auto_f
Signature:e:

  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

History:
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.

Last modified: 24 August 2012
Name: H5Eset_auto1

Signature:
herr_t H5Eset_auto1( H5E_auto1_t func, void *client_data )

Purpose:
Turns automatic error printing on or off.

Description:
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.

Programming Note for C++ Developers Using C Functions:

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.

Parameters:

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

Fortran90 Interface: h5eset_auto_f
See H5Eset_auto.

History:
Release     C
1.8.0 Function H5Eset_auto renamed to H5Eset_auto1 and deprecated in this release.

Last modified: 24 August 2012
Name: H5Eset_auto2

Signature:
herr_t H5Eset_auto2( hid_t estack_id, H5E_auto2_t func, void *client_data )

Purpose:
Turns automatic error printing on or off.

Description:
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.

Programming Note for C++ Developers Using C Functions:

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.

Parameters:

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

Fortran90 Interface: h5eset_auto_f
See H5Eset_auto.

History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eset_current_stack
Signature:
herr_t H5Eset_current_stack(hid_t estack_id)
Purpose:
Replaces the current error stack.
Description:
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.
Parameters:
Returns:
Returns a non-negative value on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Name: H5Eunregister_class
Signature:
herr_t H5Eunregister_class(hid_t class_id)
Purpose:
Removes an error class.
Description:
H5Eunregister_class removes the error class specified by class_id. All the major and minor errors in this class will also be closed.
Parameters:
Returns:
Returns a non-negative value on success; otherwise returns a negative value.
Fortran90 Interface:
None.
History:
Release     C
1.8.0 Function introduced in this release.

Last modified: 24 August 2012
Name: H5Ewalk

Signature:
herr_t H5Ewalk( H5E_direction_t direction, H5E_walk_t func, void * client_data )

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

Purpose:
Walks an error stack, calling a specified function.

Description:
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

Programming Note for C++ Developers Using C Functions:

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.

Fortran90 Interface:
None.

History:
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.

Last modified: 24 August 2012
Name: H5Ewalk1

Signature:
herr_t H5Ewalk1( H5E_direction_t direction, H5E_walk1_t func, void * client_data )

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

Notice:
This function is deprecated in favor of the function H5Ewalk2 or the macro H5Ewalk.

Description:
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:

int n
Indexed position of the error in the stack.
H5E_error1_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.

Programming Note for C++ Developers Using C Functions:

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.

Parameters:
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.

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

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function H5Ewalk renamed to H5Ewalk1 and deprecated in this release.

Last modified: 24 August 2012
Name: H5Ewalk2

Signature:
herr_t H5Ewalk2( hid_t estack_id, H5E_direction_t direction, H5E_walk2_t func, void * client_data )

Purpose:
Walks the specified error stack, calling the specified function.

Description:
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:

unsigned n
Indexed position of the error in the stack.
const H5E_error2_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 HDF5 Reference Manual.)
void *client_data
Pointer to client data in the format expected by the user-defined function.

Programming Note for C++ Developers Using C Functions:

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.

Parameters:

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

Fortran90 Interface:
None.

History:
Release     C
1.8.0 Function introduced in this release.

HDF5 documents and links 
Introduction to HDF5 
HDF5 User’s Guide 
In the HDF5 Reference Manual 
H5DS   H5IM   H5LT   H5PT   H5TB  Optimized 
H5   H5A   H5D   H5E   H5F   H5G   H5I   H5L 
H5O   H5P   H5PL   H5R   H5S   H5T   H5Z 
Tools   Datatypes   Fortran   Compatibility Macros 
Collective Calls in Parallel 

The HDF Group Help Desk:
Describes HDF5 Release 1.10.
  Copyright by The HDF Group
and the Board of Trustees of the University of Illinois