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_id	Error stack identifier
[in]	src_stack_id	Error stack identifier
[in]	close_source_stack	Flag 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_stack	Error stack identifier
[out]	is_stack	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.

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_stack Error 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_id An 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_id Error 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]	cls	An error class identifier
[in]	msg_type	The type of the error message
[in]	msg	Error 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]	func	Current setting for the function to be called upon an error condition
[out]	client_data	Current 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_id	Error stack identifier
[out]	func	The function currently set to be called upon an error condition
[out]	client_data	Data 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_id	Error class identifier
[out]	name	Buffer for the error class name
[in]	size	The 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] maj Major 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] min Minor 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_id	Error message identifier
[out]	type	The type of the error message. Valid values are H5E_MAJOR and H5E_MINOR.
[out]	msg	Error message buffer
[in]	size	The 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_id Error 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_id	Error stack identifier
[out]	is_paused	Flag 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_id Error 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_stack	Error stack identifier
[in]	count	The 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] stream File 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_stack	Error stack identifier
[in]	stream	File 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]	file	Name of the file in which the error was detected
[in]	func	Name of the function in which the error was detected
[in]	line	Line number in the file where the error was detected
[in]	maj	Major error identifier
[in]	min	Minor error identifier
[in]	str	Error 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_stack	Error stack identifier. If the identifier is H5E_DEFAULT, the error record will be pushed to the current stack.
[in]	file	Name of the file in which the error was detected
[in]	func	Name of the function in which the error was detected
[in]	line	Line number in the file where the error was detected
[in]	cls_id	Error class identifier
[in]	maj_id	Major error identifier
[in]	min_id	Minor error identifier
[in]	msg	Error 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_name	Name of the error class
[in]	lib_name	Name of the client library or application to which the error class belongs
[in]	version	Version 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_id Error 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]	func	Function to be called upon an error condition
[in]	client_data	Data 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);

H5E_auto1_t

herr_t(* H5E_auto1_t)(void *client_data)

Callback function for H5Eset_auto1()

Definition H5Epublic.h:793

herr_t

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_id	Error stack identifier
[in]	func	Function to be called upon an error condition
[in]	client_data	Data 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);

H5E_auto2_t

herr_t(* H5E_auto2_t)(hid_t estack, void *client_data)

Callback function for H5Eset_auto2()

Definition H5Epublic.h:199

hid_t

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_id Error 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_id Error 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]	direction	Direction in which the error stack is to be walked
[in]	func	Function to be called for each error encountered
[in]	client_data	Data 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);

H5E_walk1_t

herr_t(* H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data)

Callback function for H5Ewalk1()

Definition H5Epublic.h:779

H5E_error1_t

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_stack	Error stack identifier
[in]	direction	Direction in which the error stack is to be walked
[in]	func	Function to be called for each error encountered
[in]	client_data	Data 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);

H5E_walk2_t

herr_t(* H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data)

Callback function for H5Ewalk2()

Definition H5Epublic.h:184

H5E_error2_t

Definition H5Epublic.h:35

Since: 1.8.0

Detailed Description

Macros

Functions

Macro Definition Documentation

◆ H5Eget_auto

◆ H5Eprint

◆ H5Epush

◆ H5Eset_auto

◆ H5Ewalk

Function Documentation

◆ H5Eappend_stack()

◆ H5Eauto_is_v2()

◆ H5Eclear1()

◆ H5Eclear2()

◆ H5Eclose_msg()

◆ H5Eclose_stack()

◆ H5Ecreate_msg()

◆ H5Ecreate_stack()

◆ H5Eget_auto1()

◆ H5Eget_auto2()

◆ H5Eget_class_name()

◆ H5Eget_current_stack()

◆ H5Eget_major()

◆ H5Eget_minor()

◆ H5Eget_msg()

◆ H5Eget_num()

◆ H5Eis_paused()

◆ H5Epause_stack()

◆ H5Epop()

◆ H5Eprint1()

◆ H5Eprint2()

◆ H5Epush1()

◆ H5Epush2()

◆ H5Eregister_class()

◆ H5Eresume_stack()

◆ H5Eset_auto1()

◆ H5Eset_auto2()

◆ H5Eset_current_stack()

◆ H5Eunregister_class()

◆ H5Ewalk1()

◆ H5Ewalk2()