diff options
Diffstat (limited to 'doc/html/Debugging.html')
| -rw-r--r-- | doc/html/Debugging.html | 516 |
1 files changed, 0 insertions, 516 deletions
diff --git a/doc/html/Debugging.html b/doc/html/Debugging.html deleted file mode 100644 index d04cf27..0000000 --- a/doc/html/Debugging.html +++ /dev/null @@ -1,516 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> - <head> - <title>Debugging HDF5 Applications</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>Debugging HDF5 Applications</h1> - - <h2>Introduction</h2> - - <p>The HDF5 library contains a number of debugging features to - make programmers' lives easier including the ability to print - detailed error messages, check invariant conditions, display - timings and other statistics, and trace API function calls and - return values. - - <dl> - <dt><b>Error Messages</b> - <dd>Error messages are normally displayed automatically on the - standard error stream and include a stack trace of the library - including file names, line numbers, and function names. The - application has complete control over how error messages are - displayed and can disable the display on a permanent or - temporary basis. Refer to the documentation for the H5E error - handling package. - - <br><br> - <dt><b>Invariant Conditions</b> - <dd>Unless <code>NDEBUG</code> is defined during compiling, the - library will include code to verify that invariant conditions - have the expected values. When a problem is detected the - library will display the file and line number within the - library and the invariant condition that failed. A core dump - may be generated for post mortem debugging. The code to - perform these checks can be included on a per-package bases. - - <br><br> - <dt><b>Timings and Statistics</b> - <dd>The library can be configured to accumulate certain - statistics about things like cache performance, datatype - conversion, data space conversion, and data filters. The code - is included on a per-package basis and enabled at runtime by - an environment variable. - - <br><br> - <dt><b>API Tracing</b> - <dd>All API calls made by an application can be displayed and - include formal argument names and actual values and the - function return value. This code is also conditionally - included at compile time and enabled at runtime. - </dl> - - <p>The statistics and tracing can be displayed on any output - stream (including streams opened by the shell) with output from - different packages even going to different streams. - - <h2>Error Messages</h2> - - <p>By default any API function that fails will print an error - stack to the standard error stream. - - <p> - <center> - <table border align=center width="100%"> - <tr> - <td> - <p><code><pre> - -HDF5-DIAG: Error detected in thread 0. Back trace follows. - #000: H5F.c line 1245 in H5Fopen(): unable to open file - major(04): File interface - minor(10): Unable to open file - #001: H5F.c line 846 in H5F_open(): file does not exist - major(04): File interface - minor(10): Unable to open file - </code></pre> - </td> - </tr> - </table> - </center> - - <p>The error handling package (H5E) is described - <a href="Errors.html">elsewhere</a>. - - <h2>Invariant Conditions</h2> - - <p>To include checks for invariant conditions the library should - be configured with <code>--disable-production</code>, the - default for versions before 1.2. The library designers have made - every attempt to handle error conditions gracefully but an - invariant condition assertion may fail in certain cases. The - output from a failure usually looks something like this: - - <p> - <center> - <table border align=center width="100%"> - <tr> - <td> - <p><code><pre> - -Assertion failed: H5.c:123: i<NELMTS(H5_debug_g) -IOT Trap, core dumped. - </code></pre> - </td> - </tr> - </table> - </center> - - <h2>Timings and Statistics</h2> - - <p>Code to accumulate statistics is included at compile time by - using the <code>--enable-debug</code> configure switch. The - switch can be followed by an equal sign and a comma-separated - list of package names or else a default list is used. - - <p> - <center> - <table border align=center width="80%"> - <tr> - <th>Name</th> - <th>Default</th> - <th>Description</th> - </tr> - <tr> - <td align=center>a</td> - <td align=center>No</td> - <td>Attributes</td> - </tr> - <tr> - <td align=center>ac</td> - <td align=center>Yes</td> - <td>Meta data cache</td> - </tr> - <tr> - <td align=center>b</td> - <td align=center>Yes</td> - <td>B-Trees</td> - </tr> - <tr> - <td align=center>d</td> - <td align=center>Yes</td> - <td>Datasets</td> - </tr> - <tr> - <td align=center>e</td> - <td align=center>Yes</td> - <td>Error handling</td> - </tr> - <tr> - <td align=center>f</td> - <td align=center>Yes</td> - <td>Files</td> - </tr> - <tr> - <td align=center>g</td> - <td align=center>Yes</td> - <td>Groups</td> - </tr> - <tr> - <td align=center>hg</td> - <td align=center>Yes</td> - <td>Global heap</td> - </tr> - <tr> - <td align=center>hl</td> - <td align=center>No</td> - <td>Local heaps</td> - </tr> - <tr> - <td align=center>i</td> - <td align=center>Yes</td> - <td>Interface abstraction</td> - </tr> - <tr> - <td align=center>mf</td> - <td align=center>No</td> - <td>File memory management</td> - </tr> - <tr> - <td align=center>mm</td> - <td align=center>Yes</td> - <td>Library memory managment</td> - </tr> - <tr> - <td align=center>o</td> - <td align=center>No</td> - <td>Object headers and messages</td> - </tr> - <tr> - <td align=center>p</td> - <td align=center>Yes</td> - <td>Property lists</td> - </tr> - <tr> - <td align=center>s</td> - <td align=center>Yes</td> - <td>Data spaces</td> - </tr> - <tr> - <td align=center>t</td> - <td align=center>Yes</td> - <td>Datatypes</td> - </tr> - <tr> - <td align=center>v</td> - <td align=center>Yes</td> - <td>Vectors</td> - </tr> - <tr> - <td align=center>z</td> - <td align=center>Yes</td> - <td>Raw data filters</td> - </tr> - </table> - </center> - - <p>In addition to including the code at compile time the - application must enable each package at runtime. This is done - by listing the package names in the <code>HDF5_DEBUG</code> - environment variable. That variable may also contain file - descriptor numbers (the default is `2') which control the output - for all following packages up to the next file number. The - word <code>all</code> refers to all packages. Any word my be - preceded by a minus sign to turn debugging off for the package. - - <p> - <center> - <table border align=center width="100%"> - <caption align=top><b>Sample debug specifications</b></caption> - <tr valign=top> - <td><code>all</code></td> - <td>This causes debugging output from all packages to be - sent to the standard error stream.</td> - </tr> - <tr valign=top> - <td><code>all -t -s</code></td> - <td>Debugging output for all packages except datatypes - and data spaces will appear on the standard error - stream.</td> - </tr> - <tr valign=top> - <td><code>-all ac 255 t,s</code></td> - <td>This disables all debugging even if the default was to - debug something, then output from the meta data cache is - send to the standard error stream and output from data - types and spaces is sent to file descriptor 255 which - should be redirected by the shell.</td> - </tr> - </table> - </center> - - <p>The components of the <code>HDF5_DEBUG</code> value may be - separated by any non-lowercase letter. - - <h2>API Tracing</h2> - - <p>The HDF5 library can trace API calls by printing the - function name, the argument names and their values, and the - return value. Some people like to see lots of output during - program execution instead of using a good symbolic debugger, and - this feature is intended for their consumption. For example, - the output from <code>h5ls foo</code> after turning on tracing, - includes: - - <p> - <center> - <table border align=center width="100%"> - <tr> - <td> - <code><pre> - -H5Tcopy(type=184549388) = 184549419 (type); -H5Tcopy(type=184549392) = 184549424 (type); -H5Tlock(type=184549424) = SUCCEED; -H5Tcopy(type=184549393) = 184549425 (type); -H5Tlock(type=184549425) = SUCCEED; -H5Fopen(filename="foo", flags=0, access=H5P_DEFAULT) = FAIL; -HDF5-DIAG: Error detected in thread 0. Back trace follows. - #000: H5F.c line 1245 in H5Fopen(): unable to open file - major(04): File interface - minor(10): Unable to open file - #001: H5F.c line 846 in H5F_open(): file does not exist - major(04): File interface - minor(10): Unable to open file - </pre></code> - </td> - </tr> - </table> - </center> - - <p>The code that performs the tracing must be included in the - library by specifying the <code>--enable-trace</code> - configuration switch (the default for versions before 1.2). Then - the word <code>trace</code> must appear in the value of the - <code>HDF5_DEBUG</code> variable. The output will appear on the - last file descriptor before the word <code>trace</code> or two - (standard error) by default. - - <p> - <center> - <table border align=center width="100%"> - <tr> - <td>To display the trace on the standard error stream: - <code><pre> -$ env HDF5_DEBUG=trace a.out - </pre></code> - </td> - </tr> - <tr> - <td>To send the trace to a file: - <code><pre> -$ env HDF5_DEBUG="55 trace" a.out 55>trace-output - </pre></code> - </td> - </tr> - </table> - </center> - - <h3>Performance</h3> - - <p>If the library was not configured for tracing then there is no - unnecessary overhead since all tracing code is excluded. - However, if tracing is enabled but not used there is a small - penalty. First, code size is larger because of extra - statically-declared character strings used to store argument - types and names and extra auto variable pointer in each - function. Also, execution is slower because each function sets - and tests a local variable and each API function calls the - <code>H5_trace()</code> function. - - <p>If tracing is enabled and turned on then the penalties from the - previous paragraph apply plus the time required to format each - line of tracing information. There is also an extra call to - H5_trace() for each API function to print the return value. - - <h3>Safety</h3> - - <p>The tracing mechanism is invoked for each API function before - arguments are checked for validity. If bad arguments are passed - to an API function it could result in a segmentation fault. - However, the tracing output is line-buffered so all previous - output will appear. - - <h3>Completeness</h3> - - <p>There are two API functions that don't participate in - tracing. They are <code>H5Eprint()</code> and - <code>H5Eprint_cb()</code> because their participation would - mess up output during automatic error reporting. - - <p>On the other hand, a number of API functions are called during - library initialization and they print tracing information. - - <h3>Implementation</h3> - - <p>For those interested in the implementation here is a - description. Each API function should have a call to one of the - <code>H5TRACE()</code> macros immediately after the - <code>FUNC_ENTER()</code> macro. The first argument is the - return type encoded as a string. The second argument is the - types of all the function arguments encoded as a string. The - remaining arguments are the function arguments. This macro was - designed to be as terse and unobtrousive as possible. - - <p>In order to keep the <code>H5TRACE()</code> calls synchronized - with the source code we've written a perl script which gets - called automatically just before Makefile dependencies are - calculated for the file. However, this only works when one is - using GNU make. To reinstrument the tracing explicitly, invoke - the <code>trace</code> program from the hdf5 bin directory with - the names of the source files that need to be updated. If any - file needs to be modified then a backup is created by appending - a tilde to the file name. - - <p> - <center> - <table border align=center width="100%"> - <caption align=top><b>Explicit Instrumentation</b></caption> - <tr> - <td> - <code><pre> - -$ ../bin/trace *.c -H5E.c: in function `H5Ewalk_cb': -H5E.c:336: warning: trace info was not inserted - </pre></code> - </td> - </tr> - </table> - </center> - - <p>Note: The warning message is the result of a comment of the - form <code>/*NO TRACE*/</code> somewhere in the function - body. Tracing information will not be updated or inserted if - such a comment exists. - - <p>Error messages have the same format as a compiler so that they - can be parsed from program development environments like - Emacs. Any function which generates an error will not be - modified.</p> - - -<!-- #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: Wed Jun 17 12:29:12 EDT 1998 --> -<!-- hhmts start --> -Last modified: 13 December 1999 -<!-- hhmts end --> - - -</body> -</html> |