mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-01-30 15:32:37 +08:00
82fb21b613
been checked into "HDF5 Development" branch. General ======= Various "copy edit" types of repairs. Revisions to document cross-linking. Added structural links tying all docs together (banners at top and bottom of documents, similar to Reference Manual banners of the Beta release). Set background color to white in all documents. NCSAfooterlogo.gif hdf2.jpg New image files to make the documents more self-contained (i.e., to prevent loading images from NCSA and HDF home servers). index.html Redesigned to isolate links external to the installation in a single location. Intro to HDF5 ============= H5.intro.html Fixed banner linking Intro to other docs. Set all URLs to be relative within the distribution; nothing points back to the HDF server. Updates to "Limits of the Current Release" and "Changes in the Current Release." HDF5 User's Guide ================= Changed several User Guide section titles such that all sections that are primarily about a particular interface are now titled in the format "The xxxxx Interface (H5x)". H5.user.html Commented out links to developer docs since they are marked in MANIFEST as not being for distribution in the release. Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. Datatypes.html Removed the sentence "I'm deferring definition until later since they're probably not as important as the other data types." from Section 3.3, "Properties of Date and Time Atomic Types." Added info regarding 'char' versus 'string' datatypes. Added as Section 3.7, "Character and String Datatype Issues." References.html Commented out substantial material (at end of document) from References planning document that is not appropriate for the User Guide but that is worth keeping around. Groups.html Final edits from elimination of "current working group." HDF5 Reference Manual ===================== Removed "Draft" from the <title>__</title> lines. RM_H5Front.html Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. RM_H5F.html RM_H5P.html Add file mounting information.
414 lines
14 KiB
HTML
414 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>The 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">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
Error Handling
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</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.
|
|
|
|
<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 data type 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 data type
|
|
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</em> 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">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
Error Handling
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</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:hdf5dev@ncsa.uiuc.edu">Robb Matzke</a></address>
|
|
-->
|
|
<!-- Created: Fri Feb 27 23:42:52 EST 1998 -->
|
|
<!-- hhmts start -->
|
|
<!--
|
|
Last modified: Wed Mar 4 10:06:17 EST 1998
|
|
-->
|
|
<!-- hhmts end -->
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
Last modified: 30 October 1998
|
|
|
|
</body>
|
|
</html>
|