summaryrefslogtreecommitdiffstats
path: root/doc/src/RM_H5E.html
diff options
context:
space:
mode:
authorFrank Baker <fbaker@hdfgroup.org>2005-07-19 17:28:56 (GMT)
committerFrank Baker <fbaker@hdfgroup.org>2005-07-19 17:28:56 (GMT)
commit794ba0a251af47b8e3c60afa2fe92d267e2a6b55 (patch)
treef24cea3b81ff02fa3f31c0a1c4e80fa10f4393c0 /doc/src/RM_H5E.html
parentd2e92fd23610c3ccdddbbc55484e54a5a21a9252 (diff)
downloadhdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.zip
hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.gz
hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.bz2
[svn-r11084]
Description: All HDF5 user documentation has been moved to a separate hdf5doc/ repository, managed under Subversion. With this 'cvs commit', all files are stripped from hdf5/doc/. THIS CHANGE IS APPLIED ONLY TO THE HDF5 DEVELOPMENT BRANCH, post Release 1.6.x; it is not applied to the release branches.
Diffstat (limited to 'doc/src/RM_H5E.html')
-rw-r--r--doc/src/RM_H5E.html367
1 files changed, 0 insertions, 367 deletions
diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html
deleted file mode 100644
index d29380e..0000000
--- a/doc/src/RM_H5E.html
+++ /dev/null
@@ -1,367 +0,0 @@
-<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="Tools.html">Tools</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="Tools.html">Tools</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>