[svn-r502] HDF5 Reference Manual
Final updates for Alpha2. All currently-implemented functions added. Technical content verified.
This commit is contained in:
Frank Baker
@@ -5,6 +5,23 @@ HDF5/H5F Draft API Specification
|
||||
|
||||
<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="Glossary.html">Glossary</a>
|
||||
</center>
|
||||
<hr>
|
||||
|
||||
<center>
|
||||
<h1>H5F: File Interface</h1>
|
||||
</center>
|
||||
@@ -34,160 +51,250 @@ documented below.
|
||||
</td></tr>
|
||||
</table>
|
||||
|
||||
<hr>
|
||||
|
||||
<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>uintn</em> <code>flags</code>,
|
||||
<em>hid_t</em> <code>access_template</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>This is the primary function for opening existing HDF5 files.
|
||||
The <code>flags</code> parameter determines the file access mode.
|
||||
There is no read flag, all open files are implicitily opened for
|
||||
read access.
|
||||
All flags may be combined with the '|' (boolean OR operator) to
|
||||
change the behavior of the file open call.
|
||||
The <code>access_template</code> parameter is a template containing
|
||||
additional information required for specific methods of access,
|
||||
parallel I/O for example. The paramters for access templates are
|
||||
described in the H5P API documentation.
|
||||
<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>uintn</em> <code>flags</code>
|
||||
<dd>File access flags:
|
||||
<ul><dl>
|
||||
<dt>H5F_ACC_RDWR
|
||||
<dd>Allow read and write access to file.
|
||||
</dl></ul>
|
||||
<dt><em>hid_t</em><code>access_template</code>
|
||||
<dd>Template indicating the file access properties.
|
||||
If parallel file access is desired, this is a collective
|
||||
call according to the communicator stored in the
|
||||
access_template. Use 0 for default access template.
|
||||
<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>A file identifier if successful;
|
||||
<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>uintn</em> <code>flags</code>,
|
||||
<em>hid_t</em> <code>create_template</code>,
|
||||
<em>hid_t</em> <code>access_template</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>This is the primary function for opening and creating HDF5 files.
|
||||
The <code>flags</code> parameter determines whether an existing
|
||||
file will be overwritten or not. All newly created files are opened
|
||||
for both reading and writing.
|
||||
All flags may be combined with the '|' (boolean OR operator) to
|
||||
change the behavior of the file open call.
|
||||
The <code>create_template</code> and <code>access_template</code>
|
||||
parameters are templates containing additional information required
|
||||
for specific methods of access or particular aspects of the file
|
||||
to set when creating a file.
|
||||
The parameters for creation and access templates are
|
||||
described in the H5P API documentation.
|
||||
<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 template value indicates that the library should use
|
||||
the default values for the appropriate template. 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:
|
||||
<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. The file will
|
||||
be truncated, erasing all data previously stored in
|
||||
the file.
|
||||
<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_template</code>
|
||||
<dd>File creation template ID, used when modifying default file meta-data
|
||||
<dt><em>hid_t</em><code>access_template</code>
|
||||
<dd>Template indicating the file access properties.
|
||||
<dt><em>hid_t</em> <code>create_id</code>
|
||||
<dd>File creation template 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
|
||||
access_template. Use 0 for default access template.
|
||||
<code>access_template</code>.
|
||||
Use <code>0</code> for default access template.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>An ID (of type <em>hid_t</em>) for the file upon success,
|
||||
otherwise negative
|
||||
<dd>Returns a file identifier if successful;
|
||||
otherwise 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>This function determines whether a file is in the HDF5 format.
|
||||
<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>TRUE/FALSE/negative
|
||||
<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-GetCreateTemplate">H5Fget_create_template</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Fget_create_template</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>This function returns an template ID with a copy of the parameters
|
||||
used to create this file. Useful for duplicating the parameters
|
||||
when creating another file.
|
||||
<dd><code>H5Fget_create_template</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>File ID to get creation template of
|
||||
<dd>Identifier of the file to get creation property list of
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>zero/negative
|
||||
<dd>Returns a file creation property list identifier if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
|
||||
<hr>
|
||||
<dl>
|
||||
<dt><strong>Name:</strong> <a name="File-GetAccessTemplate">H5Fget_access_template</a>
|
||||
<dt><strong>Signature:</strong>
|
||||
<dd><em>hid_t </em><code>H5Fget_access_template</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_template</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>This function terminates access to an HDF5 file. If this is the
|
||||
last file ID open for a file and if access IDs are still in use,
|
||||
<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>File ID to terminate access to.
|
||||
<dd>Identifier of a file to terminate access to.
|
||||
</dl>
|
||||
<dt><strong>Returns:</strong>
|
||||
<dd>zero/negative
|
||||
<dd>Returns SUCCEED (0) if successful;
|
||||
otherwise FAIL (-1).
|
||||
</dl>
|
||||
|
||||
<hr>
|
||||
|
||||
<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="Glossary.html">Glossary</a>
|
||||
</center>
|
||||
<hr>
|
||||
|
||||
<address>
|
||||
<a href="mailto:fbaker@ncsa.uiuc.edu">Frank Baker</a>
|
||||
<br>
|
||||
<a href="mailto:h5docs@ncsa.uiuc.edu">HDF5 Documentation</a>
|
||||
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
|
||||
|
||||
<br>
|
||||
Last modified: 29 June 1998
|
||||
Last modified: 14 July 1998
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user