diff options
Diffstat (limited to 'doc/src/RM_H5E.html')
| -rw-r--r-- | doc/src/RM_H5E.html | 212 |
1 files changed, 83 insertions, 129 deletions
diff --git a/doc/src/RM_H5E.html b/doc/src/RM_H5E.html index 0065e90..4c70b6a 100644 --- a/doc/src/RM_H5E.html +++ b/doc/src/RM_H5E.html @@ -12,30 +12,6 @@ HDF5/H5E Draft API Specification <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> @@ -58,6 +34,32 @@ errors within the H5E package. </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> @@ -69,34 +71,19 @@ errors within the H5E package. <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), + <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> - 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> + 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> @@ -121,14 +108,10 @@ errors within the H5E package. <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. + <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> @@ -151,19 +134,16 @@ errors within the H5E package. <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. + <dd><code>H5Eclear</code> clears the error stack for the current thread. <p> - This function can fail if there are problems initializing the library. + The stack is also cleared whenever an API function is called, + with certain exceptions (for instance, <code>H5Eprint()</code>). <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>). + <code>H5Eclear</code> can fail if there are problems initializing + the library. <dt><strong>Parameters:</strong> <dl> - <dt><em>paramtype</em> <code>param</code> - <dd>xxx - <dt><i>Should this say "None"?</i> + <dt>None </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -179,18 +159,19 @@ errors within the H5E package. <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. + <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> - 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> + <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>xxx + <dd>File pointer, or stderr if NULL. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -210,7 +191,7 @@ errors within the H5E package. <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 + <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 @@ -222,22 +203,13 @@ errors within the H5E package. 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 + 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. - <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>. + <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> @@ -265,26 +237,26 @@ errors within the H5E package. <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. + <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. + 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). + <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 + <code>err_desc</code> 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). + <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> @@ -293,7 +265,7 @@ errors within the H5E package. <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. + <dd>A file pointer, or stderr if null. </dl> <dt><strong>Returns:</strong> <dd>Returns SUCCEED (0) if successful; @@ -307,27 +279,18 @@ errors within the H5E package. <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. + <dd>Returns a character string describing an error specified by a + major error number. <dt><strong>Description:</strong> - <dd>Given a major error number, H5Eget_major returns a constant character string - that describes the error. + <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 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. + <dd> Returns a character string describing the error if successful. Otherwise returns "Invalid major error number." </dl> @@ -338,27 +301,18 @@ errors within the H5E package. <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. + <dd>Returns a character string describing an error specified by a + minor error number. <dt><strong>Description:</strong> - <dd>Given a minor error number, H5Eget_minor returns a constant character string - that describes the error. + <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 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. + <dd> Returns a character string describing the error if successful. Otherwise returns "Invalid minor error number." </dl> |