mirror of
https://github.com/HDFGroup/hdf5.git
synced 2025-02-11 16:01:00 +08:00
82fb21b613
been checked into "HDF5 Development" branch. General ======= Various "copy edit" types of repairs. Revisions to document cross-linking. Added structural links tying all docs together (banners at top and bottom of documents, similar to Reference Manual banners of the Beta release). Set background color to white in all documents. NCSAfooterlogo.gif hdf2.jpg New image files to make the documents more self-contained (i.e., to prevent loading images from NCSA and HDF home servers). index.html Redesigned to isolate links external to the installation in a single location. Intro to HDF5 ============= H5.intro.html Fixed banner linking Intro to other docs. Set all URLs to be relative within the distribution; nothing points back to the HDF server. Updates to "Limits of the Current Release" and "Changes in the Current Release." HDF5 User's Guide ================= Changed several User Guide section titles such that all sections that are primarily about a particular interface are now titled in the format "The xxxxx Interface (H5x)". H5.user.html Commented out links to developer docs since they are marked in MANIFEST as not being for distribution in the release. Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. Datatypes.html Removed the sentence "I'm deferring definition until later since they're probably not as important as the other data types." from Section 3.3, "Properties of Date and Time Atomic Types." Added info regarding 'char' versus 'string' datatypes. Added as Section 3.7, "Character and String Datatype Issues." References.html Commented out substantial material (at end of document) from References planning document that is not appropriate for the User Guide but that is worth keeping around. Groups.html Final edits from elimination of "current working group." HDF5 Reference Manual ===================== Removed "Draft" from the <title>__</title> lines. RM_H5Front.html Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. RM_H5F.html RM_H5P.html Add file mounting information.
545 lines
18 KiB
HTML
545 lines
18 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Debugging HDF5 Applications</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</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">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
Debugging
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<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%">
|
|
<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>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%">
|
|
<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.
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</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">HDF5 User's Guide</a>:
|
|
<a href="Files.html">Files</a>
|
|
<br>
|
|
<a href="Datasets.html">Datasets</a>
|
|
<a href="Datatypes.html">Data Types</a>
|
|
<a href="Dataspaces.html">Dataspaces</a>
|
|
<a href="Groups.html">Groups</a>
|
|
<a href="References.html">References</a>
|
|
<br>
|
|
<a href="Attributes.html">Attributes</a>
|
|
<a href="Properties.html">Property Lists</a>
|
|
<a href="Errors.html">Error Handling</a>
|
|
<a href="Filters.html">Filters</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<br>
|
|
<a href="Chunking.html">Chunking</a>
|
|
Debugging
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
<a href="Ragged.html">Ragged Arrays</a>
|
|
<!--
|
|
<hr>
|
|
And in this document, the
|
|
<a href="H5.user.html">HDF5 User's Guide</a>:
|
|
<a href="Attributes.html">H5A</a>
|
|
<a href="Datasets.html">H5D</a>
|
|
<a href="Errors.html">H5E</a>
|
|
<a href="Files.html">H5F</a>
|
|
<a href="Groups.html">H5G</a>
|
|
<a href="Properties.html">H5P</a>
|
|
<a href="References.html">H5R & H5I</a>
|
|
<a href="Ragged.html">H5RA</a>
|
|
<a href="Dataspaces.html">H5S</a>
|
|
<a href="Datatypes.html">H5T</a>
|
|
<a href="Filters.html">H5Z</a>
|
|
<a href="Caching.html">Caching</a>
|
|
<a href="Chunking.html">Chunking</a>
|
|
<a href="Debugging.html">Debugging</a>
|
|
<a href="Environment.html">Environment</a>
|
|
<a href="ddl.html">DDL</a>
|
|
-->
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
|
|
|
|
<!--
|
|
<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: Thu Aug 20 10:43:42 PDT 1998
|
|
-->
|
|
<!-- hhmts end -->
|
|
|
|
<hr>
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
</address>
|
|
|
|
Last modified: 30 October 1998
|
|
|
|
</body>
|
|
</html>
|