mirror of
https://github.com/HDFGroup/hdf5.git
synced 2026-09-25 04:09:44 +03:00
222 lines
17 KiB
HTML
222 lines
17 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: Using Identifiers</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-07-11</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('_using_identifiers.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">Using Identifiers </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="_u_g.html" title="HDF5 User Guide">HDF5 User Guide</a> / <a class="el" href="_a_r__u_g.html" title="Additional Resources">Additional Resources</a> </p><hr />
|
||
<h1 class="doxsection"><a class="anchor" id="sec_using_identifiers"></a>
|
||
Using Identifiers</h1>
|
||
<p>The purpose of this topic is to describe how identifiers behave and how they should be treated by application programs.</p>
|
||
<p>When an application program uses the HDF5 library to create or open an item, a unique identifier is returned. The items that return a unique identifier when they are created or opened include the following: </p><ul>
|
||
<li>dataset </li>
|
||
<li>group </li>
|
||
<li>datatype </li>
|
||
<li>dataspace </li>
|
||
<li>file </li>
|
||
<li>attribute </li>
|
||
<li>property list </li>
|
||
<li>referenced object </li>
|
||
<li>error stack </li>
|
||
<li>error message</li>
|
||
</ul>
|
||
<p>An application may open one of the items listed above more than once at the same time. For example, an application might open a group twice, receiving two identifiers. Information from one dataset in the group could be handled through one identifier, and the information from another dataset in the group could be handled by a different identifier.</p>
|
||
<p>An application program should track every identifier it receives as a result of creating or opening one of the items listed above. In order for an application to close properly, it must release every identifier it has opened. If an application opened a group twice for example, it would need to issue two <a class="el" href="group___h5_g.html#ga8dbe20b390d2504f0bd3589ed8f4e221" title="Closes the specified group.">H5Gclose</a> commands, one for each identifier. Not releasing identifiers causes resource leaks. Until an identifier is released, the item associated with the identifier is still open.</p>
|
||
<p>The library considers a file open until all of the identifiers associated with the file and with the file’s various items have been released. The identifiers associated with these open items must be released separately. This means that an application can close a file and still work with one or more portions of the file. Suppose an application opened a file, a group within the file, and two datasets within the group. If the application closed the file with <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a>, then the file would be considered closed to the application, but the group and two datasets would still be open.</p>
|
||
<p>There are several exceptions to the above file closing rule. One is when the <a class="el" href="group___h5.html#ga8a9fe81dcf66972ed75ea481e7750574" title="Flushes all data to disk, closes all open objects, and releases memory.">H5close</a> function is used instead of <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a>. <a class="el" href="group___h5.html#ga8a9fe81dcf66972ed75ea481e7750574" title="Flushes all data to disk, closes all open objects, and releases memory.">H5close</a> causes a general shut down of the library: all data is written to disk, all identifiers are closed, and all memory used by the library is cleaned up. Another exception occurs on parallel processing systems. Suppose on a parallel system an application has opened a file, a group in the file, and two datasets in the group. If the application uses the <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a> function to close the file, the call will fail with an error. The open group and datasets must be closed before the file can be closed. A third exception is when the file access property list includes the property <a class="el" href="_h5_fpublic_8h.html#aa85fa00d037d2b0401cf72edf9a6475fae6af53249bfe320745828497f28b6390">H5F_CLOSE_STRONG</a>. This property causes the closing of all of the file’s open items when the file is closed with <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a>. For more information about <a class="el" href="group___h5.html#ga8a9fe81dcf66972ed75ea481e7750574" title="Flushes all data to disk, closes all open objects, and releases memory.">H5close</a>, <a class="el" href="group___h5_f.html#gac55cd91d80822e4f8c2a7f04ea71b124" title="Terminates access to an HDF5 file.">H5Fclose</a>, and <a class="el" href="group___f_a_p_l.html#ga60e3567f677fd3ade75b909b636d7b9c" title="Sets the file close degree.">H5Pset_fclose_degree</a>, see the <a class="el" href="_r_m.html" title="HDF5 Reference Manual">HDF5 Reference Manual</a>.</p>
|
||
<p>The reference manual entries for functions that return identifiers describe what might be returned as follows: <b>Returns:</b> Returns an identifier if successful; otherwise returns a negative value.</p>
|
||
<p>In other words, a successful operation will return a non-negative identifier which will never be 0 (zero) and will always be a positive value.</p>
|
||
<h2 class="doxsection"><a class="anchor" id="subsec_using_identifiers_func"></a>
|
||
Functions that Return Identifiers</h2>
|
||
<p>Some of the functions that return identifiers are listed below.</p>
|
||
<ul>
|
||
<li><a class="el" href="group___h5_a.html#ga4a76e4e5ab6eb0fd2aa7990d38d55f24">H5Acreate</a> </li>
|
||
<li><a class="el" href="group___h5_a.html#ga004160c28e281455ec48aa7fe557ef8a" title="Creates an attribute attached to a specified object.">H5Acreate_by_name</a> </li>
|
||
<li><a class="el" href="group___h5_a.html#ga0b070b714b2e535df2e1cb3005026a44" title="Gets an attribute's datatype.">H5Aget_type</a> </li>
|
||
<li><a class="el" href="group___h5_a.html#ga59863b205b6d93b2145f0fbca49656f7" title="Opens an attribute for an object specified by object identifier and attribute name.">H5Aopen</a> </li>
|
||
<li><a class="el" href="group___h5_a.html#gab1451cdff4f77dcf9feaee83c8179b2d" title="Opens the nth attribute attached to an object.">H5Aopen_by_idx</a> </li>
|
||
<li><a class="el" href="group___h5_a.html#gadb49a0b5b9798d2e944d877adba8ae10" title="Opens an attribute for an object by object name and attribute name.">H5Aopen_by_name</a> </li>
|
||
<li><a class="el" href="group___h5_d.html#ga0647ba4bbd26d5230cc07f3a5685b2cf">H5Dcreate</a> </li>
|
||
<li><a class="el" href="group___h5_d.html#ga15a77e82383d821fee8ecbf9ab8408cb" title="Creates a dataset in a file without linking it into the file structure.">H5Dcreate_anon</a> </li>
|
||
<li><a class="el" href="group___h5_d.html#ga252c0ddac7a7817bd757190e7398353b" title="Returns the dataset access property list associated with a dataset.">H5Dget_access_plist</a> </li>
|
||
<li><a class="el" href="group___h5_d.html#ga8848f14f4aba8e6160c3d8bb7f1be163" title="Returns an identifier for a copy of the dataset creation property list for a dataset.">H5Dget_create_plist</a> </li>
|
||
<li><a class="el" href="group___h5_d.html#gad42a46be153d895d8c28a11ebf5a0d0a" title="Returns an identifier for a copy of the dataspace for a dataset.">H5Dget_space</a> </li>
|
||
<li><a class="el" href="group___h5_d.html#ga7cd04b8332e8a0939b9973fbc500cadb" title="Returns an identifier for a copy of the datatype for a dataset.">H5Dget_type</a> </li>
|
||
<li><a class="el" href="_h5version_8h.html#a7dba2e5b2045f31c0932123ffb54f7a3">H5Dopen</a> </li>
|
||
<li><a class="el" href="group___h5_e.html#ga99a705d98873dcdd1bb6f9d5eebc5afd" title="Adds a major or minor error message to an error class.">H5Ecreate_msg</a> </li>
|
||
<li><a class="el" href="group___h5_e.html#ga8bfca811dc01e97b4ab0736dd8775b39" title="Creates a new, empty error stack.">H5Ecreate_stack</a> </li>
|
||
<li><a class="el" href="group___h5_f.html#gae64b51ee9ac0781bc4ccc599d98387f4" title="Creates an HDF5 file.">H5Fcreate</a> </li>
|
||
<li><a class="el" href="group___h5_f.html#gaa3f4f877b9bb591f3880423ed2bf44bc" title="Opens an existing HDF5 file.">H5Fopen</a> </li>
|
||
<li><a class="el" href="group___h5_f.html#ga3f213eb05c5419d63ba168c30036e47b" title="Returns a new identifier for a previously-opened HDF5 file.">H5Freopen</a> </li>
|
||
<li><a class="el" href="group___h5_g.html#ga187cee27a9fc4f1a311eb19b0522c7b8">H5Gcreate</a> </li>
|
||
<li><a class="el" href="group___h5_g.html#gab52641f0736281faaaae4e3039bbb344" title="Creates a new empty group without linking it into the file structure.">H5Gcreate_anon</a> </li>
|
||
<li><a class="el" href="group___h5_g.html#ga3eca6807deff4f9e51fc5fe0befc2245">H5Gopen</a> </li>
|
||
<li><a class="el" href="group___h5_o.html#ga9f635f58c7ddf17f87c253bfbca08bc1" title="Opens an object in an HDF5 file by location identifier and path name.">H5Oopen</a> </li>
|
||
<li><a class="el" href="group___h5_o.html#ga137f3823adab4daaaf8fe87b40453fa2" title="Opens an object using its address within an HDF5 file.">H5Oopen_by_addr</a> </li>
|
||
<li><a class="el" href="group___h5_o.html#gaeb66e5cbb3ca79890fc284a0b06762be" title="Opens the nth object in a group.">H5Oopen_by_idx</a> </li>
|
||
<li><a class="el" href="group___p_l_c_r.html#gaf1b11da01d4d45d788c45f8bc5f0cbfa" title="Creates a new property list as an instance of a property list class.">H5Pcreate</a> </li>
|
||
<li><a class="el" href="group___d_c_p_l.html#ga8319e9386cdb9b3881a8b698edfc78fc" title="Gets a dataspace identifier for the selection within the source dataset used in the mapping.">H5Pget_virtual_srcspace</a> </li>
|
||
<li><a class="el" href="group___d_c_p_l.html#ga6425cabbc055b66e218b4728d6eb911d" title="Gets a dataspace identifier for the selection within the virtual dataset used in the mapping.">H5Pget_virtual_vspace</a> </li>
|
||
<li><a class="el" href="group___h5_r.html#ga5dc19b9d1833af66c5e1f819f2c05c4a">H5Rdereference</a> </li>
|
||
<li><a class="el" href="group___h5_r.html#ga1702d609e85b9edd3d1e526a0276484f" title="Sets up a dataspace and selection as specified by a region reference.">H5Rget_region</a> </li>
|
||
<li><a class="el" href="group___h5_s.html#gabee514327cba34ca9951b24fa14fb083" title="Creates a new dataspace of a specified type.">H5Screate</a> </li>
|
||
<li><a class="el" href="group___h5_s.html#ga8e35eea5738b4805856eac7d595254ae" title="Creates a new simple dataspace and opens it for access.">H5Screate_simple</a> </li>
|
||
<li><a class="el" href="group___h5_t.html#gaec07efbab84f4e5b4ed22f010786be8e" title="Copies an existing datatype.">H5Tcopy</a> </li>
|
||
<li><a class="el" href="group___h5_t.html#gaa9afc38e1a7d35e4d0bec24c569b3c65" title="Creates a new datatype.">H5Tcreate</a> </li>
|
||
<li><a class="el" href="_h5version_8h.html#ac90f7722dacad861c0a22507d3adf0dd">H5Tdecode</a> </li>
|
||
<li><a class="el" href="group___c_o_m_p_o_u_n_d.html#gaf5de0eabe28246f040342e275b9a63eb" title="Returns the datatype of the specified member.">H5Tget_member_type</a> </li>
|
||
<li><a class="el" href="group___h5_t.html#ga331e8f7b388a50af77294018db788de3" title="Returns the base datatype from which a datatype is derived.">H5Tget_super</a> </li>
|
||
<li><a class="el" href="group___h5_t.html#ga1d14b407603fdcedfbed1f723784c209">H5Topen</a></li>
|
||
</ul>
|
||
<hr />
|
||
<p> Navigate back: <a class="el" href="index.html" title="notitle">Main</a> / <a class="el" href="_u_g.html" title="HDF5 User Guide">HDF5 User Guide</a> / <a class="el" href="_a_r__u_g.html" title="Additional Resources">Additional Resources</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>
|