diff options
| author | Quincey Koziol <koziol@hdfgroup.org> | 1998-07-08 14:54:54 (GMT) |
|---|---|---|
| committer | Quincey Koziol <koziol@hdfgroup.org> | 1998-07-08 14:54:54 (GMT) |
| commit | bd1e676c521d881b3143829f493a28b5ced1294b (patch) | |
| tree | 69c50f9fe21ce87f293d8617a6bd51b4cc1e0244 /doc/html/Errors.html | |
| parent | 73345095897d9698bb1f2f7df830bf80a56dc65a (diff) | |
| download | hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.zip hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.gz hdf5-bd1e676c521d881b3143829f493a28b5ced1294b.tar.bz2 | |
[svn-r467] Restructuring documentation.
Diffstat (limited to 'doc/html/Errors.html')
| -rw-r--r-- | doc/html/Errors.html | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/doc/html/Errors.html b/doc/html/Errors.html new file mode 100644 index 0000000..4c3637d --- /dev/null +++ b/doc/html/Errors.html @@ -0,0 +1,281 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>The Error Handling Interface (H5E)</title> + </head> + + <body> + <h1>The Error Handling Interface (H5E)</h1> + + <h2>1. Introduction</h2> + + <p>When an error occurs deep within the HDF5 library a record is + pushed onto an error stack and that function returns a failure + indication. Its caller detects the failure, pushes another + record onto the stack, and returns a failure indication. This + continues until the application-called API function returns a + failure indication (a negative integer or null pointer). The + next API function which is called (with a few exceptions) resets + the stack. + + <p>In normal circumstances, an error causes the stack to be + printed on the standard error stream. The first item, number + "#000" is produced by the API function itself and is usually + sufficient to indicate to the application programmer what went + wrong. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: An Error Message</h4></caption> + <tr> + <td> + <p>If an application calls <code>H5Tclose</code> on a + predefined data type then the following message is + printed on the standard error stream. This is a + simple error that has only one component, the API + function; other errors may have many components. + + <p><code><pre> +HDF5-DIAG: Error detected in thread 0. Back trace follows. + #000: H5T.c line 462 in H5Tclose(): predefined data type + major(01): Function argument + minor(05): Bad value + </code></pre> + </td> + </tr> + </table> + </center> + + <p>The error stack can also be printed and manipulated by these + functions, but if an application wishes make explicit calls to + <code>H5Eprint()</code> then the automatic printing should be + turned off to prevent error messages from being displayed twice + (see <code>H5Eset_auto()</code> below). + + <dl> + <dt><code>herr_t H5Eprint (FILE *<em>stream</em>)</code> + <dd>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> + + <br><br> + <dt><code>herr_t H5Eclear (void)</code> + <dd>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>). + </dl> + + <p>Sometimes an application will call a function for the sake of + its return value, fully expecting the function to fail. Under + these conditions, it would be misleading if an error message + were automatically printed. Automatic printing of messages is + controlled by the <code>H5Eset_auto()</code> function: + + <dl> + <dt><code>herr_t H5Eset_auto (herr_t(*<em>func</em>)(void*), + void *<em>client_data</em>)</code> + <dd>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>. + + <br><br> + <dt><code>herr_t H5Eget_auto (herr_t(**<em>func</em>)(void*), + void **<em>client_data</em>)</code> + <dd>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. + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: Error Control</h4></caption> + <tr> + <td> + <p>An application can temporarily turn off error + messages while "probing" a function. + + <p><code><pre> +/* Save old error handler */ +herr_t (*old_func)(void*); +void *old_client_data; +H5Eget_auto(&old_func, &old_client_data); + +/* Turn off error handling */ +H5Eset_auto(NULL, NULL); + +/* Probe. Likely to fail, but that's okay */ +status = H5Fopen (......); + +/* Restore previous error handler */ +H5Eset_auto(old_func, old_client_data); + </code></pre> + + <p>Or automatic printing can be disabled altogether and + error messages can be explicitly printed. + + <p><code><pre> +/* Turn off error handling permanently */ +H5Eset_auto (NULL, NULL); + +/* If failure, print error message */ +if (H5Fopen (....)<0) { + H5Eprint (stderr); + exit (1); +} + </code></pre> + </td> + </tr> + </table> + </center> + + <p>The application is allowed to define an automatic error + traversal function other than the default + <code>H5Eprint()</code>. For instance, one could define a + function that prints a simple, one-line error message to the + standard error stream and then exits. + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: Simple Messages</h4></caption> + <tr> + <td> + <p>The application defines a function to print a simple + error message to the standard error stream. + + <p><code><pre> +herr_t +my_hdf5_error_handler (void *unused) +{ + fprintf (stderr, "An HDF5 error was detected. Bye.\n"); + exit (1); +} + </code></pre> + + <p>The function is installed as the error handler by + saying + + <p><code><pre> +H5Eset_auto (my_hdf5_error_handler, NULL); + </code></pre> + </td> + </tr> + </table> + </center> + + <p>The <code>H5Eprint()</code> function is actually just a wrapper + around the more complex <code>H5Ewalk()</code> function which + traverses an error stack and calls a user-defined function for + each member of the stack. + + <dl> + <dt><code>herr_t H5Ewalk (H5E_direction_t <em>direction</em>, + H5E_walk_t <em>func</em>, void *<em>client_data</em>)</code> + <dd>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</em> 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>. + + <br><br> + <dt><code>typedef herr_t (*H5E_walk_t)(int <em>n</em>, + H5E_error_t *<em>eptr</em>, void + *<em>client_data</em>)</code> + <dd>An error stack traversal callback function takes three + arguments: <em>n</em> is a sequence number beginning at zero + for each traversal, <em>eptr</em> is a pointer to an error + stack member, and <em>client_data</em> is the same pointer + passed to <code>H5Ewalk()</code>. + + <br><br> + <dt><pre><code>typedef struct { + H5E_major_t <em>maj_num</em>; + H5E_minor_t <em>min_num</em>; + const char *<em>func_name</em>; + const char *<em>file_name</em>; + unsigned <em>line</em>; + const char *<em>desc</em>; +} H5E_error_t;</code></pre> + <dd>The <em>maj_num</em> and <em>min_num</em> are major + and minor error numbers, <em>func_name</em> is the name of + the function where the error was detected, + <em>file_name</em> and <em>line</em> locate the error + within the HDF5 library source code, and <em>desc</em> + points to a description of the error. + + <br><br> + <dt><code>const char *H5Eget_major (H5E_major_t <em>num</em>)</code> + <dt><code>const char *H5Eget_minor (H5E_minor_t <em>num</em>)</code> + <dd>These functions take a major or minor error number and + return a constant string which describes the error. If + <em>num</em> is out of range than a string like "Invalid major + error number" is returned. + </dl> + + <p> + <center> + <table border align=center width="100%"> + <caption align=top><h4>Example: H5Ewalk_cb</h4></caption> + <tr> + <td> + <p>This is the implementation of the default error stack + traversal callback. + + <p><code><pre> +herr_t +H5Ewalk_cb(int n, H5E_error_t *err_desc, void *client_data) +{ + FILE *stream = (FILE *)client_data; + const char *maj_str = NULL; + const char *min_str = NULL; + const int indent = 2; + + /* Check arguments */ + assert (err_desc); + if (!client_data) client_data = stderr; + + /* Get descriptions for the major and minor error numbers */ + maj_str = H5Eget_major (err_desc->maj_num); + min_str = H5Eget_minor (err_desc->min_num); + + /* Print error message */ + fprintf (stream, "%*s#%03d: %s line %u in %s(): %s\n", + indent, "", n, err_desc->file_name, err_desc->line, + err_desc->func_name, err_desc->desc); + fprintf (stream, "%*smajor(%02d): %s\n", + indent*2, "", err_desc->maj_num, maj_str); + fprintf (stream, "%*sminor(%02d): %s\n", + indent*2, "", err_desc->min_num, min_str); + + return 0; +} + </code></pre> + </td> + </tr> + </table> + </center> + + + + <hr> + <address><a href="mailto:hdf5dev@ncsa.uiuc.edu">Robb Matzke</a></address> +<!-- Created: Fri Feb 27 23:42:52 EST 1998 --> +<!-- hhmts start --> +Last modified: Wed Mar 4 10:06:17 EST 1998 +<!-- hhmts end --> + </body> +</html> |