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:

hid_t `estack_id` | IN: Error stack identifier.
H5E_direction_t `direction` | IN: Direction in which the error stack is to be walked.
H5E_walk2_t `func` | IN: Function to be called for each error encountered.
void * `client_data` | IN: Data to be passed with `func`.

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.