diff options
| author | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:51:50 (GMT) |
|---|---|---|
| committer | Frank Baker <fbaker@hdfgroup.org> | 1998-07-15 04:51:50 (GMT) |
| commit | c8e75d27b018deb862171a153dd640455dbe26fb (patch) | |
| tree | 0056588a00653bd4f6fff761482837baa9396a11 /doc/html/RM_H5E.html | |
| parent | 3e213ecf064638989c816ba3a10b3b6c6307fdad (diff) | |
| download | hdf5-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.html | 361 |
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> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +H5E +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<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> </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> </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> + <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> +<a href="RM_H5.html">H5</a> +<a href="RM_H5A.html">H5A</a> +<a href="RM_H5D.html">H5D</a> +H5E +<a href="RM_H5F.html">H5F</a> +<a href="RM_H5G.html">H5G</a> +<a href="RM_H5P.html">H5P</a> +<a href="RM_H5S.html">H5S</a> +<a href="RM_H5T.html">H5T</a> +<a href="RM_H5Z.html">H5Z</a> +<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> |