diff options
| author | Elena Pourmal <epourmal@hdfgroup.org> | 1998-07-08 22:28:21 (GMT) |
|---|---|---|
| committer | Elena Pourmal <epourmal@hdfgroup.org> | 1998-07-08 22:28:21 (GMT) |
| commit | 49f626b81f028a09d5c287156120a5d405008335 (patch) | |
| tree | ee0178875371da97373cb5c08a2fa7a276f94ccd /doc/src/RM_H5E.html | |
| parent | 2f1f2ac4e44efef28ac7b7edaf4f9470b866c9fc (diff) | |
| download | hdf5-49f626b81f028a09d5c287156120a5d405008335.zip hdf5-49f626b81f028a09d5c287156120a5d405008335.tar.gz hdf5-49f626b81f028a09d5c287156120a5d405008335.tar.bz2 | |
[svn-r475] HDF5 Reference Manual files.
Main file is RM_H5Front.html. Created from the Alpha1 Ref. Manual, Alpha1
User's Guide Documents and the Alpha2 Source Code.
Diffstat (limited to 'doc/src/RM_H5E.html')
| -rw-r--r-- | doc/src/RM_H5E.html | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html new file mode 100644 index 0000000..0065e90 --- /dev/null +++ b/doc/src/RM_H5E.html @@ -0,0 +1,377 @@ +<html> +<head><title> +HDF5/H5E Draft API Specification +</title></head> + +<body> + +<center> +<h1>H5E: Error Interface</h1> +</center> + +<h2>Error API Functions</h2> + +These functions provide error handling capabilities in the HDF5 environment. +<p> +Provides error handling in the form of a stack. The FUNC_ENTER() macro +clears the error stack whenever an API 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 H5Eprint()) +do not clear the error stack. Otherwise, any function which +doesn't have an underscore immediately after the package name +will clear the error stack. For instance, H5Fopen() clears +the error stack while H5F_open() 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. + +<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> + + +<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>SC: H5Eset_auto 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> + The default values before this function is called are + H5Eprint() with client data being the standard error stream, + stderr. + <p> + Automatic stack traversal is always in the H5E_WALK_DOWNWARD + direction. + <p> + UG: 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>. + <p> + <b>UG signature line reads</b> + <br><code>herr_t H5Eset_auto (herr_t(*<em>func</em>)(void*), + void *<em>client_data</em>)</code>. + <br><b>The UG signature line for H5Eget_auto reads similarly.</b> + <p> +<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>SC: H5Eget_auto returns the current settings for the automatic error stack + traversal function and its data. Either (or both) arguments + may be null in which case the value is not returned. + <p> + UG: 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. +<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>SC: H5Eclear clears the error stack for the current thread. + <p> + This function can fail if there are problems initializing the library. + <p> + UG: 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>). +<dt><strong>Parameters:</strong> + <dl> + <dt><em>paramtype</em> <code>param</code> + <dd>xxx + <dt><i>Should this say "None"?</i> + </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>SC: H5Eprint prints the error stack in some default way. This is just a + convenience function for H5Ewalk() with a function that + prints error messages. Users are encouraged to write there + own more specific error handlers. + <p> + UG: 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> +<dt><strong>Parameters:</strong> + <dl> + <dt><em>FILE *</em> <code>stream</code> + <dd>xxx + </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>SC: <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. + It's 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. + <p> + UG: 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>. +<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 H5Ewalk() function. This function is called + also by H5Eprint(). 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> + ERR_DESC is an error description. It contains all the + information about a particular error. + <p> + CLIENT_DATA is the same pointer that was passed as the + CLIENT_DATA argument of H5Ewalk(). 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 <code>stderr</code> 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 a major error. +<dt><strong>Description:</strong> + <dd>Given a major error number, H5Eget_major 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 pointer to a character string if successful. + Otherwise returns a pointer to "Invalid major error number". + <br> + <i> ...or how about... </i> + <br> + Returns a pointer to a character string describing the error if successful. + Otherwise returns a pointer to "Invalid major error number". + <br> + <i> ...or ... </i> + <br> + 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 a minor error. +<dt><strong>Description:</strong> + <dd>Given a minor error number, H5Eget_minor 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 pointer to a character string if successful. + Otherwise returns a pointer to "Invalid minor error number". + <br> + <i> ...or how about... </i> + <br> + Returns a pointer to a character string describing the error if successful. + Otherwise returns a pointer to "Invalid minor error number". + <br> + <i> ...or ... </i> + <br> + Returns a character string describing the error if successful. + Otherwise returns "Invalid minor error number." +</dl> + + +<hr> + +<address> +<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a> +<br> +<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a> + +<br> +Last modified: 6 July 1998 + +</body> +</html> |