mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
a901d24a8b
Purpose:
Renamed old "HDF5 User's Guide" as "HDF5 User's Guide, Release 1.4.5".
Added navigation bar link to new user's guide on HDF server.
Changed release tag line (in old UG only) back to
"Describes HDF5 Release 1.4.5, February 200 3"
Platforms tested:
IE 5
387 lines
14 KiB
HTML
387 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Error Handling Interface (H5E)</title>
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/styles_UG.lbi" -->
|
|
<!--
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
* Copyright by the Board of Trustees of the University of Illinois. *
|
|
* All rights reserved. *
|
|
* *
|
|
* This file is part of HDF5. The full HDF5 copyright notice, including *
|
|
* terms governing use, modification, and redistribution, is contained in *
|
|
* the files COPYING and Copyright.html. COPYING can be found at the root *
|
|
* of the source code distribution tree; Copyright.html can be found at the *
|
|
* root level of an installed copy of the electronic HDF5 document set and *
|
|
* is linked from the top-level documents page. It can also be found at *
|
|
* http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have *
|
|
* access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
-->
|
|
|
|
<link href="ed_styles/UGelect.css" rel="stylesheet" type="text/css">
|
|
<!-- #EndLibraryItem --></head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</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 from Release 1.4.5:</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>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<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>
|
|
<!-- #EndLibraryItem --><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>
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</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 from Release 1.4.5:</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>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<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>
|
|
<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
<br>
|
|
Describes HDF5 Release 1.4.5, February 2003
|
|
</address><!-- #EndLibraryItem --><!-- Created: Fri Feb 27 23:42:52 EST 1998 -->
|
|
<!-- hhmts start -->
|
|
Last modified: 13 December 1999
|
|
<!-- hhmts end -->
|
|
|
|
</body>
|
|
</html>
|