85cf3f4bb8
Changed H5Sget_space_type to H5Sget_simple_extent_type. Changed H5Sget_simple_extent_type FAIL return value to H5S_NO_CLASS. RM_H5F.html H5Fflush. Corrected function name in sytax line, which had read H5Fis_hdf. RM_H5G.html Removed discussion of "current working group" and associated information from the introductory discussion. H5Gset, H5Gpush, H5Gpop Removed these functions. H5Gunlink, H5Gmove Removed the "not yet implemented" notations from these functions.
335 lines
12 KiB
HTML
335 lines
12 KiB
HTML
<html>
|
|
<head><title>
|
|
HDF5/H5F Draft API Specification
|
|
</title></head>
|
|
|
|
<body>
|
|
|
|
<hr>
|
|
<center>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<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_H5P.html">H5P</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="Glossary.html">Glossary</a>
|
|
-->
|
|
</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>
|
|
</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 FAIL (-1).
|
|
</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 FAIL (-1).
|
|
</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>
|
|
)
|
|
<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.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>const char *</em><code>object_id</code>
|
|
<dd>Identifier of object used to identify the file.
|
|
</dl>
|
|
<dt><strong>Returns:</strong>
|
|
<dd>Returns SUCCEED (0) if successful;
|
|
otherwise returns FAIL (-1).
|
|
</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 FAIL (-1).
|
|
</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 FAIL (-1).
|
|
</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 FAIL (-1).
|
|
</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 SUCCEED (0) if successful;
|
|
otherwise FAIL (-1).
|
|
</dl>
|
|
|
|
|
|
<hr>
|
|
<center>
|
|
<a href="RM_H5Front.html">HDF5 Reference Manual</a>
|
|
<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_H5P.html">H5P</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="Glossary.html">Glossary</a>
|
|
-->
|
|
</center>
|
|
<hr>
|
|
|
|
<address>
|
|
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
|
|
|
<br>
|
|
Last modified: 14 August 1998
|
|
|
|
</body>
|
|
</html>
|