diff options
| author | Robb Matzke <matzke@llnl.gov> | 1998-08-19 22:46:31 (GMT) |
|---|---|---|
| committer | Robb Matzke <matzke@llnl.gov> | 1998-08-19 22:46:31 (GMT) |
| commit | e455040749ca1d47fb218b9bb35d78247fb9561d (patch) | |
| tree | 2d26f2ae1fea1ff393f00eb36e3f2155dec690b6 /doc/html/Debugging.html | |
| parent | 4322bfe90ab7de7245ff770155867fa5da78147c (diff) | |
| download | hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.zip hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.tar.gz hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.tar.bz2 | |
[svn-r606] Debugging can be enabled/disabled at runtime though code is still
conditionally included at compile time. Tracing and debugging share
the same environment variable. All is documented in Debugging.html.
Diffstat (limited to 'doc/html/Debugging.html')
| -rw-r--r-- | doc/html/Debugging.html | 408 |
1 files changed, 408 insertions, 0 deletions
diff --git a/doc/html/Debugging.html b/doc/html/Debugging.html new file mode 100644 index 0000000..8c0c4cc --- /dev/null +++ b/doc/html/Debugging.html @@ -0,0 +1,408 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> + <head> + <title>Debugging HDF5 Applications</title> + </head> + + <body> + <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, data type + 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%"> + <caption align=top><h4>Example: An Error Message</h4></caption> + <tr> + <td> + <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 handling package (H5E) is described + <a href="Errors.html">here</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%"> + <caption align=top><h4>Example: A Failed Assertion</h4></caption> + <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>Data types</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 data types + 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%"> + <caption align=top><b>Sample Output</b></caption> + <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%"> + <caption align=top><b>Execution Examples</b></caption> + <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. + + + <hr> + <address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address> +<!-- Created: Wed Jun 17 12:29:12 EDT 1998 --> +<!-- hhmts start --> +Last modified: Wed Aug 19 15:21:35 PDT 1998 +<!-- hhmts end --> + </body> +</html> |