mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-26 04:09:39 +03:00
164 lines
8.8 KiB
HTML
164 lines
8.8 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.9.7"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>HDF5: HDF5 Library Code Conventions</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript">var page_layout=1;</script>
|
|
<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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(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="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">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>
|
|
</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"> 1.15.0.bca2806</span>
|
|
</div>
|
|
<div id="projectbrief">API Reference</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.7 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @license-end */
|
|
</script>
|
|
<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="_about.html"><span>About</span></a></li>
|
|
<li>
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<span id="MSearchSelect" onmouseover="return searchBox.OnSearchSelectShow()" onmouseout="return searchBox.OnSearchSelectHide()"> </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()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
|
|
</span>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(document).ready(function(){initNavTree('md_doc_2code-conventions.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">
|
|
<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">HDF5 Library Code Conventions</div></div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="autotoc_md31"></a> This document describes some practices that are new, or newly documented, starting in 2020.</p>
|
|
<h1><a class="anchor" id="autotoc_md32"></a>
|
|
Function / Variable Attributes</h1>
|
|
<p>In H5private.h, the library provides platform-independent macros for qualifying function and variable definitions.</p>
|
|
<h2><a class="anchor" id="autotoc_md33"></a>
|
|
Functions that accept <tt>printf(3)</tt> and <tt>scanf(3)</tt> format strings</h2>
|
|
<p>Label functions that accept a <code>printf(3)</code>-compliant format string with <code>H5_ATTR_FORMAT(printf,format_argno,variadic_argno)</code>, where the format string is the <code>format_argno</code>th argument (counting from 1) and the variadic arguments start with the <code>variadic_argno</code>th.</p>
|
|
<p>Functions that accept a <code>scanf(3)</code>-compliant format string should be labeled <code>H5_ATTR_FORMAT(scanf,format_argno,variadic_argno)</code>.</p>
|
|
<h2><a class="anchor" id="autotoc_md34"></a>
|
|
Functions that do never return</h2>
|
|
<p>The definition of a function that always causes the program to abort and hang should be labeled <code>H5_ATTR_NORETURN</code> to help the compiler see which flows of control are infeasible.</p>
|
|
<h2><a class="anchor" id="autotoc_md35"></a>
|
|
Other attributes</h2>
|
|
<p><b>TBD</b></p>
|
|
<h2><a class="anchor" id="autotoc_md36"></a>
|
|
Unused variables and parameters</h2>
|
|
<p>Compilers will warn about unused parameters and variables—developers should pay attention to those warnings and make an effort to prevent them.</p>
|
|
<p>Some function parameters and variables are unused in <em>all</em> configurations of the project. Ordinarily, such parameters and variables should be deleted. However, sometimes it is possible to foresee a parameter being used, or removing it would change an API, or a parameter has to be defined to conform a function to some function pointer type. In those cases, it's permissible to mark a symbol <code>H5_ATTR_UNUSED</code>.</p>
|
|
<p>Other parameters and variables are unused in <em>some</em> configurations of the project, but not all. A symbol may fall into disuse in some configuration in the future—then the compiler should warn, and the symbol should not be defined—so developers should try to label a sometimes-unused symbol with an attribute that's specific to the configurations where the symbol is (or is not) expected to be used. The library provides the following attributes for that purpose:</p>
|
|
<ul>
|
|
<li><code>H5_ATTR_DEPRECATED_USED</code>: used only if deprecated symbols are enabled</li>
|
|
<li><code>H5_ATTR_NDEBUG_UNUSED</code>: used only if <code>NDEBUG</code> is <em>not</em> #defined</li>
|
|
<li><code>H5_ATTR_DEBUG_API_USED</code>: used if the debug API is enabled</li>
|
|
<li><code>H5_ATTR_PARALLEL_UNUSED</code>: used only if Parallel HDF5 <em>is not</em> configured</li>
|
|
<li><code>H5_ATTR_PARALLEL_USED</code>: used only if Parallel HDF5 <em>is</em> configured</li>
|
|
</ul>
|
|
<p>Some attributes may be phased in or phased out in the future. </p>
|
|
</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.7 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|