<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>Error Handling Interface (H5E)</title>
</head>
<body bgcolor="#FFFFFF">
<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="H5.intro.html">Introduction to HDF5</a> <br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
<a href="index.html">Other HDF5 documents and links</a> <br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
<br>
<a href="Files.html">Files</a>
<a href="Datasets.html">Datasets</a>
<a href="Datatypes.html">Datatypes</a>
<a href="Dataspaces.html">Dataspaces</a>
<a href="Groups.html">Groups</a>
<br>
<a href="References.html">References</a>
<a href="Attributes.html">Attributes</a>
<a href="Properties.html">Property Lists</a>
Error Handling
<br>
<a href="Filters.html">Filters</a>
<a href="Caching.html">Caching</a>
<a href="Chunking.html">Chunking</a>
<a href="MountingFiles.html">Mounting Files</a>
<br>
<a href="Performance.html">Performance</a>
<a href="Debugging.html">Debugging</a>
<a href="Environment.html">Environment</a>
<a href="ddl.html">DDL</a>
</td></tr>
</table>
</center>
<hr>
<h1>The Error Handling Interface (H5E)</h1>
<h2>1. Introduction</h2>
<p>When an error occurs deep within the HDF5 library a record is
pushed onto an error stack and that function returns a failure
indication. Its caller detects the failure, pushes another
record onto the stack, and returns a failure indication. This
continues until the application-called API function returns a
failure indication (a negative integer or null pointer). The
next API function which is called (with a few exceptions) resets
the stack.
<h2>2. Error Handling Operations</h2>
<p>In normal circumstances, an error causes the stack to be
printed on the standard error stream. The first item, number
"#000" is produced by the API function itself and is usually
sufficient to indicate to the application programmer what went
wrong.
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: An Error Message</h4></caption>
<tr>
<td>
<p>If an application calls <code>H5Tclose</code> on a
predefined datatype then the following message is
printed on the standard error stream. This is a
simple error that has only one component, the API
function; other errors may have many components.
<p><code><pre>
HDF5-DIAG: Error detected in thread 0. Back trace follows.
#000: H5T.c line 462 in H5Tclose(): predefined datatype
major(01): Function argument
minor(05): Bad value
</code></pre>
</td>
</tr>
</table>
</center>
<p>The error stack can also be printed and manipulated by these
functions, but if an application wishes make explicit calls to
<code>H5Eprint()</code> then the automatic printing should be
turned off to prevent error messages from being displayed twice
(see <code>H5Eset_auto()</code> below).
<dl>
<dt><code>herr_t H5Eprint (FILE *<em>stream</em>)</code>
<dd>The error stack is printed on the specified stream. Even if
the error stack is empty a one-line message will be printed:
<code>HDF5-DIAG: Error detected in thread 0.</code>
<br><br>
<dt><code>herr_t H5Eclear (void)</code>
<dd>The error stack can be explicitly cleared by calling this
function. The stack is also cleared whenever an API function
is called, with certain exceptions (for instance,
<code>H5Eprint()</code>).
</dl>
<p>Sometimes an application will call a function for the sake of
its return value, fully expecting the function to fail. Under
these conditions, it would be misleading if an error message
were automatically printed. Automatic printing of messages is
controlled by the <code>H5Eset_auto()</code> function:
<dl>
<dt><code>herr_t H5Eset_auto (herr_t(*<em>func</em>)(void*),
void *<em>client_data</em>)</code>
<dd>If <em>func</em> is not a null pointer, then the function to
which it points will be called automatically when an API
function is about to return an indication of failure. The
function is called with a single argument, the
<em>client_data</em> pointer. When the library is first
initialized the auto printing function is set to
<code>H5Eprint()</code> (cast appropriately) and
<em>client_data</em> is the standard error stream pointer,
<code>stderr</code>.
<br><br>
<dt><code>herr_t H5Eget_auto (herr_t(**<em>func</em>)(void*),
void **<em>client_data</em>)</code>
<dd>This function returns the current automatic error traversal
settings through the <em>func</em> and <em>client_data</em>
arguments. Either (or both) arguments may be null pointers in
which case the corresponding information is not returned.
</dl>
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: Error Control</h4></caption>
<tr>
<td>
<p>An application can temporarily turn off error
messages while "probing" a function.
<p><code><pre>
/* Save old error handler */
herr_t (*old_func)(void*);
void *old_client_data;
H5Eget_auto(&old_func, &old_client_data);
/* Turn off error handling */
H5Eset_auto(NULL, NULL);
/* Probe. Likely to fail, but that's okay */
status = H5Fopen (......);
/* Restore previous error handler */
H5Eset_auto(old_func, old_client_data);
</code></pre>
<p>Or automatic printing can be disabled altogether and
error messages can be explicitly printed.
<p><code><pre>
/* Turn off error handling permanently */
H5Eset_auto (NULL, NULL);
/* If failure, print error message */
if (H5Fopen (....)<0) {
H5Eprint (stderr);
exit (1);
}
</code></pre>
</td>
</tr>
</table>
</center>
<p>The application is allowed to define an automatic error
traversal function other than the default
<code>H5Eprint()</code>. For instance, one could define a
function that prints a simple, one-line error message to the
standard error stream and then exits.
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: Simple Messages</h4></caption>
<tr>
<td>
<p>The application defines a function to print a simple
error message to the standard error stream.
<p><code><pre>
herr_t
my_hdf5_error_handler (void *unused)
{
fprintf (stderr, "An HDF5 error was detected. Bye.\n");
exit (1);
}
</code></pre>
<p>The function is installed as the error handler by
saying
<p><code><pre>
H5Eset_auto (my_hdf5_error_handler, NULL);
</code></pre>
</td>
</tr>
</table>
</center>
<p>The <code>H5Eprint()</code> function is actually just a wrapper
around the more complex <code>H5Ewalk()</code> function which
traverses an error stack and calls a user-defined function for
each member of the stack.
<dl>
<dt><code>herr_t H5Ewalk (H5E_direction_t <em>direction</em>,
H5E_walk_t <em>func</em>, void *<em>client_data</em>)</code>
<dd>The error stack is traversed and <em>func</em> is called for
each member of the stack. Its arguments are an integer
sequence number beginning at zero (regardless of
<em>direction</em>), a pointer to an error description record,
and the <em>client_data</em> pointer. If <em>direction</em>
is <code>H5E_WALK_UPWARD</code> then traversal begins at the
inner-most function that detected the error and concludes with
the API function. The opposite order is
<code>H5E_WALK_DOWNWARD</code>.
<br><br>
<dt><code>typedef herr_t (*H5E_walk_t)(int <em>n</em>,
H5E_error_t *<em>eptr</em>, void
*<em>client_data</em>)</code>
<dd>An error stack traversal callback function takes three
arguments: <em>n</em> is a sequence number beginning at zero
for each traversal, <em>eptr</em> is a pointer to an error
stack member, and <em>client_data</em> is the same pointer
passed to <code>H5Ewalk()</code>.
<br><br>
<dt><pre><code>typedef struct {
H5E_major_t <em>maj_num</em>;
H5E_minor_t <em>min_num</em>;
const char *<em>func_name</em>;
const char *<em>file_name</em>;
unsigned <em>line</em>;
const char *<em>desc</em>;
} H5E_error_t;</code></pre>
<dd>The <em>maj_num</em> and <em>min_num</em> are major
and minor error numbers, <em>func_name</em> is the name of
the function where the error was detected,
<em>file_name</em> and <em>line</em> locate the error
within the HDF5 library source code, and <em>desc</em>
points to a description of the error.
<br><br>
<dt><code>const char *H5Eget_major (H5E_major_t <em>num</em>)</code>
<dt><code>const char *H5Eget_minor (H5E_minor_t <em>num</em>)</code>
<dd>These functions take a major or minor error number and
return a constant string which describes the error. If
<em>num</em> is out of range than a string like "Invalid major
error number" is returned.
</dl>
<p>
<center>
<table border align=center width="100%">
<caption align=top><h4>Example: H5Ewalk_cb</h4></caption>
<tr>
<td>
<p>This is the implementation of the default error stack
traversal callback.
<p><code><pre>
herr_t
H5Ewalk_cb(int n, H5E_error_t *err_desc, void *client_data)
{
FILE *stream = (FILE *)client_data;
const char *maj_str = NULL;
const char *min_str = NULL;
const int indent = 2;
/* Check arguments */
assert (err_desc);
if (!client_data) client_data = stderr;
/* Get descriptions for the major and minor error numbers */
maj_str = H5Eget_major (err_desc->maj_num);
min_str = H5Eget_minor (err_desc->min_num);
/* Print error message */
fprintf (stream, "%*s#%03d: %s line %u in %s(): %s\n",
indent, "", n, err_desc->file_name, err_desc->line,
err_desc->func_name, err_desc->desc);
fprintf (stream, "%*smajor(%02d): %s\n",
indent*2, "", err_desc->maj_num, maj_str);
fprintf (stream, "%*sminor(%02d): %s\n",
indent*2, "", err_desc->min_num, min_str);
return 0;
}
</code></pre>
</td>
</tr>
</table>
</center>
<hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="H5.intro.html">Introduction to HDF5</a> <br>
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
<a href="index.html">Other HDF5 documents and links</a> <br>
<!--
<a href="Glossary.html">Glossary</a><br>
-->
</td>
<td valign=top align=right>
And in this document, the
<a href="H5.user.html"><strong>HDF5 User's Guide:</strong></a>
<br>
<a href="Files.html">Files</a>
<a href="Datasets.html">Datasets</a>
<a href="Datatypes.html">Datatypes</a>
<a href="Dataspaces.html">Dataspaces</a>
<a href="Groups.html">Groups</a>
<br>
<a href="References.html">References</a>
<a href="Attributes.html">Attributes</a>
<a href="Properties.html">Property Lists</a>
Error Handling
<br>
<a href="Filters.html">Filters</a>
<a href="Caching.html">Caching</a>
<a href="Chunking.html">Chunking</a>
<a href="MountingFiles.html">Mounting Files</a>
<br>
<a href="Performance.html">Performance</a>
<a href="Debugging.html">Debugging</a>
<a href="Environment.html">Environment</a>
<a href="ddl.html">DDL</a>
</td></tr>
</table>
</center>
<hr>
<address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
</address>
<!-- Created: Fri Feb 27 23:42:52 EST 1998 -->
<!-- hhmts start -->
Last modified: 13 December 1999
<!-- hhmts end -->
<br>
Describes HDF5 Release 1.5, Unreleased Development Branch
</body>
</html>