mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-12-03 02:32:04 +08:00
cf629d9e6c
Purpose:
Alphabetic sort of RM function entries
Additional and modified HTML coding to accomodate HTMLdoc and
automated PDF generation
Description:
Solution:
Platforms tested:
Misc. update:
995 lines
40 KiB
HTML
995 lines
40 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5F API Specification
|
|
</title>
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/styles_RM.lbi" -->
|
|
|
|
<!--
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
* Copyright by the Board of Trustees of the University of Illinois. *
|
|
* All rights reserved. *
|
|
* *
|
|
* This file is part of HDF5. The full HDF5 copyright notice, including *
|
|
* terms governing use, modification, and redistribution, is contained in *
|
|
* the files COPYING and Copyright.html. COPYING can be found at the root *
|
|
* of the source code distribution tree; Copyright.html can be found at the *
|
|
* root level of an installed copy of the electronic HDF5 document set and *
|
|
* is linked from the top-level documents page. It can also be found at *
|
|
* http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have *
|
|
* access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
|
|
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
|
|
-->
|
|
|
|
<link href="ed_styles/RMelect.css" rel="stylesheet" type="text/css">
|
|
<!-- #EndLibraryItem --></head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
<!-- HEADER RIGHT " " -->
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr><!-- #EndLibraryItem --><center>
|
|
<h1>H5F: File Interface</h1>
|
|
</center>
|
|
|
|
<h2>File API Functions</h2>
|
|
|
|
These functions are designed to provide file-level access to HDF5 files.
|
|
Further manipulation of objects inside a file is performed through one of APIs
|
|
documented below.
|
|
|
|
<p>
|
|
<strong>The C Interfaces:</strong>
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#File-Create">H5Fcreate</a>
|
|
<li><a href="#File-Open">H5Fopen</a>
|
|
<li><a href="#File-Reopen">H5Freopen</a>
|
|
<li><a href="#File-Close">H5Fclose</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#File-Flush">H5Fflush</a>
|
|
<li><a href="#File-IsHDF5">H5Fis_hdf5</a>
|
|
<li><a href="#File-Mount">H5Fmount</a>
|
|
<li><a href="#File-Unmount">H5Funmount</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#File-GetVfdHandle">H5Fget_vfd_handle</a>
|
|
<li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
|
|
<li><a href="#File-GetAccessPlist">H5Fget_access_plist</a>
|
|
<li><a href="#File-GetObjCount">H5Fget_obj_count</a>
|
|
<li><a href="#File-GetObjIDs">H5Fget_obj_ids</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
<br>
|
|
|
|
<i>Alphabetical Listing</i>
|
|
|
|
<table border="0">
|
|
<tr>
|
|
<td valign="top">
|
|
<ul>
|
|
<li><a href="#File-Close">H5Fclose</a>
|
|
<li><a href="#File-Create">H5Fcreate</a>
|
|
<li><a href="#File-Flush">H5Fflush</a>
|
|
<li><a href="#File-GetAccessPlist">H5Fget_access_plist</a>
|
|
<li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
|
|
</ul>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<ul>
|
|
<li><a href="#File-GetObjCount">H5Fget_obj_count</a>
|
|
<li><a href="#File-GetObjIDs">H5Fget_obj_ids</a>
|
|
<li><a href="#File-GetVfdHandle">H5Fget_vfd_handle</a>
|
|
<li><a href="#File-IsHDF5">H5Fis_hdf5</a>
|
|
<li><a href="#File-Mount">H5Fmount</a>
|
|
</ul>
|
|
</td>
|
|
|
|
<td> </td>
|
|
|
|
<td valign="top">
|
|
<ul>
|
|
<li><a href="#File-Open">H5Fopen</a>
|
|
<li><a href="#File-Reopen">H5Freopen</a>
|
|
<li><a href="#File-Unmount">H5Funmount</a>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<strong>The FORTRAN90 Interfaces:</strong>
|
|
|
|
<br>
|
|
<font size=-1>
|
|
<i>In general, each FORTRAN90 subroutine performs exactly the same task
|
|
as the corresponding C function. The links below (electronic versions only) go to the C function
|
|
descriptions, which serve as general descriptions for both. A button,
|
|
under <strong>Non-C API(s)</strong> at the end of the C function description,
|
|
opens an external browser window displaying the FORTRAN90-specific
|
|
information. You will probably want to adjust the size and location of
|
|
this external window so that both browser windows are visible and to
|
|
facilitate moving easily between them.</i>
|
|
</font><br>
|
|
|
|
<table border=0>
|
|
<tr><td valign=top>
|
|
<ul>
|
|
<li><a href="#File-Create">h5fcreate_f</a>
|
|
<li><a href="#File-Open">h5fopen_f</a>
|
|
<li><a href="#File-Reopen">h5freopen_f</a>
|
|
<li><a href="#File-Close">h5fclose_f</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#File-Flush">h5fflush_f</a>
|
|
<li><a href="#File-IsHDF5">h5fis_hdf5_f</a>
|
|
<li><a href="#File-Mount">h5fmount_f</a>
|
|
<li><a href="#File-Unmount">h5funmount_f</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#File-GetVfdHandle">h5fget_vfd_handle_f</a>
|
|
<li><a href="#File-GetCreatePlist">h5fget_create_plist_f</a>
|
|
<li><a href="#File-GetAccessPlist">h5fget_access_plist_f</a>
|
|
<li><a href="#File-GetObjCount">h5fget_obj_count_f</a>
|
|
<li><a href="#File-GetObjIDs">h5fget_obj_ids_f</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fclose" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-Close">H5Fclose</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Fclose</code>(<em>hid_t</em> <code>file_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Terminates access to an HDF5 file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fclose</code> terminates access to an HDF5 file
|
|
by flushing all data to storage and terminating access
|
|
to the file through <code>file_id</code>.
|
|
<p>
|
|
If this is the last file identifier open for the file
|
|
and no other access identifier is open (e.g., a dataset
|
|
identifier, group identifier, or shared datatype identifier),
|
|
the file will be fully closed and access will end.
|
|
<p>
|
|
<strong>Delayed close:</strong>
|
|
<br>
|
|
Note the following deviation from the above-described behavior.
|
|
If <code>H5Fclose</code> is called for a file but one or more
|
|
objects within the file remain open, those objects will remain
|
|
accessible until they are individually closed.
|
|
Thus, if the dataset <code>data_sample</code> is open when
|
|
<code>H5Fclose</code> is called for the file containing it,
|
|
<code>data_sample</code> will remain open and accessible
|
|
(including writable) until it is explicitely closed.
|
|
The file will be automatically closed once all objects in the
|
|
file have been closed.
|
|
<p>
|
|
Be warned, hoever, that there are circumstances where it is
|
|
not possible to delay closing a file.
|
|
For example, an MPI-IO file close is a collective call; all of
|
|
the processes that opened the file must close it collectively.
|
|
The file cannot be closed at some time in the future by each
|
|
process in an independent fashion.
|
|
Another example is that an application using an AFS token-based
|
|
file access privilage may destroy its AFS token after
|
|
<code>H5Fclose</code> has returned successfully.
|
|
This would make any future access to the file, or any object
|
|
within it, illegal.
|
|
<p>
|
|
In such situations, applications must close all open objects
|
|
in a file before calling <code>H5Fclose</code>.
|
|
It is generally recommended to do so in all cases.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>IN: Identifier of a file to terminate access to.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fclose_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fcreate" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-Create">H5Fcreate</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Fcreate</code>(<em>const char *</em><code>name</code>,
|
|
<em>unsigned</em> <code>flags</code>,
|
|
<em>hid_t</em> <code>create_id</code>,
|
|
<em>hid_t</em> <code>access_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Creates HDF5 files.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fcreate</code> is the primary function for creating
|
|
HDF5 files .
|
|
<p>
|
|
The <code>flags</code> parameter determines whether an
|
|
existing file will be overwritten. All newly created files
|
|
are opened for both reading and writing. All flags may be
|
|
combined with the bit-wise OR operator (`|') to change
|
|
the behavior of the <code>H5Fcreate</code> call.
|
|
<p>
|
|
The more complex behaviors of file creation and access
|
|
are controlled through the file-creation and file-access
|
|
property lists. The value of <code>H5P_DEFAULT</code> for
|
|
a property list value indicates that the library should use
|
|
the default values for the appropriate property list.
|
|
<p>
|
|
The return value is a file identifier for the newly-created file;
|
|
this file identifier should be closed by calling
|
|
<code>H5Fclose</code> when it is no longer needed.
|
|
<p>
|
|
|
|
<b>Special case -- File creation in the case of an
|
|
already-open file:</b>
|
|
<br>
|
|
If a file being created is already opened, by either a
|
|
previous <code>H5Fopen</code> or <code>H5Fcreate</code> call,
|
|
the HDF5 library may or may not detect that the open file and
|
|
the new file are the same physical file.
|
|
(See <a href="#File-Open"><code>H5Fopen</code></a> regarding
|
|
the limitations in detecting the re-opening of an already-open
|
|
file.)
|
|
<p>
|
|
If the library detects that the file is already opened,
|
|
<code>H5Fcreate</code> will return a failure, regardless
|
|
of the use of <code>H5F_ACC_TRUNC</code>.
|
|
<p>
|
|
If the library does not detect that the file is already opened
|
|
and <code>H5F_ACC_TRUNC</code> is not used,
|
|
<code>H5Fcreate</code> will return a failure because the file
|
|
already exists. Note that this is correct behavior.
|
|
<p>
|
|
But if the library does not detect that the file is already
|
|
opened and <code>H5F_ACC_TRUNC</code> is used,
|
|
<code>H5Fcreate</code> will truncate the existing file
|
|
and return a valid file identifier.
|
|
Such a truncation of a currently-opened file will almost
|
|
certainly result in errors.
|
|
While unlikely, the HDF5 library may not be able to detect,
|
|
and thus report, such errors.
|
|
<p>
|
|
Applications should avoid calling <code>H5Fcreate</code>
|
|
with an already opened file.
|
|
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of the file to access.
|
|
<dt><em>uintn</em> <code>flags</code>
|
|
<dd>IN: File access flags. Allowable values are:
|
|
<ul><dl>
|
|
<dt><code>H5F_ACC_TRUNC</code>
|
|
<dd>Truncate file, if it already exists,
|
|
erasing all data previously stored in the file.
|
|
<dt><code>H5F_ACC_EXCL</code>
|
|
<dd>Fail if file already exists.
|
|
</dl></ul>
|
|
<li><code>H5F_ACC_TRUNC</code> and <code>H5F_ACC_EXCL</code>
|
|
are mutually exclusive; use exactly one.
|
|
<li>An additional flag, <code>H5F_ACC_DEBUG</code>, prints
|
|
debug information. This flag is used only by HDF5 library
|
|
developers; <i>it is neither tested nor supported</i>
|
|
for use in applications.
|
|
<dt><em>hid_t</em> <code>create_id</code>
|
|
<dd>IN: File creation property list identifier, used when modifying
|
|
default file meta-data.
|
|
Use <code>H5P_DEFAULT</code> for default file creation properties.
|
|
<dt><em>hid_t</em> <code>access_id</code>
|
|
<dd>IN: File access property list identifier.
|
|
If parallel file access is desired, this is a collective
|
|
call according to the communicator stored in the
|
|
<code>access_id</code>.
|
|
Use <code>H5P_DEFAULT</code> for default file access properties.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a file identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fcreate_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fflush" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-Flush">H5Fflush</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Fflush</code>(<em>hid_t </em><code>object_id</code>,
|
|
<em>H5F_scope_t</em> <code>scope</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Flushes all buffers associated with a file to disk.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fflush</code> causes all buffers associated with a
|
|
file to be immediately flushed to disk without removing the
|
|
data from the cache.
|
|
<p>
|
|
<code>object_id</code> can be any object associated with the file,
|
|
including the file itself, a dataset, a group, an attribute, or
|
|
a named data type.
|
|
<p>
|
|
<code>scope</code> specifies whether the scope of the flushing
|
|
action is global or local. Valid values are
|
|
<center>
|
|
<table border=0>
|
|
<tr><td align=left valign=bottom><code>H5F_SCOPE_GLOBAL</code></td>
|
|
<td> </td>
|
|
<td align=left valign=bottom>Flushes the entire virtual file.</td></tr>
|
|
<tr><td align=left valign=bottom><code>H5F_SCOPE_LOCAL</code></td>
|
|
<td></td>
|
|
<td align=left valign=bottom>Flushes only the specified file.</td></tr>
|
|
</table>
|
|
</center>
|
|
<dt><strong>Note:</strong>
|
|
<dd>HDF5 does not possess full control over buffering.
|
|
<code>H5Fflush</code> flushes the internal HDF5 buffers then
|
|
asks the operating system (the OS) to flush the system buffers for the
|
|
open files. After that, the OS is responsible for ensuring that
|
|
the data is actually flushed to disk.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t </em><code>object_id</code>
|
|
<dd>IN: Identifier of object used to identify the file.
|
|
<dt><em>H5F_scope_t</em> <code>scope</code>
|
|
<dd>IN: Specifies the scope of the flushing action.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fflush_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fget_access_plist" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-GetAccessPlist">H5Fget_access_plist</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Fget_access_plist</code>(<em>hid_t</em> <code>file_id</code>)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns a file access property list identifier.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fget_access_plist</code> returns the
|
|
file access property list identifier of the specified file.
|
|
<p>
|
|
See "File Access Properties" in
|
|
<a href="RM_H5P.html">H5P: Property List Interface</a>
|
|
in this reference manual and
|
|
"File Access Property Lists"
|
|
in <a href="Files.html"><cite>Files</cite></a> in the
|
|
<cite>HDF5 User's Guide</cite> for
|
|
additional information and related functions.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>IN: Identifier of file to get access property list of
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a file access property list identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fget_access_plist_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fget_create_plist" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-GetCreatePlist">H5Fget_create_plist</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Fget_create_plist</code>(<em>hid_t</em> <code>file_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns a file creation property list identifier.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fget_create_plist</code> returns a file creation
|
|
property list identifier identifying the creation properties
|
|
used to create this file. This function is useful for
|
|
duplicating properties when creating another file.
|
|
<p>
|
|
See "File Creation Properties" in
|
|
<a href="RM_H5P.html">H5P: Property List Interface</a>
|
|
in this reference manual and
|
|
"File Creation Properties"
|
|
in <a href="Files.html"><cite>Files</cite></a> in the
|
|
<cite>HDF5 User's Guide</cite> for
|
|
additional information and related functions.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>IN: Identifier of the file to get creation property list of
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a file creation property list identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fget_create_plist_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fget_obj_count" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-GetObjCount">H5Fget_obj_count</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>int </em><code>H5Fget_obj_count</code>(<em>hid_t</em> <code>file_id</code>,
|
|
<em>unsigned int</em> <code>types</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns the number of open object identifiers for an open file.
|
|
<dt><strong>Description:</strong>
|
|
<dd>Given the identifier of an open file, <code>file_id</code>,
|
|
and the desired object types, <code>types</code>,
|
|
<code>H5Fget_obj_count</code> returns the number of
|
|
open object identifiers for the file.
|
|
<p>
|
|
To retrieve a count of open identifiers for open objects in
|
|
all HDF5 application files that are currently open,
|
|
pass the value <code>H5F_OBJ_ALL</code> in <code>file_id</code>.
|
|
<p>
|
|
The types of objects to be counted are specified
|
|
in <code>types</code> as follows:
|
|
<center>
|
|
<table width=90% border=0>
|
|
<tr><td valign=top>
|
|
<code>H5F_OBJ_FILE</code>
|
|
</td><td valign=top>
|
|
Files only
|
|
</td></tr><tr><td valign=top>
|
|
<code>H5F_OBJ_DATASET</code>
|
|
</td><td valign=top>
|
|
Datasets only
|
|
</td></tr><tr><td valign=top>
|
|
<code>H5F_OBJ_GROUP</code>
|
|
</td><td valign=top>
|
|
Groups only
|
|
</td></tr><tr><td valign=top>
|
|
<code>H5F_OBJ_DATATYPE </code>
|
|
</td><td valign=top>
|
|
Named datatypes only
|
|
</td></tr><tr><td valign=top>
|
|
<code>H5F_OBJ_ATTR </code>
|
|
</td><td valign=top>
|
|
Attributes only
|
|
</td></tr><tr><td valign=top>
|
|
<code>H5F_OBJ_ALL</code>
|
|
</td><td valign=top>
|
|
All of the above
|
|
<br>
|
|
(I.e., <code>H5F_OBJ_FILE</code> | <code>H5F_OBJ_DATASET</code> |
|
|
<code>H5F_OBJ_GROUP</code> | <code>H5F_OBJ_DATATYPE</code>
|
|
| <code>H5F_OBJ_ATTR</code> )
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
Multiple object types can be combined with the
|
|
logical <code>OR</code> operator (<code>|</code>).
|
|
For example, the expression <code>(H5F_OBJ_DATASET|H5F_OBJ_GROUP)</code> would call for
|
|
datasets and groups.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>IN: Identifier of a currently-open HDF5 file or
|
|
<code>H5F_OBJ_ALL</code> for all currently-open HDF5 files.
|
|
<dt><em>unsigned int</em> <code>types</code>
|
|
<dd>IN: Type of object for which identifiers are to be returned.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a the number of open objects if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fget_obj_count_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fget_obj_ids" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-GetObjIDs">H5Fget_obj_ids</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>int </em><code>H5Fget_obj_ids</code>(<em>hid_t</em> <code>file_id</code>,
|
|
<em>unsigned int</em> <code>types</code>,
|
|
<em>int</em> <code>max_objs</code>,
|
|
<em>hid_t *</em><code>obj_id_list</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns a list of open object identifiers.
|
|
<dt><strong>Description:</strong>
|
|
<dd>Given the file identifier <code>file_id</code> and
|
|
the type of objects to be identified, <code>types</code>,
|
|
<code>H5Fget_obj_ids</code> returns the list of identifiers
|
|
for all open HDF5 objects fitting the specified criteria.
|
|
<p>
|
|
To retrieve identifiers for open objects in all HDF5 application
|
|
files that are currently open, pass the value
|
|
<code>H5F_OBJ_ALL</code> in <code>file_id</code>.
|
|
<p>
|
|
The types of object identifiers to be retrieved are specified
|
|
in <code>types</code> using the codes listed for the same
|
|
parameter in <a href="#File-GetObjCount"><code>H5Fget_obj_count</code></a>
|
|
<p>
|
|
To retrieve identifiers for all open objects, pass a negative value
|
|
for the <code>max_objs</code>.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>IN: Identifier of a currently-open HDF5 file or
|
|
<code>H5F_OBJ_ALL</code> for all currently-open HDF5 files.
|
|
<dt><em>unsigned int</em> <code>types</code>
|
|
<dd>IN: Type of object for which identifiers are to be returned.
|
|
<dt><em>int</em> <code>max_objs</code>
|
|
<dd>IN: Maximum number of object identifiers to place into <code>obj_id_list</code>.
|
|
<dt><em>hid_t *</em><code>obj_id_list</code>
|
|
<dd>OUT: Pointer to the returned list of open object identifiers.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns number of objects placed into <code>obj_id_list</code> if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fget_obj_ids_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fget_vfd_handle" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-GetVfdHandle">H5Fget_vfd_handle</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t </em><code>H5Fget_vfd_handle</code>(<em>hid_t</em> <code>file_id</code>,
|
|
<em>hid_t</em> <code>fapl_id</code>,
|
|
<em>void *</em><code>file_handle</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns pointer to the file handle from the virtual file driver.
|
|
<dt><strong>Description:</strong>
|
|
<dd>Given the file identifier <code>file_id</code> and
|
|
the file access property list <code>fapl_id</code>,
|
|
<code>H5Fget_vfd_handle</code> returns a pointer to the file handle
|
|
from the low-level file driver currently being used by the
|
|
HDF5 library for file I/O.
|
|
<dt><strong>Notes:</strong>
|
|
<dd>Users are not supposed to modify any file through this file handle.
|
|
<p>
|
|
This file handle is dynamic and is valid only while the file remains
|
|
open; it will be invalid if the file is closed and reopened or
|
|
opened during a subsequent session.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>IN: Identifier of the file to be queried.
|
|
<dt><em>hid_t</em> <code>fapl_id</code>
|
|
<dd>IN: File access property list identifier.
|
|
For most drivers, the value will be <code>H5P_DEFAULT</code>.
|
|
For the <code>FAMILY</code> or <code>MULTI</code> drivers,
|
|
this value should be defined through the property list
|
|
functions:
|
|
<code>H5Pset_family_offset</code> for the <code>FAMILY</code>
|
|
driver and <code>H5Pset_multi_type</code> for the
|
|
<code>MULTI</code> driver.
|
|
<dt><em>void *</em><code>file_handle</code>
|
|
<dd>OUT: Pointer to the file handle being used by
|
|
the low-level virtual file driver.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<!--
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fget_vfd_handle_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
--> <!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fis_hdf5" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-IsHDF5">H5Fis_hdf5</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>htri_t </em><code>H5Fis_hdf5</code>(<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Determines whether a file is in the HDF5 format.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fis_hdf5</code> determines whether a file is in
|
|
the HDF5 format.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: File name to check format.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>When successful, returns a positive value, for <code>TRUE</code>,
|
|
or <code>0</code> (zero), for <code>FALSE</code>.
|
|
Otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fis_hdf5_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fmount" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-Mount">H5Fmount</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Fmount</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>,
|
|
<em>hid_t</em> <code>child_id</code>,
|
|
<em>hid_t</em> <code>plist_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Mounts a file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fmount</code> mounts the file specified by
|
|
<code>child_id</code> onto the group specified by
|
|
<code>loc_id</code> and <code>name</code> using
|
|
the mount properties <code>plist_id</code>.
|
|
<p>
|
|
Note that <code>loc_id</code> is either a file or group identifier
|
|
and <code>name</code> is relative to <code>loc_id</code>.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: Identifier for of file or group in
|
|
which <code>name</code> is defined.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of the group onto which the
|
|
file specified by <code>child_id</code>
|
|
is to be mounted.
|
|
<dt><em>hid_t</em> <code>child_id</code>
|
|
<dd>IN: Identifier of the file to be mounted.
|
|
<dt><em>hid_t</em> <code>plist_id</code>
|
|
<dd>IN: Identifier of the property list to be used.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fmount_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Fopen" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-Open">H5Fopen</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Fopen</code>(<em>const char *</em><code>name</code>,
|
|
<em>unsigned</em> <code>flags</code>,
|
|
<em>hid_t</em> <code>access_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Opens an existing file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Fopen</code> opens an existing file and is the primary
|
|
function for accessing existing HDF5 files.
|
|
<p>
|
|
The parameter <code>access_id</code> is a file access property
|
|
list identifier or <code>H5P_DEFAULT</code> if the
|
|
default I/O access parameters are to be used
|
|
<p>
|
|
The <code>flags</code> argument determines whether writing
|
|
to an existing file will be allowed.
|
|
The file is opened with read and write permission if
|
|
<code>flags</code> is set to <code>H5F_ACC_RDWR</code>.
|
|
All flags may be combined with the bit-wise OR operator (`|')
|
|
to change the behavior of the file open call.
|
|
More complex behaviors of file access are controlled
|
|
through the file-access property list.
|
|
<p>
|
|
The return value is a file identifier for the open file;
|
|
this file identifier should be closed by calling
|
|
<code>H5Fclose</code> when it is no longer needed.
|
|
<p>
|
|
|
|
<b>Special case -- Multiple opens:</b>
|
|
<br>
|
|
A file can often be opened with a new <code>H5Fopen</code>
|
|
call without closing an already-open identifier established
|
|
in a previous <code>H5Fopen</code> or <code>H5Fcreate</code>
|
|
call. Each such <code>H5Fopen</code> call will return a
|
|
unique identifier and the file can be accessed through any
|
|
of these identifiers as long as the identifier remains valid.
|
|
In such multiply-opened cases, all the open calls should
|
|
use the same <code>flags</code> argument.
|
|
<p>
|
|
In some cases, such as files on a local Unix file system,
|
|
the HDF5 library can detect that a file is multiply opened and
|
|
will maintain coherent access among the file identifiers.
|
|
<p>
|
|
But in many other cases, such as parallel file systems or
|
|
networked file systems, it is not always possible to detect
|
|
multiple opens of the same physical file.
|
|
In such cases, HDF5 will treat the file identifiers
|
|
as though they are accessing different files and
|
|
will be unable to maintain coherent access.
|
|
Errors are likely to result in these cases.
|
|
While unlikely, the HDF5 library may not be able to detect,
|
|
and thus report, such errors.
|
|
<p>
|
|
It is generally recommended that applications avoid
|
|
multiple opens of the same file.
|
|
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of the file to access.
|
|
<dt><em>unsigned</em> <code>flags</code>
|
|
<dd>IN: File access flags. Allowable values are:
|
|
<ul><dl>
|
|
<dt><code>H5F_ACC_RDWR</code>
|
|
<dd>Allow read and write access to file.
|
|
<dt><code>H5F_ACC_RDONLY</code>
|
|
<dd>Allow read-only access to file.
|
|
</dl>
|
|
<li><code>H5F_ACC_RDWR</code> and <code>H5F_ACC_RDONLY</code>
|
|
are mutually exclusive; use exactly one.
|
|
<li>An additional flag, <code>H5F_ACC_DEBUG</code>, prints
|
|
debug information. This flag is used only by HDF5 library
|
|
developers; it is neither tested nor supported
|
|
for use in applications.
|
|
</ul>
|
|
<dt><em>hid_t</em> <code>access_id</code>
|
|
<dd>IN: Identifier for the file access properties list.
|
|
If parallel file access is desired, this is a collective
|
|
call according to the communicator stored in the
|
|
<code>access_id</code>.
|
|
Use <code>H5P_DEFAULT</code> for default file access properties.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a file identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5fopen_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Freopen" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-Reopen">H5Freopen</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>hid_t </em><code>H5Freopen</code>(<em>hid_t</em> <code>file_id</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Returns a new identifier for a previously-opened HDF5 file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Freopen</code> returns a new file identifier for an
|
|
already-open HDF5 file, as specified by <code>file_id</code>.
|
|
Both identifiers share caches and other information.
|
|
The only difference between the identifiers is that the
|
|
new identifier is not mounted anywhere and no files are
|
|
mounted on it.
|
|
<p>
|
|
Note that there is no circumstance under which
|
|
<code>H5Freopen</code> can actually open a closed file;
|
|
the file must already be open and have an active
|
|
<code>file_id</code>. E.g., one cannot close a file with
|
|
<code> H5Fclose (file_id) </code> then use
|
|
<code> H5Freopen (file_id) </code> to reopen it.
|
|
<p>
|
|
The new file identifier should be closed by calling
|
|
<code>H5Fclose</code> when it is no longer needed.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>IN: Identifier of a file for which an additional identifier
|
|
is required.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a new file identifier if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5freopen_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
<!-- NEW PAGE -->
|
|
<!-- HEADER RIGHT "H5Funmount" -->
|
|
<hr>
|
|
<dl>
|
|
<dt><strong>Name:</strong> <a name="File-Unmount">H5Funmount</a>
|
|
<dt><strong>Signature:</strong>
|
|
<dd><em>herr_t</em> <code>H5Funmount</code>(<em>hid_t</em> <code>loc_id</code>,
|
|
<em>const char *</em><code>name</code>
|
|
)
|
|
<dt><strong>Purpose:</strong>
|
|
<dd>Unmounts a file.
|
|
<dt><strong>Description:</strong>
|
|
<dd>Given a mount point, <code>H5Funmount</code>
|
|
dissassociates the mount point's file
|
|
from the file mounted there. This function
|
|
does not close either file.
|
|
<p>
|
|
The mount point can be either the group in the
|
|
parent or the root group of the mounted file
|
|
(both groups have the same name). If the mount
|
|
point was opened before the mount then it is the
|
|
group in the parent; if it was opened after the
|
|
mount then it is the root group of the child.
|
|
<p>
|
|
Note that <code>loc_id</code> is either a file or group identifier
|
|
and <code>name</code> is relative to <code>loc_id</code>.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>IN: File or group identifier for the location at which
|
|
the specified file is to be unmounted.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>IN: Name of the mount point.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
<dt><strong>Non-C API(s):</strong>
|
|
<dd><a href="fortran/h5f_FORTRAN.html#h5funmount_f"
|
|
target="FortranWin"><img src="Graphics/FORTRAN.gif" border=0></a>
|
|
<!--
|
|
<img src="Graphics/Java.gif">
|
|
<img src="Graphics/C++.gif">
|
|
-->
|
|
</dl>
|
|
|
|
|
|
|
|
|
|
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="index.html">HDF5 documents and links</a> <br>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</a> <br>
|
|
<!--
|
|
<a href="Glossary.html">Glossary</a><br>
|
|
-->
|
|
</td>
|
|
<td valign=top align=right>
|
|
And in this document, the
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<br>
|
|
<a href="RM_H5.html">H5</a>
|
|
<a href="RM_H5A.html">H5A</a>
|
|
<a href="RM_H5D.html">H5D</a>
|
|
<a href="RM_H5E.html">H5E</a>
|
|
<a href="RM_H5F.html">H5F</a>
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<br>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5S.html">H5S</a>
|
|
<a href="RM_H5T.html">H5T</a>
|
|
<a href="RM_H5Z.html">H5Z</a>
|
|
<a href="Tools.html">Tools</a>
|
|
<a href="PredefDTypes.html">Datatypes</a>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
<br>
|
|
Describes HDF5 Release 1.6.0, July 2003
|
|
</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
|
|
<!--
|
|
document.writeln("Last modified: 3 October 2003");
|
|
-->
|
|
</SCRIPT>
|
|
|
|
</body>
|
|
</html>
|