Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Exception Class Reference

`#include <c++/src/H5Exception.h>`

## Detailed Description

Exception provides wrappers of HDF5 error handling functions.

Many classes are derived from Exception for specific HDF5 C interfaces.

Inheritance diagram for Exception:

## Public Member Functions
| Exception ()
| Default constructor.
| Exception (const Exception &orig)
| Copy constructor: same HDF5 object as original.
| Exception (const std::string &func_name, const std::string &message=DEFAULT_MSG)
| Creates an exception with the name of the function, in which the failure occurs, and an optional detailed message.
const char * | getCDetailMsg () const
| Returns the detailed message set at the time the exception is thrown.
const char * | getCFuncName () const
| Returns the name of the function, where the exception is thrown.
std::string | getDetailMsg () const
| Returns the detailed message set at the time the exception is thrown.
std::string | getFuncName () const
| Returns the name of the function, where the exception is thrown.
std::string | getMajorString (hid_t err_major_id) const
| Returns a text string that describes the error specified by a major error number.
std::string | getMinorString (hid_t err_minor_id) const
| Returns a text string that describes the error specified by a minor error number.
virtual | ~Exception ()=default

## Static Public Member Functions
static void | clearErrorStack ()
| Clears the error stack for the current thread.
static void | dontPrint ()
| Turns off the automatic error printing from the C library.
static void | getAutoPrint (H5E_auto2_t &func, void **client_data)
| Retrieves the current settings for the automatic error stack traversal function and its data.
static void | printErrorStack (FILE *stream=stderr, hid_t err_stack=H5E_DEFAULT)
| Prints the error stack in a default manner.
static void | setAutoPrint (H5E_auto2_t &func, void *client_data)
| Turns on the automatic error printing.
static void | walkErrorStack (H5E_direction_t direction, H5E_walk2_t func, void *client_data)
| Walks the error stack for the current thread, calling the specified function.

## Static Protected Attributes
static const char | DEFAULT_MSG [] = "No detailed information provided"

## Constructor & Destructor Documentation

## ◆ Exception() [1/3]

Exception | ( | const std::string & | func,
|  | const std::string & | message = DEFAULT_MSG )

Creates an exception with the name of the function, in which the failure occurs, and an optional detailed message.

Parameters

  func | - IN: Name of the function where failure occurs
  message | - IN: Message on the failure

## ◆ Exception() [2/3]

Exception | ( |  | ) |

Default constructor.

## ◆ Exception() [3/3]

Exception | ( | const Exception & | orig | ) |

Copy constructor: same HDF5 object as original.

Parameters

  orig | - IN: Exception instance to copy

## ◆ ~Exception()

virtual ~Exception | ( |  | ) |
| virtual default

## Member Function Documentation

## ◆ clearErrorStack()

void clearErrorStack | ( |  | ) |
| static

Clears the error stack for the current thread.

Description
  The stack is also cleared whenever a C API function is called, with certain exceptions (for instance, `H5Eprint`).

## ◆ dontPrint()

void dontPrint | ( |  | ) |
| static

Turns off the automatic error printing from the C library.

## ◆ getAutoPrint()

void getAutoPrint | ( | H5E_auto2_t & | func,
|  | void ** | client_data )
| static

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

Parameters

  func | - OUT: Current setting for the function to be called upon an error condition
  client_data | - OUT: Current setting for the data passed to the error function

## ◆ getCDetailMsg()

const char * getCDetailMsg | ( |  | ) | const

Returns the detailed message set at the time the exception is thrown.

Returns
  Text message - `char` pointer

## ◆ getCFuncName()

const char * getCFuncName | ( |  | ) | const

Returns the name of the function, where the exception is thrown.

Returns
  Text message - `char` pointer

## ◆ getDetailMsg()

std::string getDetailMsg | ( |  | ) | const

Returns the detailed message set at the time the exception is thrown.

Returns
  Text message - `H5std_string`

## ◆ getFuncName()

std::string getFuncName | ( |  | ) | const

Returns the name of the function, where the exception is thrown.

Returns
  Text message - `H5std_string`

## ◆ getMajorString()

std::string getMajorString | ( | hid_t | err_major | ) | const

Returns a text string that describes the error specified by a major error number.

Parameters

  err_major | - IN: Major error number

Returns
  Major error string

Description
  In the failure case, the string "Invalid major error number" will be returned.

## ◆ getMinorString()

std::string getMinorString | ( | hid_t | err_minor | ) | const

Returns a text string that describes the error specified by a minor error number.

Parameters

  err_minor | - IN: Minor error number

Returns
  Minor error string

Description
  In the failure case, the string "Invalid minor error number" will be returned.

## ◆ printErrorStack()

void printErrorStack | ( | FILE * | stream = stderr,
|  | hid_t | err_stack = H5E_DEFAULT )
| static

Prints the error stack in a default manner.

Parameters

  stream | - IN: File pointer, default to stderr
  err_stack | - IN: Error stack ID, default to H5E_DEFAULT(0)

## ◆ setAutoPrint()

void setAutoPrint | ( | H5E_auto2_t & | func,
|  | void * | client_data )
| static

Turns on the automatic error printing.

Parameters

  func | - IN: Function to be called upon an error condition
  client_data | - IN: Data passed to the error function

Description
  When the library is first initialized the auto printing function, func, is set to the C API `H5Eprint` and client_data is the standard error stream pointer, `stderr`. Automatic stack traversal is always in the `H5E_WALK_DOWNWARD` direction.

  Users are encouraged to write their own more specific error handlers

## ◆ walkErrorStack()

void walkErrorStack | ( | H5E_direction_t | direction,
|  | H5E_walk2_t | func,
|  | void * | client_data )
| static

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

Parameters

  direction | - IN: Direction in which the error stack is to be walked
  func | - IN: Function to be called for each error encountered
  client_data | - IN: Data passed to the error function

Description
  Valid values for direction include:
  - `H5E_WALK_UPWARD` - begin with the most specific error and end at the API
  - `H5E_WALK_DOWNWARD` - begin at the API and end at the inner-most function where the error was first detected

  The function specified by func will be called for each error in the error stack. The `H5E_walk_t` prototype is as follows:
  typedef herr_t (*H5E_walk_t)(int n, H5E_error_t *err_desc, void *client_data)
  int n - Indexed position of the error in the stack; it begins at zero
  regardless of stack traversal direction
  H5E_error_t *err_desc - Pointer to a data structure describing the
  error. This structure is listed below.
  void *client_data - Pointer to client data in the format expected by
  the user-defined function.
  herr_t
  int herr_t
  Definition H5public.h:269
  H5E_error_t
  #define H5E_error_t
  Definition H5version.h:1213
  H5E_walk_t
  #define H5E_walk_t
  Definition H5version.h:1214

  Data structure to describe the error:
  typedef struct H5E_error2_t {
  hid_t cls_id; //class ID
  hid_t maj_num; //major error ID
  hid_t min_num; //minor error number
  const char *func_name; //function in which error occurred
  const char *file_name; //file in which error occurred
  unsigned line; //line in file where error occurs
  const char *desc; //optional supplied description
  } H5E_error2_t;
  hid_t
  int64_t hid_t
  Definition H5Ipublic.h:60
  H5E_error2_t
  Definition H5Epublic.h:35

## Field Documentation

## ◆ DEFAULT_MSG

const char DEFAULT_MSG = "No detailed information provided"
| static protected

The documentation for this class was generated from the following files:

- c++/src/H5Exception.h
- c++/src/H5Exception.cpp