82fb21b613
been checked into "HDF5 Development" branch. General ======= Various "copy edit" types of repairs. Revisions to document cross-linking. Added structural links tying all docs together (banners at top and bottom of documents, similar to Reference Manual banners of the Beta release). Set background color to white in all documents. NCSAfooterlogo.gif hdf2.jpg New image files to make the documents more self-contained (i.e., to prevent loading images from NCSA and HDF home servers). index.html Redesigned to isolate links external to the installation in a single location. Intro to HDF5 ============= H5.intro.html Fixed banner linking Intro to other docs. Set all URLs to be relative within the distribution; nothing points back to the HDF server. Updates to "Limits of the Current Release" and "Changes in the Current Release." HDF5 User's Guide ================= Changed several User Guide section titles such that all sections that are primarily about a particular interface are now titled in the format "The xxxxx Interface (H5x)". H5.user.html Commented out links to developer docs since they are marked in MANIFEST as not being for distribution in the release. Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. Datatypes.html Removed the sentence "I'm deferring definition until later since they're probably not as important as the other data types." from Section 3.3, "Properties of Date and Time Atomic Types." Added info regarding 'char' versus 'string' datatypes. Added as Section 3.7, "Character and String Datatype Issues." References.html Commented out substantial material (at end of document) from References planning document that is not appropriate for the User Guide but that is worth keeping around. Groups.html Final edits from elimination of "current working group." HDF5 Reference Manual ===================== Removed "Draft" from the <title>__</title> lines. RM_H5Front.html Removed 2nd and 3rd indices from page. Changed "freeform" lists of sections (TOCs) to aligned tables. RM_H5F.html RM_H5P.html Add file mounting information.
486 lines
18 KiB
HTML
486 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>.
|
|
<dt><strong>Parameters:</strong>
|
|
<dl>
|
|
<dt><em>hid_t</em> <code>loc_id</code>
|
|
<dd>The identifier for the group onto which the
|
|
file specified by <code>child_id</code>
|
|
is to be mounted.
|
|
<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 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>
|