42f49894fc
HDF5 Reference Manual Backs out FORTRAN API info. (It was checked into wrong tree.) Retains minor edits and formatting fixes that were made while inserting FORTRAN.
506 lines
19 KiB
HTML
506 lines
19 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5F API Specification
|
|
</title></head>
|
|
|
|
<body bgcolor="#FFFFFF">
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="H5.user.html">HDF5 User Guide</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</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>
|
|
H5F
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<br>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5RA.html">H5RA</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>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<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.
|
|
|
|
<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-GetCreatePlist">H5Fget_create_plist</a>
|
|
<li><a href="#File-GetAccessPlist">H5Fget_access_plist</a>
|
|
</ul>
|
|
</td></tr>
|
|
</table>
|
|
|
|
|
|
<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> for the default I/O access
|
|
parameters.
|
|
<p>
|
|
The <code>flags</code> argument determines whether writing
|
|
to an existing file will be allowed or not.
|
|
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.
|
|
The more complex behaviors of a file's access are controlled
|
|
through the file-access property list.
|
|
<p>
|
|
Files which are opened more than once return a unique identifier
|
|
for each <code>H5Fopen()</code> call and can be accessed
|
|
through all file identifiers.
|
|
<p>
|
|
The return value is a file identifier for the open file and it
|
|
should be closed by calling <code>H5Fclose()</code> when it is
|
|
no longer needed.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>Name of the file to access.
|
|
<dt><em>unsigned</em> <code>flags</code>
|
|
<dd>File access flags. Allowable values include:
|
|
<ul><dl>
|
|
<dt>H5F_ACC_RDWR
|
|
<dd>Allow read and write access to file.
|
|
<dt>H5F_ACC_RDONLY
|
|
<dd>Allow read-only access to file.
|
|
<dt>H5F_ACC_DEBUG
|
|
<dd>Print debug information.
|
|
(Used only by HDF5 library developers.
|
|
Do not use this flag in applications.)
|
|
</dl></ul>
|
|
<code>H5F_ACC_RDWR</code> and <code>H5F_ACC_RDONLY</code>
|
|
are mutually exclusive; use exactly one.
|
|
<dt><em>hid_t</em> <code>access_id</code>
|
|
<dd>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.
|
|
</dl>
|
|
|
|
|
|
<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. Also see
|
|
<code>H5Fpublic.h</code> for the list of supported flags.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>Name of the file to access.
|
|
<dt><em>uintn</em> <code>flags</code>
|
|
<dd>File access flags. Allowable values include:
|
|
<ul><dl>
|
|
<dt>H5F_ACC_TRUNC
|
|
<dd>Truncate file, if it already exists,
|
|
erasing all data previously stored in the file.
|
|
<dt>H5F_ACC_EXCL
|
|
<dd>Fail if file already exists.
|
|
<dt>H5F_ACC_DEBUG
|
|
<dd>Print debug information.
|
|
(Used only by HDF5 library developers.
|
|
Do not use this flag in applications.)
|
|
</dl></ul>
|
|
<code>H5F_ACC_TRUNC</code> and <code>H5F_ACC_EXCL</code>
|
|
are mutually exclusive; use exactly one.
|
|
<dt><em>hid_t</em> <code>create_id</code>
|
|
<dd>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>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.
|
|
</dl>
|
|
|
|
|
|
<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>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t </em><code>object_id</code>
|
|
<dd>Identifier of object used to identify the file.
|
|
<dt><em>H5F_scope_t</em> <code>scope</code>
|
|
<dd>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.
|
|
</dl>
|
|
|
|
|
|
<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>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.
|
|
</dl>
|
|
|
|
|
|
<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>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.
|
|
</dl>
|
|
|
|
|
|
<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>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.
|
|
</dl>
|
|
|
|
|
|
<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.
|
|
If this is the last file identifier open for a file
|
|
and if access identifiers are still in use,
|
|
this function will fail.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>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.
|
|
</dl>
|
|
|
|
|
|
<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>The identifier for of file or group in
|
|
which <code>name</code> is defined.
|
|
<dt><em>const char *</em><code>name</code>
|
|
<dd>The 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>The identifier of the file to be mounted.
|
|
<dt><em>hid_t</em> <code>plist_id</code>
|
|
<dd>The 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.
|
|
</dl>
|
|
|
|
|
|
<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>The 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>The name of the mount point.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a non-negative value if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<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>Reopens an HDF5 file.
|
|
<dt><strong>Description:</strong>
|
|
<dd><code>H5Freopen</code> reopens an HDF5 file. The new
|
|
file identifier which is returned points to the same file
|
|
as the specified file idetifier, <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.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>file_id</code>
|
|
<dd>Identifier of a file to terminate access to.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns a new file identifier if successful;
|
|
otherwise returns a negative value.
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<table border=0 width=98%>
|
|
<tr><td valign=top align=left>
|
|
<a href="H5.intro.html">Introduction to HDF5</a> <br>
|
|
<a href="H5.user.html">HDF5 User Guide</a> <br>
|
|
<a href="index.html">Other HDF5 documents and links</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>
|
|
H5F
|
|
<a href="RM_H5G.html">H5G</a>
|
|
<a href="RM_H5I.html">H5I</a>
|
|
<br>
|
|
<a href="RM_H5P.html">H5P</a>
|
|
<a href="RM_H5R.html">H5R</a>
|
|
<a href="RM_H5RA.html">H5RA</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>
|
|
</td></tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
<br>
|
|
Last modified: 30 October 1998
|
|
|
|
</body>
|
|
</html>
|