diff options
Diffstat (limited to 'doc/html/Errors.html')
| -rw-r--r-- | doc/html/Errors.html | 386 |
1 files changed, 0 insertions, 386 deletions
diff --git a/doc/html/Errors.html b/doc/html/Errors.html deleted file mode 100644 index 29a00ba..0000000 --- a/doc/html/Errors.html +++ /dev/null @@ -1,386 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> - <head> - <title>Error Handling Interface (H5E)</title> - -<!-- #BeginLibraryItem "/ed_libs/styles_UG.lbi" --> -<!-- - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Copyright by the Board of Trustees of the University of Illinois. * - * All rights reserved. * - * * - * This file is part of HDF5. The full HDF5 copyright notice, including * - * terms governing use, modification, and redistribution, is contained in * - * the files COPYING and Copyright.html. COPYING can be found at the root * - * of the source code distribution tree; Copyright.html can be found at the * - * root level of an installed copy of the electronic HDF5 document set and * - * is linked from the top-level documents page. It can also be found at * - * http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have * - * access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - --> - -<link href="ed_styles/UGelect.css" rel="stylesheet" type="text/css"> -<!-- #EndLibraryItem --></head> - - <body bgcolor="#FFFFFF"> - - -<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="index.html">HDF5 documents and links</a> <br> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> -</td></tr> -</table> -</center> -<hr> -<!-- #EndLibraryItem --><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. - - <h2>2. Error Handling Operations</h2> - - <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 datatype 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 datatype - 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</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>. - - <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> - - -<!-- #BeginLibraryItem "/ed_libs/NavBar_UG.lbi" --><hr> -<center> -<table border=0 width=98%> -<tr><td valign=top align=left> - <a href="index.html">HDF5 documents and links</a> <br> - <a href="H5.intro.html">Introduction to HDF5</a> <br> - <a href="RM_H5Front.html">HDF5 Reference Manual</a> <br> - <a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User's Guide for Release 1.6</a> <br> - <!-- - <a href="Glossary.html">Glossary</a><br> - --> -</td> -<td valign=top align=right> - And in this document, the - <a href="H5.user.html"><strong>HDF5 User's Guide from Release 1.4.5:</strong></a> - <br> - <a href="Files.html">Files</a> - <a href="Datasets.html">Datasets</a> - <a href="Datatypes.html">Datatypes</a> - <a href="Dataspaces.html">Dataspaces</a> - <a href="Groups.html">Groups</a> - <br> - <a href="References.html">References</a> - <a href="Attributes.html">Attributes</a> - <a href="Properties.html">Property Lists</a> - <a href="Errors.html">Error Handling</a> - <br> - <a href="Filters.html">Filters</a> - <a href="Caching.html">Caching</a> - <a href="Chunking.html">Chunking</a> - <a href="MountingFiles.html">Mounting Files</a> - <br> - <a href="Performance.html">Performance</a> - <a href="Debugging.html">Debugging</a> - <a href="Environment.html">Environment</a> - <a href="ddl.html">DDL</a> -</td></tr> -</table> -</center> -<hr> -<!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address> -<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a> -<br> -Describes HDF5 Release 1.4.5, February 2003 -</address><!-- #EndLibraryItem --><!-- Created: Fri Feb 27 23:42:52 EST 1998 --> -<!-- hhmts start --> -Last modified: 13 December 1999 -<!-- hhmts end --> - -</body> -</html> |