mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-27 02:10:55 +08:00
d70b72d630
RM_H5S.html Dataspaces.html H5Sselect_hyperslab H5Sselect_elements Add H5S_SELECT_OR operator. Converted operator list to a table. H5Sextent_copy Corrected source and destination descriptions. (RM_H5S.html only) H5Screate Removed unused H5S_NONE dataspace type. H5Sset_extent_none Corrected reset class type to H5S_NO_CLASS (previously said H5S_NONE). RM_H5G.html H5Gget_linkval Corrected descriptions of 'loc_id', 'name', and 'value'. Corrected "Purpose". Emphasized need to call H5Gget_objinfo first. H5Gset_comment H5Gget_comment Corrected description of 'loc_id'. H5Gget_objinfo Corrected description of 'loc_id'. Added H5G_TYPE to list of valid values of 'type'. RM_H5F.html ExternalFiles.html H5Fmount H5Funmount Corrected description of 'loc_id'. Changed function descriptions in ExternalFiles.html to correspond to RM. RM_H5T.html Moved H5Tget_class and H5Tget_size to "General Datatype Operations" in top index.
488 lines
18 KiB
HTML
488 lines
18 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-Open">H5Fopen</a>
|
|
<li><a href="#File-Create">H5Fcreate</a>
|
|
<li><a href="#File-IsHDF5">H5Fis_hdf5</a>
|
|
</ul>
|
|
</td><td> </td><td valign=top>
|
|
<ul>
|
|
<li><a href="#File-Flush">H5Fflush</a>
|
|
<li><a href="#File-Close">H5Fclose</a>
|
|
<li><a href="#File-Mount">H5Fmount</a>
|
|
<li><a href="#File-Unmount">H5Funmount</a>
|
|
<li><a href="#File-Reopen">H5Freopen</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. See the <code>H5Fcreate</code>
|
|
parameters list for a list of possible values.
|
|
<dt><em>hid_t</em> <code>access_id</code>
|
|
<dd>Identifier for the file access properties list.
|
|
</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. Possible 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_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.
|
|
<dt>H5P_DEFAULT
|
|
<dd>Apply default file access and creation properties.
|
|
</dl></ul>
|
|
<dt><em>hid_t</em> <code>create_id</code>
|
|
<dd>File creation property list identifier, used when modifying
|
|
default file meta-data.
|
|
<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>0</code> for default 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>const char *</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>hbool_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>Returns <code>TRUE</code> or <code>FALSE</code> if successful.
|
|
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> identifies a file or group.
|
|
<code>name</code> then specifies a group 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 either be 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.
|
|
<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 file to be unmounted.
|
|
</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>
|