[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.
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
parent: 4322bfe90ab7de7245ff770155867fa5da78147c (diff)
download: hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.zip
hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.tar.gz
hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.tar.bz2
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>
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
parent	4322bfe90ab7de7245ff770155867fa5da78147c (diff)
download	hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.zip hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.tar.gz hdf5-e455040749ca1d47fb218b9bb35d78247fb9561d.tar.bz2