mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
245 lines
13 KiB
HTML
245 lines
13 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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=11"/>
|
|
<meta name="generator" content="Doxygen 1.16.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="navtreedata.js"></script>
|
|
<script type="text/javascript" src="navtree.js"></script>
|
|
<script type="text/javascript" src="cookie.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">
|
|
$(function() { init_search(); });
|
|
</script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="hdf5doxy.css" rel="stylesheet" type="text/css"/>
|
|
<link href="doxygen-awesome.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>
|
|
<div style="background:#FFDDDD;font-size:120%;text-align:center;margin:0;padding:5px">Help us improve by taking our short survey: <a href="https://www.hdfgroup.org/website-survey/">https://www.hdfgroup.org/website-survey/</a></div>
|
|
<!-- ... other metadata & script includes ... -->
|
|
<script type="text/javascript" src="doxygen-awesome-tabs.js"></script>
|
|
<script type="text/javascript">
|
|
DoxygenAwesomeTabs.init()
|
|
</script>
|
|
<!-- Google tag (gtag.js) -->
|
|
<script async src="https://www.googletagmanager.com/gtag/js?id=G-57FMZK4S7X"></script>
|
|
<script>
|
|
window.dataLayer = window.dataLayer || [];
|
|
function gtag(){dataLayer.push(arguments);}
|
|
gtag('js', new Date());
|
|
gtag('config', 'G-57FMZK4S7X');
|
|
</script>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<table cellspacing="0" cellpadding="0">
|
|
<tbody>
|
|
<tr id="projectrow">
|
|
<td id="projectlogo"><img alt="Logo" src="HDFG-logo.png"/></td>
|
|
<td id="projectalign">
|
|
<div id="projectname">HDF5<span id="projectnumber"> Last Updated on 2026-09-24</span>
|
|
</div>
|
|
<div id="projectbrief">The HDF5 Field Guide</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.16.1 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
</script>
|
|
<script type="text/javascript">
|
|
$(function() { codefold.init(); });
|
|
</script>
|
|
<div id="main-nav">
|
|
<div id="navrow1" class="tabs">
|
|
<ul class="tablist">
|
|
<li><a href="index.html"><span>Main Page</span></a></li>
|
|
<li><a href="_getting_started.html"><span>Getting started</span></a></li>
|
|
<li><a href="_u_g.html"><span>User Guide</span></a></li>
|
|
<li><a href="_r_m.html"><span>Reference Manual</span></a></li>
|
|
<li><a href="_cookbook.html"><span>Cookbook</span></a></li>
|
|
<li><a href="_t_n.html"><span>Technical Notes</span></a></li>
|
|
<li><a href="_r_f_c.html"><span>RFCs</span></a></li>
|
|
<li><a href="_s_p_e_c.html"><span>Specifications</span></a></li>
|
|
<li><a href="_g_l_s.html"><span>Glossary</span></a></li>
|
|
<li><a href="_f_t_s.html"><span>Full-Text Search</span></a></li>
|
|
<li><a href="_about.html"><span>About</span></a></li>
|
|
<li>
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<span id="MSearchSelect" class="search-icon" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"><span class="search-icon-dropdown"></span></span>
|
|
<input type="text" id="MSearchField" value="" placeholder="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()"><div id="MSearchCloseImg" class="close-icon"></div></a>
|
|
</span>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div><!-- main-nav -->
|
|
</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">
|
|
$(function(){initNavTree('_a_p_p_d_b_g.html','',''); });
|
|
</script>
|
|
<div id="container">
|
|
<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">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div><div class="header">
|
|
<div class="headertitle"><div class="title">Debugging HDF5 Applications </div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p>Navigate back: <a class="el" href="index.html" title="notitle">Main</a> / <a class="el" href="_t_n.html" title="Technical Notes">Technical Notes</a> </p><hr />
|
|
<h1 class="doxsection"><a class="anchor" id="sec_adddbg_intro"></a>
|
|
Introduction</h1>
|
|
<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.</p>
|
|
<h2 class="doxsection"><a class="anchor" id="subsec_adddbg_intro_err"></a>
|
|
Error Messages</h2>
|
|
<p>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.</p>
|
|
<h2 class="doxsection"><a class="anchor" id="subsec_adddbg_intro_invar"></a>
|
|
Invariant Conditions</h2>
|
|
<p>Unless NDEBUG 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.</p>
|
|
<h2 class="doxsection"><a class="anchor" id="subsec_adddbg_intro_stats"></a>
|
|
Timings and Statistics</h2>
|
|
<p>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.</p>
|
|
<h2 class="doxsection"><a class="anchor" id="subsec_adddbg_intro_trace"></a>
|
|
API Tracing</h2>
|
|
<p>Tracing API calls has been removed from the library.</p>
|
|
<p>The statistics can be displayed on any output stream (including streams opened by the shell) with output from different packages even going to different streams.</p>
|
|
<h1 class="doxsection"><a class="anchor" id="sec_adddbg_msg"></a>
|
|
Error Messages</h1>
|
|
<p>By default any API function that fails will print an error stack to the standard error stream. </p><div class="fragment"><div class="line">HDF5-DIAG: Error detected in thread 0. Back trace follows.</div>
|
|
<div class="line"> #000: H5F.c line 1245 in <a class="code hl_function" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a>(): unable to open file</div>
|
|
<div class="line"> major(04): File interface</div>
|
|
<div class="line"> minor(10): Unable to open file</div>
|
|
<div class="line"> #001: H5F.c line 846 in H5F_open(): file does not exist</div>
|
|
<div class="line"> major(04): File interface</div>
|
|
<div class="line"> minor(10): Unable to open file</div>
|
|
<div class="ttc" id="agroup___h5_f_html_gaa3f4f877b9bb591f3880423ed2bf44bc"><div class="ttname"><a href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc">H5Fopen</a></div><div class="ttdeci">hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id)</div><div class="ttdoc">Opens an existing HDF5 file.</div></div>
|
|
</div><!-- fragment --><p> The error handling package (H5E) is described elsewhere.</p>
|
|
<h1 class="doxsection"><a class="anchor" id="sec_adddbg_invars"></a>
|
|
Invariant Conditions</h1>
|
|
<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><div class="fragment"><div class="line">Assertion failed: <a class="code hl_namespace" href="namespace_h5.html">H5</a>.c:123: i<NELMTS(H5_debug_g)</div>
|
|
<div class="line">IOT Trap, core dumped.</div>
|
|
<div class="ttc" id="anamespace_h5_html"><div class="ttname"><a href="namespace_h5.html">H5</a></div><div class="ttdef"><b>Definition</b> H5AbstractDs.cpp:33</div></div>
|
|
</div><!-- fragment --><h1 class="doxsection"><a class="anchor" id="sec_adddbg_stats"></a>
|
|
Timings and Statistics</h1>
|
|
<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><table class="doxtable">
|
|
<tr>
|
|
<th><b>Name</b> </th><th><b>Default</b> </th><th><b>Description</b> </th></tr>
|
|
<tr>
|
|
<td>a</td><td>No</td><td>Attributes</td></tr>
|
|
<tr>
|
|
<td>ac</td><td>Yes</td><td>Meta data cache</td></tr>
|
|
<tr>
|
|
<td>b</td><td>Yes</td><td>B-Trees</td></tr>
|
|
<tr>
|
|
<td>d</td><td>Yes</td><td>Datasets</td></tr>
|
|
<tr>
|
|
<td>e</td><td>Yes</td><td>Error handling</td></tr>
|
|
<tr>
|
|
<td>f</td><td>Yes</td><td>Files</td></tr>
|
|
<tr>
|
|
<td>g</td><td>Yes</td><td>Groups</td></tr>
|
|
<tr>
|
|
<td>hg</td><td>Yes</td><td>Global heap</td></tr>
|
|
<tr>
|
|
<td>hl</td><td>No</td><td>Local heaps</td></tr>
|
|
<tr>
|
|
<td>i</td><td>Yes</td><td>Interface abstraction</td></tr>
|
|
<tr>
|
|
<td>mf</td><td>No</td><td>File memory management</td></tr>
|
|
<tr>
|
|
<td>mm</td><td>Yes</td><td>Library memory management</td></tr>
|
|
<tr>
|
|
<td>o</td><td>No</td><td>Object headers and messages</td></tr>
|
|
<tr>
|
|
<td>p</td><td>Yes</td><td>Property lists</td></tr>
|
|
<tr>
|
|
<td>s</td><td>Yes</td><td>Data spaces</td></tr>
|
|
<tr>
|
|
<td>t</td><td>Yes</td><td>Datatypes</td></tr>
|
|
<tr>
|
|
<td>v</td><td>Yes</td><td>Vectors</td></tr>
|
|
<tr>
|
|
<td>z</td><td>Yes</td><td>Raw data filters</td></tr>
|
|
</table>
|
|
<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 HDF5_DEBUG 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 'all' refers to all packages. Any word my be preceded by a minus sign to turn debugging off for the package.</p>
|
|
<h2 class="doxsection"><a class="anchor" id="subsec_adddbg_stats_sample"></a>
|
|
Sample debug specifications</h2>
|
|
<table class="doxtable">
|
|
<tr>
|
|
<td>all </td><td>This causes debugging output from all packages to be sent to the standard error stream. </td></tr>
|
|
<tr>
|
|
<td>all -t -s </td><td>Debugging output for all packages except datatypes and data spaces will appear on the standard error stream. </td></tr>
|
|
<tr>
|
|
<td>-all ac 255 t,s </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>
|
|
<p>The components of the HDF5_DEBUG value may be separated by any non-lowercase letter.</p>
|
|
<hr />
|
|
<p> Navigate back: <a class="el" href="index.html" title="notitle">Main</a> / <a class="el" href="_t_n.html" title="Technical Notes">Technical Notes</a> </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</div><!-- doc-content -->
|
|
<div id="page-nav" class="page-nav-panel">
|
|
<div id="page-nav-resize-handle"></div>
|
|
<div id="page-nav-tree">
|
|
<div id="page-nav-contents">
|
|
</div><!-- page-nav-contents -->
|
|
</div><!-- page-nav-tree -->
|
|
</div><!-- page-nav -->
|
|
</div><!-- container -->
|
|
<!-- start footer part -->
|
|
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
|
|
<ul>
|
|
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.16.1 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|