summaryrefslogtreecommitdiffstats
path: root/doc/html/RM_H5E.html
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>1998-07-15 04:51:50 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>1998-07-15 04:51:50 (GMT)
commitc8e75d27b018deb862171a153dd640455dbe26fb (patch)
tree0056588a00653bd4f6fff761482837baa9396a11 /doc/html/RM_H5E.html
parent3e213ecf064638989c816ba3a10b3b6c6307fdad (diff)
downloadhdf5-c8e75d27b018deb862171a153dd640455dbe26fb.zip
hdf5-c8e75d27b018deb862171a153dd640455dbe26fb.tar.gz
hdf5-c8e75d27b018deb862171a153dd640455dbe26fb.tar.bz2
[svn-r503] HDF5 Reference Manual
Updated for Alpha2.
Diffstat (limited to 'doc/html/RM_H5E.html')
-rw-r--r--doc/html/RM_H5E.html361
1 files changed, 361 insertions, 0 deletions
diff --git a/doc/html/RM_H5E.html b/doc/html/RM_H5E.html
new file mode 100644
index 0000000..e3c8177
--- /dev/null
+++ b/doc/html/RM_H5E.html
@@ -0,0 +1,361 @@
+<html>
+<head><title>
+HDF5/H5E Draft API Specification
+</title></head>
+
+<body>
+
+<hr>
+<center>
+<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
+<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
+<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
+<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
+H5E&nbsp;&nbsp;
+<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
+<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
+<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
+<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
+<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
+<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
+<a href="Glossary.html">Glossary</a>
+</center>
+<hr>
+
+<center>
+<h1>H5E: Error Interface</h1>
+</center>
+
+<h2>Error API Functions</h2>
+
+These functions provide error handling capabilities in the HDF5 environment.
+
+<table border=0>
+<tr><td valign=top>
+<ul>
+ <li><a href="#Error-SetAuto">H5Eset_auto</a>
+ <li><a href="#Error-GetAuto">H5Eget_auto</a>
+ <li><a href="#Error-Clear">H5Eclear</a>
+</ul>
+</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
+<ul>
+ <li><a href="#Error-Print">H5Eprint</a>
+ <li><a href="#Error-Walk">H5Ewalk</a>
+ <li><a href="#Error-WalkCB">H5Ewalk_cb</a>
+</ul>
+</td><td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td><td valign=top>
+<ul>
+ <li><a href="#Error-GetMajor">H5Eget_major</a>
+ <li><a href="#Error-GetMinor">H5Eget_minor</a>
+</ul>
+</td></tr>
+</table>
+
+<p>
+The Error interface provides error handling in the form of a stack.
+The <code>FUNC_ENTER()</code> macro clears the error stack whenever
+an interface function is entered.
+When an error is detected, an entry is pushed onto the stack.
+As the functions unwind, additional entries are pushed onto the stack.
+The API function will return some indication that an error occurred and
+the application can print the error stack.
+<p>
+Certain API functions in the H5E package, such as <code>H5Eprint()</code>,
+do not clear the error stack. Otherwise, any function which
+does not have an underscore immediately after the package name
+will clear the error stack. For instance, <code>H5Fopen()</code>
+clears the error stack while <code>H5F_open()</code> does not.
+<p>
+An error stack has a fixed maximum size.
+If this size is exceeded then the stack will be truncated and only the
+inner-most functions will have entries on the stack.
+This is expected to be a rare condition.
+<p>
+Each thread has its own error stack, but since
+multi-threading has not been added to the library yet, this
+package maintains a single error stack. The error stack is
+statically allocated to reduce the complexity of handling
+errors within the H5E package.
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-SetAuto">H5Eset_auto</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Eset_auto</code>(<em>H5E_auto_t</em> <code>func</code>,
+ <em>void *</em><code>client_data</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Turns automatic error printing on or off.
+<dt><strong>Description:</strong>
+ <dd><code>H5Eset_auto</code> turns on or off automatic printing of
+ errors. When turned on (non-null <code>func</code> pointer),
+ any API function which returns an error indication will
+ first call <code>func</code>, passing it <code>client_data</code>
+ as an argument.
+ <p>
+ When the library is first initialized the auto printing function
+ is set to <code>H5Eprint()</code> (cast appropriately) and
+ <code>client_data</code> is the standard error stream pointer,
+ <code>stderr</code>.
+ <p>
+ Automatic stack traversal is always in the
+ <code>H5E_WALK_DOWNWARD</code> direction.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>H5E_auto_t</em> <code>func</code>
+ <dd>Function to be called upon an error condition.
+ <dt><em>void *</em><code>client_data</code>
+ <dd>Data passed to the error function.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-GetAuto">H5Eget_auto</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Eget_auto</code>(<em>H5E_auto_t *</em> <code>func</code>,
+ <em>void **</em><code>client_data</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Returns the current settings for the automatic error stack
+ traversal function and its data.
+<dt><strong>Description:</strong>
+ <dd><code>H5Eget_auto</code> returns the current settings for the
+ automatic error stack traversal function, <code>func</code>,
+ and its data, <code>client_data</code>. Either (or both)
+ arguments may be null in which case the value is not returned.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>H5E_auto_t *</em> <code>func</code>
+ <dd>Current setting for the function to be called upon an
+ error condition.
+ <dt><em>void **</em><code>client_data</code>
+ <dd>Current setting for the data passed to the error function.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-Clear">H5Eclear</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Eclear</code>(<code>void</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Clears the error stack for the current thread.
+<dt><strong>Description:</strong>
+ <dd><code>H5Eclear</code> clears the error stack for the current thread.
+ <p>
+ The stack is also cleared whenever an API function is called,
+ with certain exceptions (for instance, <code>H5Eprint()</code>).
+ <p>
+ <code>H5Eclear</code> can fail if there are problems initializing
+ the library.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt>None
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-Print">H5Eprint</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Eprint</code>(<em>FILE *</em> <code>stream</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Prints the error stack in a default manner.
+<dt><strong>Description:</strong>
+ <dd><code>H5Eprint</code> prints the error stack on the specified
+ stream, <code>stream</code>.
+ Even if the error stack is empty, a one-line message will be printed:
+ <br>&nbsp;&nbsp;&nbsp;&nbsp;
+ <code>HDF5-DIAG: Error detected in thread 0.</code>
+ <p>
+ <code>H5Eprint</code> is a convenience function for
+ <code>H5Ewalk()</code> with a function that prints error messages.
+ Users are encouraged to write there own more specific error handlers.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>FILE *</em> <code>stream</code>
+ <dd>File pointer, or stderr if NULL.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-Walk">H5Ewalk</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Ewalk</code>(<em>H5E_direction_t</em> <code>direction</code>,
+ <em>H5E_walk_t</em> <code>func</code>,
+ <em>void *</em> <code>client_data</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Walks the error stack for the current thread, calling a specified
+ function.
+<dt><strong>Description:</strong>
+ <dd><code>H5Ewalk</code> walks the error stack for the current thread
+ and calls the specified function for each error along the way.
+ <p>
+ <code>direction</code> determines whether the stack is walked
+ from the inside out or the outside in.
+ A value of <code>H5E_WALK_UPWARD</code> means begin with the
+ most specific error and end at the API;
+ a value of <code>H5E_WALK_DOWNWARD</code> means to start at the
+ API and end at the inner-most function where the error was first
+ detected.
+ <p>
+ <code>func</code> will be called for each error in the error stack.
+ Its arguments will include an index number (beginning at zero
+ regardless of stack traversal direction), an error stack entry,
+ and the <code>client_data</code> pointer passed to
+ <code>H5E_print</code>.
+ <p>
+ <code>H5Ewalk</code> can fail if there are problems initializing
+ the library.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>H5E_direction_t</em> <code>direction</code>
+ <dd>Direction in which the error stack is to be walked.
+ <dt><em>H5E_walk_t</em> <code>func</code>
+ <dd>Function to be called for each error encountered.
+ <dt><em>void *</em> <code>client_data</code>
+ <dd>Data to be passed with <code>func</code>.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-WalkCB">H5Ewalk_cb</a>
+<dt><strong>Signature:</strong>
+ <dd><em>herr_t</em> <code>H5Ewalk_cb</code>(<em>int</em> <code>n</code>,
+ <em>H5E_error_t *</em><code>err_desc</code>,
+ <em>void</em> <code>*client_data</code>
+ )
+<dt><strong>Purpose:</strong>
+ <dd>Default error stack traversal callback function
+ that prints error messages to the specified output stream.
+<dt><strong>Description:</strong>
+ <dd><code>H5Ewalk_cb</code> is a default error stack traversal callback
+ function that prints error messages to the specified output stream.
+ It is not meant to be called directly but rather as an
+ argument to the <code>H5Ewalk()</code> function.
+ This function is called also by <code>H5Eprint()</code>.
+ Application writers are encouraged to use this function as a
+ model for their own error stack walking functions.
+ <p>
+ <code>n</code> is a counter for how many times this function
+ has been called for this particular traversal of the stack.
+ It always begins at zero for the first error on the stack
+ (either the top or bottom error, or even both, depending on
+ the traversal direction and the size of the stack).
+ <p>
+ <code>err_desc</code> is an error description. It contains all the
+ information about a particular error.
+ <p>
+ <code>client_data</code> is the same pointer that was passed as the
+ <code>client_data</code> argument of <code>H5Ewalk()</code>.
+ It is expected to be a file pointer (or stderr if null).
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>int</em> <code>n</code>
+ <dd>Number of times this function has been called
+ for this traversal of the stack.
+ <dt><em>H5E_error_t *</em><code>err_desc</code>
+ <dd>Error description.
+ <dt><em>void</em> <code>*client_data</code>
+ <dd>A file pointer, or stderr if null.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd>Returns SUCCEED (0) if successful;
+ otherwise FAIL (-1).
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-GetMajor">H5Eget_major</a>
+<dt><strong>Signature:</strong>
+ <dd><em>const char *</em> <code>H5Eget_major</code>(<em>H5E_major_t</em> <code>n</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Returns a character string describing an error specified by a
+ major error number.
+<dt><strong>Description:</strong>
+ <dd>Given a major error number, <code>H5Eget_major</code> returns a
+ constant character string that describes the error.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>H5E_major_t</em> <code>n</code>
+ <dd>Major error number.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd> Returns a character string describing the error if successful.
+ Otherwise returns "Invalid major error number."
+</dl>
+
+
+<hr>
+<dl>
+<dt><strong>Name:</strong> <a name="Error-GetMinor">H5Eget_minor</a>
+<dt><strong>Signature:</strong>
+ <dd><em>const char *</em> <code>H5Eget_minor</code>(<em>H5E_minor_t</em> <code>n</code>)
+<dt><strong>Purpose:</strong>
+ <dd>Returns a character string describing an error specified by a
+ minor error number.
+<dt><strong>Description:</strong>
+ <dd>Given a minor error number, <code>H5Eget_minor</code> returns a
+ constant character string that describes the error.
+<dt><strong>Parameters:</strong>
+ <dl>
+ <dt><em>H5E_minor_t</em> <code>n</code>
+ <dd>Minor error number.
+ </dl>
+<dt><strong>Returns:</strong>
+ <dd> Returns a character string describing the error if successful.
+ Otherwise returns "Invalid minor error number."
+</dl>
+
+
+<hr>
+<center>
+<a href="RM_H5Front.html">HDF5 Reference Manual</a>&nbsp;
+<a href="RM_H5.html">H5</a>&nbsp;&nbsp;
+<a href="RM_H5A.html">H5A</a>&nbsp;&nbsp;
+<a href="RM_H5D.html">H5D</a>&nbsp;&nbsp;
+H5E&nbsp;&nbsp;
+<a href="RM_H5F.html">H5F</a>&nbsp;&nbsp;
+<a href="RM_H5G.html">H5G</a>&nbsp;&nbsp;
+<a href="RM_H5P.html">H5P</a>&nbsp;&nbsp;
+<a href="RM_H5S.html">H5S</a>&nbsp;&nbsp;
+<a href="RM_H5T.html">H5T</a>&nbsp;&nbsp;
+<a href="RM_H5Z.html">H5Z</a>&nbsp;&nbsp;
+<a href="Glossary.html">Glossary</a>
+</center>
+<hr>
+
+<address>
+<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
+
+<br>
+Last modified: 14 July 1998
+
+</body>
+</html>