diff options
| author | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
|---|---|---|
| committer | byrnHDF <byrnHDF@users.noreply.github.com> | 2023-11-16 13:49:28 (GMT) |
| commit | 4f20d880c97be1249f8d89ced95f72836dbf3ee0 (patch) | |
| tree | 30d8dcb282134b7126b092796f2be00d2d97bd3c /develop/_a_p_p_d_b_g.html | |
| parent | 4e7e457497c948b41c8b0065225875bf10cdf9d4 (diff) | |
| download | hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.zip hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.gz hdf5-4f20d880c97be1249f8d89ced95f72836dbf3ee0.tar.bz2 | |
deploy: ef39882fa1e13740d2530c7a0637bd1f1a822b68
Diffstat (limited to 'develop/_a_p_p_d_b_g.html')
| -rw-r--r-- | develop/_a_p_p_d_b_g.html | 510 |
1 files changed, 510 insertions, 0 deletions
diff --git a/develop/_a_p_p_d_b_g.html b/develop/_a_p_p_d_b_g.html new file mode 100644 index 0000000..1a1f4de --- /dev/null +++ b/develop/_a_p_p_d_b_g.html @@ -0,0 +1,510 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> +<meta http-equiv="X-UA-Compatible" content="IE=9"/> +<meta name="generator" content="Doxygen 1.9.1"/> +<meta name="viewport" content="width=device-width, initial-scale=1"/> +<title>HDF5: Debugging HDF5 Applications</title> +<link href="tabs.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="jquery.js"></script> +<script type="text/javascript" src="dynsections.js"></script> +<link href="navtree.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="resize.js"></script> +<script type="text/javascript" src="navtreedata.js"></script> +<script type="text/javascript" src="navtree.js"></script> +<link href="search/search.css" rel="stylesheet" type="text/css"/> +<script type="text/javascript" src="search/searchdata.js"></script> +<script type="text/javascript" src="search/search.js"></script> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ + $(document).ready(function() { init_search(); }); +/* @license-end */ +</script> +<link href="doxygen.css" rel="stylesheet" type="text/css" /> +<link href="hdf5doxy.css" rel="stylesheet" type="text/css"> +<!-- <link href="hdf5doxy.css" rel="stylesheet" type="text/css"/> + --> +<script type="text/javascript" src="hdf5_navtree_hacks.js"></script> +</head> +<body> +<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Please, help us to better serve our user community by answering the following short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div> +<div id="top"><!-- do not remove this div, it is closed by doxygen! --> +<div id="titlearea"> +<table cellspacing="0" cellpadding="0"> + <tbody> + <tr style="height: 56px;"> + <td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td> + <td id="projectalign" style="padding-left: 0.5em;"> + <div id="projectname"><a href="https://www.hdfgroup.org">HDF5</a> +  <span id="projectnumber">1.15.0.ef39882</span> + </div> + <div id="projectbrief">API Reference</div> + </td> + <td> <div id="MSearchBox" class="MSearchBoxInactive"> + <span class="left"> + <img id="MSearchSelect" src="search/mag_sel.svg" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + alt=""/> + <input type="text" id="MSearchField" value="Search" accesskey="S" + onfocus="searchBox.OnSearchFieldFocus(true)" + onblur="searchBox.OnSearchFieldFocus(false)" + onkeyup="searchBox.OnSearchFieldChange(event)"/> + </span><span class="right"> + <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a> + </span> + </div> +</td> + </tr> + </tbody> +</table> +</div> +<!-- end header part --> +<!-- Generated by Doxygen 1.9.1 --> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); +/* @license-end */ +</script> +</div><!-- top --> +<div id="side-nav" class="ui-resizable side-nav-resizable"> + <div id="nav-tree"> + <div id="nav-tree-contents"> + <div id="nav-sync" class="sync"></div> + </div> + </div> + <div id="splitbar" style="-moz-user-select:none;" + class="ui-resizable-handle"> + </div> +</div> +<script type="text/javascript"> +/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ +$(document).ready(function(){initNavTree('_a_p_p_d_b_g.html',''); initResizable(); }); +/* @license-end */ +</script> +<div id="doc-content"> +<!-- window showing the filter options --> +<div id="MSearchSelectWindow" + onmouseover="return searchBox.OnSearchSelectShow()" + onmouseout="return searchBox.OnSearchSelectHide()" + onkeydown="return searchBox.OnSearchSelectKey(event)"> +</div> + +<!-- iframe showing the search results (closed by default) --> +<div id="MSearchResultsWindow"> +<iframe src="javascript:void(0)" frameborder="0" + name="MSearchResults" id="MSearchResults"> +</iframe> +</div> + +<div class="PageDoc"><div class="header"> + <div class="headertitle"> +<div class="title">Debugging HDF5 Applications </div> </div> +</div><!--header--> +<div class="contents"> +<div class="textblock"><html> + <head> + <title>Debugging HDF5 Applications</title> + + <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. + + </p><dl> + <dt><b>Error Messages</b> + </dt><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> + </dd><dt><b>Invariant Conditions</b> + </dt><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> + </dd><dt><b>Timings and Statistics</b> + </dt><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> + </dd><dt><b>API Tracing</b> + </dt><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. + </dd></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. + + </p><h2>Error Messages</h2> + + <p>By default any API function that fails will print an error + stack to the standard error stream. + + </p><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <p><code></code></p><pre><code> +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> + </tbody></table> + </center> + + <p>The error handling package (H5E) is described + <a href="./group___h5_e.html">elsewhere</a>. + + </p><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><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><tr> + <td> + <p><code></code></p><pre><code> +Assertion failed: H5.c:123: i<NELMTS(H5_debug_g) +IOT Trap, core dumped. + </code></pre> + </td> + </tr> + </tbody></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><p> + </p><center> + <table border="" align="center" width="80%"> + <tbody><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 management</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> + </tbody></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><p> + </p><center> + <table border="" align="center" width="100%"> + <caption align="top"><b>Sample debug specifications</b></caption> + <tbody><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> + </tbody></table> + </center> + + <p>The components of the <code>HDF5_DEBUG</code> value may be + separated by any non-lowercase letter. + + </p><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><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><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> + </tbody></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><p> + </p><center> + <table border="" align="center" width="100%"> + <tbody><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> + </tbody></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><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. + + </p><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. + + </p><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><p>On the other hand, a number of API functions are called during + library initialization and they print tracing information. + + </p><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><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><p> + </p><center> + <table border="" align="center" width="100%"> + <caption align="top"><b>Explicit Instrumentation</b></caption> + <tbody><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> + </tbody></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><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> + +</body></html> + </div></div><!-- contents --> +</div><!-- PageDoc --> +</div><!-- doc-content --> +<!-- start footer part --> +<div id="nav-path" class="navpath"><!-- id is needed for treeview function! --> + <ul> + <li class="footer">Generated by + <a href="http://www.doxygen.org/index.html"> + <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.9.1 </li> + </ul> +</div> +</body> +</html> |