summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorRobb Matzke <matzke@llnl.gov>1998-08-19 22:46:31 (GMT)
committerRobb Matzke <matzke@llnl.gov>1998-08-19 22:46:31 (GMT)
commite455040749ca1d47fb218b9bb35d78247fb9561d (patch)
tree2d26f2ae1fea1ff393f00eb36e3f2155dec690b6 /doc
parent4322bfe90ab7de7245ff770155867fa5da78147c (diff)
downloadhdf5-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')
-rw-r--r--doc/html/Debugging.html408
-rw-r--r--doc/html/H5.user.html4
-rw-r--r--doc/html/tracing.html193
3 files changed, 410 insertions, 195 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&lt;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>
diff --git a/doc/html/H5.user.html b/doc/html/H5.user.html
index c090922..a7b59e8 100644
--- a/doc/html/H5.user.html
+++ b/doc/html/H5.user.html
@@ -32,7 +32,7 @@
A guide to the H5Z interface.
<li><a href="Caching.html">Caching</a> -
A guide for meta and raw data caching.
- <li><a href="tracing.html">API Tracing</a> -
+ <li><a href="Debugging.html">Debugging</a> -
A guide to debugging HDF5 API calls.
</ul>
@@ -66,7 +66,7 @@
<address><a href="mailto:koziol@ncsa.uiuc.edu">Quincey Koziol</a></address>
<address><a href="mailto:matzke@llnl.gov">Robb Matzke</a></address>
<!-- hhmts start -->
-Last modified: Wed Aug 5 17:02:57 EDT 1998
+Last modified: Wed Aug 19 15:29:11 PDT 1998
<!-- hhmts end -->
</body>
diff --git a/doc/html/tracing.html b/doc/html/tracing.html
deleted file mode 100644
index 8d3c677..0000000
--- a/doc/html/tracing.html
+++ /dev/null
@@ -1,193 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
-<html>
- <head>
- <title>API Tracing</title>
- </head>
-
- <body>
- <h1>API Tracing</h1>
-
- <h2>Introduction</h2>
-
- <p>The HDF5 library is now able to 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>
-
- <h2>Configuation</h2>
-
- <p>This all happens with some magic in the configuration script,
- the makefiles, and macros. First, from the end-user point of
- view, the library must be configured with the
- <code>--enable-trace</code> switch (the default;
- `--disable-trace' is the alternative). This causes the library
- to include the support necessary for API tracing.
-
- <p>
- <center>
- <table border align=center width="100%">
- <caption align=top><b>Configuration</b></caption>
- <tr>
- <td>
- <code><pre>
-$ make distclean
-$ sh configure --enable-trace
-$ make
- </pre></code>
- </td>
- </tr>
- </table>
- </center>
-
- <h2>Execution</h2>
-
- <p>In order to actually get tracing output one must turn tracing
- on and specify a file descriptor where the tracing output should
- be written. This is done by assigning a file descriptor number
- to the <code>HDF5_TRACE</code> environment variable.
-
- <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>
-$ export HDF5_TRACE=2
-$ a.out
- </pre></code>
- </td>
- </tr>
- <tr>
- <td>To send the trace to a file:
- <code><pre>
-$ export HDF5_TRACE=255
-$ a.out 255>trace-output
- </pre></code>
- </td>
- </tr>
- </table>
- </center>
-
- <h2>Performance</h2>
-
- <p>If the library was not configured for tracing then there is no
- unnecessary overhead since all tracing code is
- excluded.
-
- <p>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.
-
- <h2>Safety</h2>
-
- <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.
-
- <h2>Completeness</h2>
-
- <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.
-
- <h2>Implementation</h2>
-
- <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 Jul 8 14:07:23 EDT 1998
-<!-- hhmts end -->
- </body>
-</html>
generated by cgit v0.12 at 2024-07-16 19:07:48 (GMT)