Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 1.14.5
API Reference
Loading...
Searching...
No Matches
Error Handling (H5E)

Detailed Description

Macros

#define H5Eget_auto   H5Eget_auto2
 
#define H5Eprint   H5Eprint2
 
#define H5Epush   H5Epush2
 
#define H5Eset_auto   H5Eset_auto2
 
#define H5Ewalk   H5Ewalk2
 

Functions

hid_t H5Eregister_class (const char *cls_name, const char *lib_name, const char *version)
 Registers a client library or application program to the HDF5 error API.
 
herr_t H5Eunregister_class (hid_t class_id)
 Removes an error class.
 
herr_t H5Eclose_msg (hid_t err_id)
 Closes an error message.
 
hid_t H5Ecreate_msg (hid_t cls, H5E_type_t msg_type, const char *msg)
 Adds a major or minor error message to an error class.
 
hid_t H5Ecreate_stack (void)
 Creates a new, empty error stack.
 
hid_t H5Eget_current_stack (void)
 Returns a copy of the current error stack.
 
herr_t H5Eappend_stack (hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack)
 Appends one error stack to another, optionally closing the source stack.
 
herr_t H5Eis_paused (hid_t stack_id, hbool_t *is_paused)
 
  • Check if pushing errors on an error stack is paused

 
herr_t H5Epause_stack (hid_t stack_id)
 
  • Pause pushing errors on an error stack

 
herr_t H5Eresume_stack (hid_t stack_id)
 
  • Resume pushing errors on an error stack

 
herr_t H5Eclose_stack (hid_t stack_id)
 Closes an error stack handle.
 
ssize_t H5Eget_class_name (hid_t class_id, char *name, size_t size)
 Retrieves error class name.
 
herr_t H5Eset_current_stack (hid_t err_stack_id)
 Replaces the current error stack.
 
herr_t H5Epush2 (hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, hid_t maj_id, hid_t min_id, const char *msg,...)
 Pushes a new error record onto an error stack.
 
herr_t H5Epop (hid_t err_stack, size_t count)
 Deletes specified number of error messages from the error stack.
 
herr_t H5Eprint2 (hid_t err_stack, FILE *stream)
 Prints the specified error stack in a default manner.
 
herr_t H5Ewalk2 (hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data)
 Walks the specified error stack, calling the specified function.
 
herr_t H5Eget_auto2 (hid_t estack_id, H5E_auto2_t *func, void **client_data)
 Returns the settings for the automatic error stack traversal function and its data.
 
herr_t H5Eset_auto2 (hid_t estack_id, H5E_auto2_t func, void *client_data)
 Turns automatic error printing on or off.
 
herr_t H5Eclear2 (hid_t err_stack)
 Clears the specified error stack or the error stack for the current thread.
 
herr_t H5Eauto_is_v2 (hid_t err_stack, unsigned *is_stack)
 Determines the type of error stack.
 
ssize_t H5Eget_msg (hid_t msg_id, H5E_type_t *type, char *msg, size_t size)
 Retrieves an error message.
 
ssize_t H5Eget_num (hid_t error_stack_id)
 Retrieves the number of error messages in an error stack.
 
herr_t H5Eclear1 (void)
 Clears the error stack for the current thread.
 
herr_t H5Eget_auto1 (H5E_auto1_t *func, void **client_data)
 Returns the current settings for the automatic error stack traversal function and its data.
 
herr_t H5Epush1 (const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str)
 Pushes a new error record onto the error stack.
 
herr_t H5Eprint1 (FILE *stream)
 Prints the current error stack in a default manner.
 
herr_t H5Eset_auto1 (H5E_auto1_t func, void *client_data)
 Turns automatic error printing on or off.
 
herr_t H5Ewalk1 (H5E_direction_t direction, H5E_walk1_t func, void *client_data)
 Walks the current error stack, calling the specified function.
 
char * H5Eget_major (H5E_major_t maj)
 Returns a character string describing an error specified by a major error number.
 
char * H5Eget_minor (H5E_minor_t min)
 Returns a character string describing an error specified by a minor error number.
 

Macro Definition Documentation

◆ H5Eget_auto

#define H5Eget_auto   H5Eget_auto2

H5Eget_auto() is a macro that is mapped to either H5Eget_auto1() or H5Eget_auto2().

See also
API Compatibility Macros

◆ H5Eprint

#define H5Eprint   H5Eprint2

H5Eprint() is a macro that is mapped to either H5Eprint1() or H5Eprint2().

See also
API Compatibility Macros

◆ H5Epush

#define H5Epush   H5Epush2

H5Epush() is a macro that is mapped to either H5Epush1() or H5Epush2().

See also
API Compatibility Macros

◆ H5Eset_auto

#define H5Eset_auto   H5Eset_auto2

H5Eset_auto() is a macro that is mapped to either H5Eset_auto1() or H5Eset_auto2().

See also
API Compatibility Macros

◆ H5Ewalk

#define H5Ewalk   H5Ewalk2

H5Ewalk() is a macro that is mapped to either H5Ewalk1() or H5Ewalk2().

See also
API Compatibility Macros

Function Documentation

◆ H5Eappend_stack()

herr_t H5Eappend_stack ( hid_t  dst_stack_id,
hid_t  src_stack_id,
hbool_t  close_source_stack 
)

Appends one error stack to another, optionally closing the source stack.


Parameters
[in]dst_stack_idError stack identifier
[in]src_stack_idError stack identifier
[in]close_source_stackFlag to indicate whether to close the source stack
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eappend_stack() appends the messages from error stack src_stack_id to the error stack dst_stack_id. If close_source_stack is true, the source error stack will be closed.

Since
1.14.0

◆ H5Eauto_is_v2()

herr_t H5Eauto_is_v2 ( hid_t  err_stack,
unsigned *  is_stack 
)

Determines the type of error stack.


Parameters
[in]err_stackError stack identifier
[out]is_stackA 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.

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.

Since
1.8.0

◆ H5Eclear1()

herr_t H5Eclear1 ( void  )

Clears the error stack for the current thread.


Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated in this release.

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()).

Since
1.0.0

◆ H5Eclear2()

herr_t H5Eclear2 ( hid_t  err_stack)

Clears the specified error stack or the error stack for the current thread.


Parameters
[in]err_stackError stack identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eclear2() clears the error stack specified by err_stack, or, if err_stack is set to H5E_DEFAULT, the error stack for the current thread.

err_stack is an error stack identifier, such as that returned by H5Eget_current_stack().

The current error stack is also cleared whenever an API function is called, with certain exceptions (for instance, H5Eprint1() or H5Eprint2()).

Since
1.8.0

◆ H5Eclose_msg()

herr_t H5Eclose_msg ( hid_t  err_id)

Closes an error message.


Parameters
[in]err_idAn error message identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eclose_msg() closes an error message identifier, which can be either a major or minor message.

Since
1.8.0

◆ H5Eclose_stack()

herr_t H5Eclose_stack ( hid_t  stack_id)

Closes an error stack handle.


Parameters
[in]stack_idError stack identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eclose_stack() closes the error stack handle stack_id and releases its resources. H5E_DEFAULT cannot be closed.

Since
1.8.0

◆ H5Ecreate_msg()

hid_t H5Ecreate_msg ( hid_t  cls,
H5E_type_t  msg_type,
const char *  msg 
)

Adds a major or minor error message to an error class.


Parameters
[in]clsAn error class identifier
[in]msg_typeThe type of the error message
[in]msgError message
Returns
An error ID (success), H5I_INVALID_HID (failure)

H5Ecreate_msg() adds an error message to an error class defined by client library or application program. The error message can be either major or minor as indicated by the parameter msg_type.

Use H5Eclose_msg() to close the message identifier returned by this function.

Since
1.8.0

◆ H5Ecreate_stack()

hid_t H5Ecreate_stack ( void  )

Creates a new, empty error stack.


Returns
Returns an error stack identifier if successful; otherwise returns H5I_INVALID_HID.

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.

Since
1.8.0

◆ H5Eget_auto1()

herr_t H5Eget_auto1 ( H5E_auto1_t func,
void **  client_data 
)

Returns the current settings for the automatic error stack traversal function and its data.


Parameters
[out]funcCurrent setting for the function to be called upon an error condition
[out]client_dataCurrent setting for the data passed to the error function
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and deprecated in this release.

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.

Since
1.0.0

◆ H5Eget_auto2()

herr_t H5Eget_auto2 ( hid_t  estack_id,
H5E_auto2_t func,
void **  client_data 
)

Returns the settings for the automatic error stack traversal function and its data.


Parameters
[in]estack_idError stack identifier
[out]funcThe function currently set to be called upon an error condition
[out]client_dataData currently set to be passed to the error function
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

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.

Since
1.8.0

◆ H5Eget_class_name()

ssize_t H5Eget_class_name ( hid_t  class_id,
char *  name,
size_t  size 
)

Retrieves error class name.


Parameters
[in]class_idError class identifier
[out]nameBuffer for the error class name
[in]sizeThe maximum number of characters of the class name to be returned by this function in name.
Returns
Returns non-negative value as on success; otherwise returns negative value.

H5Eget_class_name() retrieves the name of the error class specified by the class identifier. If a non-NULL pointer is passed in for name and size is greater than zero, the class name of size long is returned. The length of the error class name is also returned.

Up to size characters of the error class name are returned in name; additional characters, if any, are not returned to the user application.

If the length of the error class name, which determines the required value of size, is unknown, a preliminary call to H5Eget_class_name() with the last two parameters set to NULL and zero respectively can be made. The return value of this call will be the size in bytes of the error class name. That value, plus 1 for a NULL terminator, must then be assigned to size for a second H5Eget_class_name() call, which will retrieve the actual error class name.

If zero is returned, it means the error class has no name.

Since
1.8.0

◆ H5Eget_current_stack()

hid_t H5Eget_current_stack ( void  )

Returns a copy of the current error stack.


Returns
Returns an error stack identifier if successful; otherwise returns H5I_INVALID_HID.

H5Eget_current_stack() copies the current error stack and returns an error stack identifier for the new copy.

Since
1.8.0

◆ H5Eget_major()

char * H5Eget_major ( H5E_major_t  maj)

Returns a character string describing an error specified by a major error number.


Parameters
[in]majMajor error number
Returns
Pointer to the message (success), or NULL (failure)
Deprecated:
1.8.0 Function deprecated in this release.

H5Eget_major() returns a constant character string that describes the error, given a major error number.

Attention
This function returns a dynamically allocated string (char array). An application calling this function must free the memory associated with the return value to prevent a memory leak.
Since
1.0.0

◆ H5Eget_minor()

char * H5Eget_minor ( H5E_minor_t  min)

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


Parameters
[in]minMinor error number
Returns
Pointer to the message (success), or NULL (failure)
Deprecated:
1.8.0 Function deprecated and return type changed in this release.

H5Eget_minor() returns a constant character string that describes the error, given a minor error number.

Attention
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.
Since
1.0.0

◆ H5Eget_msg()

ssize_t H5Eget_msg ( hid_t  msg_id,
H5E_type_t type,
char *  msg,
size_t  size 
)

Retrieves an error message.


Parameters
[in]msg_idError message identifier
[out]typeThe type of the error message. Valid values are H5E_MAJOR and H5E_MINOR.
[out]msgError message buffer
[in]sizeThe length of error message to be returned by this function
Returns
Returns the size of the error message in bytes on success; otherwise returns a negative value.

H5Eget_msg() retrieves the error message including its length and type. The error message is specified by msg_id. The user is responsible for passing in sufficient buffer space for the message. If msg is not NULL and size is greater than zero, the error message of size long is returned. The length of the message is also returned. If NULL is passed in as msg, only the length and type of the message is returned. If the return value is zero, it means there is no message.

Since
1.8.0

◆ H5Eget_num()

ssize_t H5Eget_num ( hid_t  error_stack_id)

Retrieves the number of error messages in an error stack.


Parameters
[in]error_stack_idError stack identifier
Returns
Returns number of error messages in an error stack on success; otherwise returns a negative value.

H5Eget_num() retrieves the number of error records in the error stack specified by error_stack_id (including major, minor messages and description).

Since
1.8.0

◆ H5Eis_paused()

herr_t H5Eis_paused ( hid_t  stack_id,
hbool_t is_paused 
)

  • Check if pushing errors on an error stack is paused


Parameters
[in]stack_idError stack identifier
[out]is_pausedFlag whether stack is paused
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eis_paused() can be used within HDF5 VOL connectors and other dynamically loaded components to check if the HDF5 library, or other component has paused pushing error on the default error stack or an application stack.

The library may pause pushing errors on the default error stack when performing "speculative" operations, such as testing for the existence of something that could be located at one of many locations. stack_id is the error stack to query, and the value pointed to by is_paused is set to TRUE/FALSE.

If an error occurs while attempting to query the status of stack_id, the value pointed to by is_paused is unchanged.

Since
1.14.5

◆ H5Epause_stack()

herr_t H5Epause_stack ( hid_t  stack_id)

  • Pause pushing errors on an error stack


Parameters
[in]stack_idError stack identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Epause_stack() pauses pushing errors on an error stack. Pushing an error on a paused error stack will be ignored (not fail).

H5Eresume_stack() is used to allow errors to be pushed on a stack. Calls to H5Epause_stack() and H5Eresume_stack() must be matched.

Calls to H5Epause_stack()/H5Eresume_stack() may be nested.

Since
1.14.5

◆ H5Epop()

herr_t H5Epop ( hid_t  err_stack,
size_t  count 
)

Deletes specified number of error messages from the error stack.


Parameters
[in]err_stackError stack identifier
[in]countThe number of error messages to be deleted from the top of error stack
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Epop() deletes the number of error records specified in count from the top of the error stack specified by err_stack (including major, minor messages and description). The number of error messages to be deleted is specified by count.

Since
1.8.0

◆ H5Eprint1()

herr_t H5Eprint1 ( FILE *  stream)

Prints the current error stack in a default manner.


Parameters
[in]streamFile pointer, or NULL for stderr
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
1.8.0 Function H5Eprint() renamed to H5Eprint1() and deprecated in this release.

H5Eprint1() prints the error stack for the current thread on the specified stream, stream. Even if the error stack is empty, a one-line message of the following form will be printed:

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.

Since
1.0.0

◆ H5Eprint2()

herr_t H5Eprint2 ( hid_t  err_stack,
FILE *  stream 
)

Prints the specified error stack in a default manner.


Parameters
[in]err_stackError stack identifier
[in]streamFile pointer, or NULL for stderr
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eprint2() prints the error stack specified by err_stack on the specified stream, stream. Even if the error stack is empty, a one-line message of the following form will be printed:

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 err_stack is H5E_DEFAULT, the current error stack will be printed.

H5Eprint2() is a convenience function for H5Ewalk2() with a function that prints error messages. Users are encouraged to write their own more specific error handlers.

Since
1.8.0

◆ H5Epush1()

herr_t H5Epush1 ( const char *  file,
const char *  func,
unsigned  line,
H5E_major_t  maj,
H5E_minor_t  min,
const char *  str 
)

Pushes a new error record onto the error stack.


Parameters
[in]fileName of the file in which the error was detected
[in]funcName of the function in which the error was detected
[in]lineLine number in the file where the error was detected
[in]majMajor error identifier
[in]minMinor error identifier
[in]strError description string
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
1.8.0 Function H5Epush() renamed to H5Epush1() and deprecated in this release.

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.

Since
1.4.0

◆ H5Epush2()

herr_t H5Epush2 ( hid_t  err_stack,
const char *  file,
const char *  func,
unsigned  line,
hid_t  cls_id,
hid_t  maj_id,
hid_t  min_id,
const char *  msg,
  ... 
)

Pushes a new error record onto an error stack.


Parameters
[in]err_stackError stack identifier. If the identifier is H5E_DEFAULT, the error record will be pushed to the current stack.
[in]fileName of the file in which the error was detected
[in]funcName of the function in which the error was detected
[in]lineLine number in the file where the error was detected
[in]cls_idError class identifier
[in]maj_idMajor error identifier
[in]min_idMinor error identifier
[in]msgError description string
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Epush2() pushes a new error record onto the error stack specified by err_stack.
The error record contains the error class identifier cls_id, the major and minor message identifiers maj_id and min_id, the function name func where the error was detected, the file name file and line number line in the file where the error was detected, and an error description msg.
The major and minor errors must be in the same error class.
The function name, filename, and error description strings must be statically allocated.
msg can be a format control string with additional arguments. This design of appending additional arguments is similar to the system and C functions printf() and fprintf().

Since
1.8.0

◆ H5Eregister_class()

hid_t H5Eregister_class ( const char *  cls_name,
const char *  lib_name,
const char *  version 
)

Registers a client library or application program to the HDF5 error API.


Parameters
[in]cls_nameName of the error class
[in]lib_nameName of the client library or application to which the error class belongs
[in]versionVersion of the client library or application to which the error class belongs. It can be NULL.
Returns
Returns a class identifier on success; otherwise returns H5I_INVALID_ID.

H5Eregister_class() registers a client library or application program to the HDF5 error API so that the client library or application program can report errors together with the HDF5 library. It receives an identifier for this error class for further error operations. The library name and version number will be printed out in the error message as a preamble.

Since
1.8.0

◆ H5Eresume_stack()

herr_t H5Eresume_stack ( hid_t  stack_id)

  • Resume pushing errors on an error stack


Parameters
[in]stack_idError stack identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eresume_stack() resumes pushing errors on an error stack.

     Calls to H5Epause_stack() and H5Eresume_stack() must be matched.

     Calls to H5Epause_stack()/H5Eresume_stack() may be nested.
Since
1.14.5

◆ H5Eset_auto1()

herr_t H5Eset_auto1 ( H5E_auto1_t  func,
void *  client_data 
)

Turns automatic error printing on or off.


Parameters
[in]funcFunction to be called upon an error condition
[in]client_dataData passed to the error function
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and deprecated in this release.

H5Eset_auto1() turns on or off automatic printing of errors. When turned on (non-null func pointer), any API function which returns an error indication will first call func, passing it client_data as an argument.

func, a function conforming to the H5E_auto1_t prototype, is defined in the H5Epublic.h source code file as:

typedef herr_t (*H5E_auto1_t)(void *client_data);
herr_t(* H5E_auto1_t)(void *client_data)
Callback function for H5Eset_auto1()
Definition H5Epublic.h:793
int herr_t
Definition H5public.h:239

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.

Since
1.0.0

◆ H5Eset_auto2()

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

Turns automatic error printing on or off.


Parameters
[in]estack_idError stack identifier
[in]funcFunction to be called upon an error condition
[in]client_dataData passed to the error function
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eset_auto2() turns on or off automatic printing of errors for the error stack specified with estack_id. An estack_id value of H5E_DEFAULT indicates the current stack.

When automatic printing is turned on, by the use of a non-null func pointer, any API function which returns an error indication will first call func, passing it client_data as an argument.

func, a function compliant with the H5E_auto2_t prototype, is defined in the H5Epublic.h source code file as:

typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data);
herr_t(* H5E_auto2_t)(hid_t estack, void *client_data)
Callback function for H5Eset_auto2()
Definition H5Epublic.h:199
int64_t hid_t
Definition H5Ipublic.h:60

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.

Since
1.8.0

◆ H5Eset_current_stack()

herr_t H5Eset_current_stack ( hid_t  err_stack_id)

Replaces the current error stack.


Parameters
[in]err_stack_idError stack identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eset_current_stack() replaces the content of the current error stack with a copy of the content of the error stack specified by err_stack_id, and it closes the error stack specified by err_stack_id.

Since
1.8.0

◆ H5Eunregister_class()

herr_t H5Eunregister_class ( hid_t  class_id)

Removes an error class.


Parameters
[in]class_idError class identifier.
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Eunregister_class() removes the error class specified by class_id. All the major and minor errors in this class will also be closed.

Since
1.8.0

◆ H5Ewalk1()

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

Walks the current error stack, calling the specified function.


Parameters
[in]directionDirection in which the error stack is to be walked
[in]funcFunction to be called for each error encountered
[in]client_dataData to be passed to func
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.
Deprecated:
1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and deprecated in this release.

H5Ewalk1() walks the error stack for the current thread and calls the function specified in func for each error along the way.

direction specifies whether the stack is walked from the inside out or the outside in. A value of H5E_WALK_UPWARD means to begin with the most specific error and end at the API; a value of H5E_WALK_DOWNWARD means to start at the API and end at the innermost function where the error was first detected.

func, a function conforming to the H5E_walk1_t prototype, will be called for each error in the error stack. Its arguments will include an index number n (beginning at zero regardless of stack traversal direction), an error stack entry err_desc, and the client_data pointer passed to H5Eprint(). The H5E_walk1_t prototype is as follows:

typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data);
herr_t(* H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data)
Callback function for H5Ewalk1()
Definition H5Epublic.h:779
Definition H5Epublic.h:756
Since
1.0.0

◆ H5Ewalk2()

herr_t H5Ewalk2 ( hid_t  err_stack,
H5E_direction_t  direction,
H5E_walk2_t  func,
void *  client_data 
)

Walks the specified error stack, calling the specified function.


Parameters
[in]err_stackError stack identifier
[in]directionDirection in which the error stack is to be walked
[in]funcFunction to be called for each error encountered
[in]client_dataData to be passed to func
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Ewalk2() walks the error stack specified by err_stack for the current thread and calls the function specified in func for each error along the way.

If the value of err_stack is H5E_DEFAULT, then H5Ewalk2() walks the current error stack.

direction specifies whether the stack is walked from the inside out or the outside in. A value of H5E_WALK_UPWARD means to begin with the most specific error and end at the API; a value of H5E_WALK_DOWNWARD means to start at the API and end at the innermost function where the error was first detected.

func, a function conforming to the H5E_walk2_t prototype, will be called for each error in the error stack. Its arguments will include an index number n (beginning at zero regardless of stack traversal direction), an error stack entry err_desc, and the client_data pointer passed to H5Eprint(). The H5E_walk2_t prototype is as follows:

typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data);
herr_t(* H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data)
Callback function for H5Ewalk2()
Definition H5Epublic.h:184
Definition H5Epublic.h:35
Since
1.8.0