<html>
<head><title>
HDF5/H5F API Specification
</title>
<!-- #BeginLibraryItem "/ed_libs/styles_RM.lbi" -->
<!--
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by the Board of Trustees of the University of Illinois. *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the files COPYING and Copyright.html. COPYING can be found at the root *
* of the source code distribution tree; Copyright.html can be found at the *
* root level of an installed copy of the electronic HDF5 document set and *
* is linked from the top-level documents page. It can also be found at *
* http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html. If you do not have *
* access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-->
<link href="ed_styles/RMelect.css" rel="stylesheet" type="text/css">
<!-- #EndLibraryItem --></head>
<body bgcolor="#FFFFFF">
<!-- HEADER RIGHT " " -->
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="index.html">HDF5 documents and links</a> <br>
<a href="H5.intro.html">Introduction to HDF5</a> <br>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</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="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5im.html">H5IM</a>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5lt.html">H5LT</a>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5pt.html">H5PT</a>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5tb.html">H5TB</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>
<a href="RM_H5F.html">H5F</a>
<a href="RM_H5G.html">H5G</a>
<a href="RM_H5I.html">H5I</a>
<a href="RM_H5P.html">H5P</a>
<br>
<a href="RM_H5R.html">H5R</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="PredefDTypes.html">Datatypes</a>
</td></tr>
</table>
</center>
<hr><!-- #EndLibraryItem --><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.
<p>
<strong>The C Interfaces:</strong>
<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>
<li><a href="#File-Flush">H5Fflush</a>
<li><a href="#File-IsHDF5">H5Fis_hdf5</a>
<li><a href="#File-Mount">H5Fmount</a>
</ul>
</td><td> </td><td valign=top>
<ul>
<li><a href="#File-Unmount">H5Funmount</a>
<li><a href="#File-GetVfdHandle">H5Fget_vfd_handle</a>
<li><a href="#File-GetFilesize">H5Fget_filesize</a>
<li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
<li><a href="#File-GetAccessPlist">H5Fget_access_plist</a>
<li><a href="#File-GetName">H5Fget_name</a>
<li><a href="#File-GetObjCount">H5Fget_obj_count</a>
</ul>
</td><td> </td><td valign=top>
<ul>
<li><a href="#File-GetObjIDs">H5Fget_obj_ids</a>
<li><a href="#File-GetFreeSpace">H5Fget_freespace</a>
<li><a href="#File-GetMdcConfig">H5Fget_mdc_config</a>
<li><a href="#File-GetMdcHitRate">H5Fget_mdc_hit_rate</a>
<li><a href="#File-GetMdcSize">H5Fget_mdc_size</a>
<li><a href="#File-ResetMdcHitRateStats">H5Freset_mdc_hit_rate_stats</a>
<li><a href="#File-SetMdcConfig">H5Fset_mdc_config</a>
</ul>
</td></tr>
</table>
<br>
<i>Alphabetical Listing</i>
<table border="0">
<tr>
<td valign="top">
<ul>
<li><a href="#File-Close">H5Fclose</a>
<li><a href="#File-Create">H5Fcreate</a>
<li><a href="#File-Flush">H5Fflush</a>
<li><a href="#File-GetAccessPlist">H5Fget_access_plist</a>
<li><a href="#File-GetCreatePlist">H5Fget_create_plist</a>
<li><a href="#File-GetFilesize">H5Fget_filesize</a>
<li><a href="#File-GetFreeSpace">H5Fget_freespace</a>
</ul>
</td>
<td> </td>
<td valign="top">
<ul>
<li><a href="#File-GetMdcConfig">H5Fget_mdc_config</a>
<li><a href="#File-GetMdcHitRate">H5Fget_mdc_hit_rate</a>
<li><a href="#File-GetMdcSize">H5Fget_mdc_size</a>
<li><a href="#File-GetName">H5Fget_name</a>
<li><a href="#File-GetObjCount">H5Fget_obj_count</a>
<li><a href="#File-GetObjIDs">H5Fget_obj_ids</a>
<li><a href="#File-GetVfdHandle">H5Fget_vfd_handle</a>
</ul>
</td>
<td> </td>
<td valign="top">
<ul>
<li><a href="#File-IsHDF5">H5Fis_hdf5</a>
<li><a href="#File-Mount">H5Fmount</a>
<li><a href="#File-Open">H5Fopen</a>
<li><a href="#File-Reopen">H5Freopen</a>
<li><a href="#File-ResetMdcHitRateStats">H5Freset_mdc_hit_rate_stats</a>
<li><a href="#File-SetMdcConfig">H5Fset_mdc_config</a>
<li><a href="#File-Unmount">H5Funmount</a>
</ul>
</td>
</tr>
</table>
<br>
<strong>The FORTRAN90 Interfaces:</strong>
<br>
In general, each FORTRAN90 subroutine performs exactly the same task
as the corresponding C function.
<br>
<table border=0>
<tr><td valign=top>
<ul>
<li><a href="#File-Create">h5fcreate_f</a>
<li><a href="#File-Open">h5fopen_f</a>
<li><a href="#File-Reopen">h5freopen_f</a>
<li><a href="#File-Close">h5fclose_f</a>
<li><a href="#File-Flush">h5fflush_f</a>
<li><a href="#File-IsHDF5">h5fis_hdf5_f</a>
</ul>
</td><td> </td><td valign=top>
<ul>
<li><a href="#File-Mount">h5fmount_f</a>
<li><a href="#File-Unmount">h5funmount_f</a>
<li><a href="#File-GetVfdHandle">h5fget_vfd_handle_f</a>
<li><a href="#File-GetFilesize">h5fget_filesize_f</a>
<li><a href="#File-GetFreespace">h5fget_freespace_f</a>
</ul>
</td><td> </td><td valign=top>
<ul>
<li><a href="#File-GetCreatePlist">h5fget_create_plist_f</a>
<li><a href="#File-GetAccessPlist">h5fget_access_plist_f</a>
<li><a href="#File-GetName">h5fget_name_f</a>
<li><a href="#File-GetObjCount">h5fget_obj_count_f</a>
<li><a href="#File-GetObjIDs">h5fget_obj_ids_f</a>
<!--<li><a href="#File-GetMdcConfig">H5Fget_mdc_config_f</a> -->
<!--<li><a href="#File-GetMdcHitRate">H5Fget_mdc_hit_rate_f</a> -->
<!--<li><a href="#File-GetMdcSize">H5Fget_mdc_size_f</a> -->
<!--<li><a href="#File-ResetMdcHitRateStats">H5Freset_mdc_hit_rate_stats_f</a> -->
<!--<li><a href="#File-SetMdcConfig">H5Fset_mdc_config_f</a> -->
</ul>
</td></tr>
</table>
<!-- NEW PAGE -->
<!-- HEADER RIGHT " " -->
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fclose" -->
<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
by flushing all data to storage and terminating access
to the file through <code>file_id</code>.
<p>
If this is the last file identifier open for the file
and no other access identifier is open (e.g., a dataset
identifier, group identifier, or shared datatype identifier),
the file will be fully closed and access will end.
<p>
<strong>Delayed close:</strong>
<br>
Note the following deviation from the above-described behavior.
If <code>H5Fclose</code> is called for a file but one or more
objects within the file remain open, those objects will remain
accessible until they are individually closed.
Thus, if the dataset <code>data_sample</code> is open when
<code>H5Fclose</code> is called for the file containing it,
<code>data_sample</code> will remain open and accessible
(including writable) until it is explicitely closed.
The file will be automatically closed once all objects in the
file have been closed.
<p>
Be warned, hoever, that there are circumstances where it is
not possible to delay closing a file.
For example, an MPI-IO file close is a collective call; all of
the processes that opened the file must close it collectively.
The file cannot be closed at some time in the future by each
process in an independent fashion.
Another example is that an application using an AFS token-based
file access privilage may destroy its AFS token after
<code>H5Fclose</code> has returned successfully.
This would make any future access to the file, or any object
within it, illegal.
<p>
In such situations, applications must close all open objects
in a file before calling <code>H5Fclose</code>.
It is generally recommended to do so in all cases.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id </code></td>
<td valign="top">IN: Identifier of a file to terminate access to.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fclose_f
<dd>
<pre>
SUBROUTINE h5fclose_f(file_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fclose_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fcreate" -->
<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.
<p>
The return value is a file identifier for the newly-created file;
this file identifier should be closed by calling
<code>H5Fclose</code> when it is no longer needed.
<p>
<b>Special case -- File creation in the case of an
already-open file:</b>
<br>
If a file being created is already opened, by either a
previous <code>H5Fopen</code> or <code>H5Fcreate</code> call,
the HDF5 library may or may not detect that the open file and
the new file are the same physical file.
(See <a href="#File-Open"><code>H5Fopen</code></a> regarding
the limitations in detecting the re-opening of an already-open
file.)
<p>
If the library detects that the file is already opened,
<code>H5Fcreate</code> will return a failure, regardless
of the use of <code>H5F_ACC_TRUNC</code>.
<p>
If the library does not detect that the file is already opened
and <code>H5F_ACC_TRUNC</code> is not used,
<code>H5Fcreate</code> will return a failure because the file
already exists. Note that this is correct behavior.
<p>
But if the library does not detect that the file is already
opened and <code>H5F_ACC_TRUNC</code> is used,
<code>H5Fcreate</code> will truncate the existing file
and return a valid file identifier.
Such a truncation of a currently-opened file will almost
certainly result in errors.
While unlikely, the HDF5 library may not be able to detect,
and thus report, such errors.
<p>
Applications should avoid calling <code>H5Fcreate</code>
with an already opened file.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>const char *</em><code>name </code></td>
<td valign="top">IN: Name of the file to access.</td></tr>
<tr>
<td valign="top"><em>uintn</em> <code>flags</code></td>
<td valign="top">IN: File access flags. Allowable values are:
<ul><dl>
<dt><code>H5F_ACC_TRUNC</code>
<dd>Truncate file, if it already exists,
erasing all data previously stored in the file.
<dt><code>H5F_ACC_EXCL</code>
<dd>Fail if file already exists.
</dl></ul>
<li><code>H5F_ACC_TRUNC</code> and <code>H5F_ACC_EXCL</code>
are mutually exclusive; use exactly one.
<li>An additional flag, <code>H5F_ACC_DEBUG</code>, prints
debug information. This flag is used only by HDF5 library
developers; <i>it is neither tested nor supported</i>
for use in applications.</td></tr>
<tr>
<td valign="top"><em>hid_t</em> <code>create_id </code></td>
<td valign="top">IN: File creation property list identifier, used when modifying
default file meta-data.
Use <code>H5P_DEFAULT</code> for default file creation properties.</td></tr>
<tr>
<td valign="top"><em>hid_t</em> <code>access_id</code></td>
<td valign="top">IN: 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.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a file identifier if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fcreate_f
<dd>
<pre>
SUBROUTINE h5fcreate_f(name, access_flags, file_id, hdferr, &
creation_prp, access_prp)
IMPLICIT NONE
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the file
INTEGER, INTENT(IN) :: access_flag ! File access flags
! Possible values are:
! H5F_ACC_RDWR_F
! H5F_ACC_RDONLY_F
! H5F_ACC_TRUNC_F
! H5F_ACC_EXCL_F
! H5F_ACC_DEBUG_F
INTEGER(HID_T), INTENT(OUT) :: file_id ! File identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: creation_prp
! File creation propertly
! list identifier, if not
! specified its value is
! H5P_DEFAULT_F
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: access_prp
! File access property list
! identifier, if not
! specified its value is
! H5P_DEFAULT_F
END SUBROUTINE h5fcreate_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fflush" -->
<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=top><code>H5F_SCOPE_GLOBAL</code></td>
<td> </td>
<td align=left valign=top>Flushes the entire virtual file.</td></tr>
<tr><td align=left valign=top><code>H5F_SCOPE_LOCAL</code></td>
<td></td>
<td align=left valign=top>Flushes only the specified file.</td></tr>
</table>
</center>
<dt><strong>Note:</strong>
<dd>HDF5 does not possess full control over buffering.
<code>H5Fflush</code> flushes the internal HDF5 buffers then
asks the operating system (the OS) to flush the system buffers for the
open files. After that, the OS is responsible for ensuring that
the data is actually flushed to disk.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t </em><code>object_id</code></td>
<td valign="top">IN: Identifier of object used to identify the file.</td></tr>
<tr>
<td valign="top"><em>H5F_scope_t</em> <code>scope </code></td>
<td valign="top">IN: Specifies the scope of the flushing action.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fflush_f
<dd>
<pre>
SUBROUTINE h5fflush_f(obj_id, new_file_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier
INTEGER, INTENT(IN) :: scope ! Flag with two possible values:
! H5F_SCOPE_GLOBAL_F
! H5F_SCOPE_LOCAL_F
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fflush_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_access_plist" -->
<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>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id </code></td>
<td valign="top">IN: Identifier of file to get access property list of</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a file access property list identifier if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fget_access_plist_f
<dd>
<pre>
SUBROUTINE h5fget_access_plist_f(file_id, fcpl_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
INTEGER(HID_T), INTENT(OUT) :: fapl_id ! File access property list identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fget_access_plist_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_create_plist" -->
<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>
<ul><table>
<dt>
<td valign="top"><em>hid_t</em> <code>file_id </code></td>
<td valign="top">IN: Identifier of the file to get creation property list of</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a file creation property list identifier if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fget_create_plist_f
<dd>
<pre>
SUBROUTINE h5fget_create_plist_f(file_id, fcpl_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
INTEGER(HID_T), INTENT(OUT) :: fcpl_id ! File creation property list
! identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fget_create_plist_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_filesize" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetFilesize">H5Fget_filesize</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t </em><code>H5Fget_filesize</code>(<em>hid_t</em> <code>file_id</code>,
<em>hsize_t *</em><code>size</code>
)
<dt><strong>Purpose:</strong>
<dd>Returns the size of an HDF5 file.
<dt><strong>Description:</strong>
<dd><code>H5Fget_filesize</code> returns the size
of the HDF5 file specified by <code>file_id</code>.
<p>
The returned size is that of the entire file,
as opposed to only the HDF5 portion of the file.
I.e., <code>size</code> includes the user block, if any,
the HDF5 portion of the file, and
any data that may have been appended
beyond the data written through the HDF5 Library.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>file_id</code>
<dd>IN: Identifier of a currently-open HDF5 file
<dt><em>hsize_t *</em><code>size</code>
<dd>OUT: Size of the file, in bytes.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fget_freespace_f
<dd>
<pre>
SUBROUTINE h5fget_filesize_f(file_id, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! file identifier
INTEGER(HSIZE_T), INTENT(OUT) :: size ! Size of the file
INTEGER, INTENT(OUT) :: hdferr ! Error code: 0 on success,
! -1 if fail
END SUBROUTINE h5fget_filesize_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_freespace" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetFreeSpace">H5Fget_freespace</a>
<dt><strong>Signature:</strong>
<dd><em>hssize_t </em><code>H5Fget_freespace</code>(<em>hid_t</em> <code>file_id</code>)
<dt><strong>Purpose:</strong>
<dd>Returns the amount of free space in a file.
<dt><strong>Description:</strong>
<dd>Given the identifier of an open file, <code>file_id</code>,
<code>H5Fget_freespace</code> returns the amount of space that is
unused by any objects in the file.
<p>
Currently, the HDF5 library only tracks free space in a file from a
file open or create until that file is closed, so this routine will
only report the free space that has been created during that
interval.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id </code></td>
<td valign="top">IN: Identifier of a currently-open HDF5 file</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a the amount of free space in the file if successful;
otherwise returns a negative value.
<dt><strong>Returns:</strong>
<dd>Returns a file creation property list identifier if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fget_freespace_f
<dd>
<pre>
SUBROUTINE h5fget_freespace_f(file_id, free_space, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
INTEGER(HSSIZE_T), INTENT(OUT) :: free_space ! Amount of free space in file
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fget_freespace_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_mdc_config" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetMdcConfig">H5Fget_mdc_config</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Fget_mdc_config</code>(<em>hid_t</em>
<code>file_id</code>, <em>H5AC_cache_config_t *</em><code>config_ptr</code>)
<dt><strong>Purpose:</strong>
<dd>Obtain current metadata cache configuration for target file.
<dt><strong>Description:</strong>
<dd><code>H5Fget_mdc_config</code> loads the current metadata cache
configuration into the instance of <code>H5AC_cache_config_t</code>
pointed to by the <code>config_ptr</code> parameter.
<p>Note that the version field of *<code>config_ptr</code> must
be initialized --this allows the library to support old versions
of the <code>H5AC_cache_config_t</code> structure.
<p>See the overview of the metadata cache in the special topics section
of the user manual for details on metadata cache configuration.
If you haven't read and understood that documentation, the results
of this call will not make much sense.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id </code></td>
<td valign="top">IN: Identifier of the target file</td></tr>
<tr>
<td valign="top"><em>H5AC_cache_config_t *</em><code>config_ptr</code> </td>
<td valign="top">IN/OUT: Pointer to the instance of H5AC_cache_config_t
in which the current metadata cache configuration is to be reported.
The fields of this structure are discussed below:</td></tr>
<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2"><strong>General configuration section:</strong></td>
</tr>
<tr>
<td valign="top"><em>int</em> <code>version</code> </td>
<td valign="top">IN: Integer field indicating the the version
of the H5AC_cache_config_t in use. This field should be
set to H5AC__CURR_CACHE_CONFIG_VERSION
(defined in H5ACpublic.h).</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>rpt_fcn_enabled</code> </td>
<td valign="top">OUT: Boolean flag indicating whether the adaptive
cache resize report function is enabled. This field should almost
always be set to FALSE. Since resize algorithm activity is reported
via stdout, it MUST be set to FALSE on Windows machines.
<p>The report function is not supported code, and can be
expected to change between versions of the library.
Use it at your own risk.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>set_initial_size</code> </td>
<td valign="top">OUT: Boolean flag indicating whether the cache
should be created with a user specified initial maximum size.
<p>If the configuration is loaded from the cache,
this flag will always be FALSE.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>initial_size</code> </td>
<td valign="top">OUT: Initial maximum size of the cache in bytes,
if applicable.
<p>If the configuration is loaded from the cache, this
field will contain the cache maximum size as of the
time of the call.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>min_clean_fraction</code> </td>
<td valign="top">OUT: This field is only used in the parallel
version of the library. It specifies the minimum fraction
of the cache that must be kept either clean or
empty when possible.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>max_size</code> </td>
<td valign="top">OUT: Upper bound (in bytes) on the range of
values that the adaptive cache resize code can select as
the maximum cache size.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>min_size</code> </td>
<td valign="top">OUT: Lower bound (in bytes) on the range
of values that the adaptive cache resize code can
select as the maximum cache size.</td></tr>
<tr>
<td valign="top"><em>long int</em> <code>epoch_length</code> </td>
<td valign="top">OUT: Number of cache accesses between runs
of the adaptive cache resize code.</td></tr>
<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2"><strong>Increment configuration section:</strong></td>
</tr>
<tr>
<td valign="top"><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code> </td>
<td valign="top">OUT: Enumerated value indicating the operational
mode of the automatic cache size increase code. At present,
only the following values are legal:
<p>H5C_incr__off: Automatic cache size increase is disabled.
<p>H5C_incr__threshold: Automatic cache size increase is
enabled using the hit rate threshold algorithm.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>lower_hr_threshold</code> </td>
<td valign="top">OUT: Hit rate threshold used in the hit rate
threshold cache size increase algorithm.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>increment</code> </td>
<td valign="top">OUT: The factor by which the current maximum
cache size is multiplied to obtain an initial new maximum cache
size if a size increase is triggered in the hit rate
threshold cache size increase algorithm.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>apply_max_increment</code> </td>
<td valign="top">OUT: Boolean flag indicating whether an upper
limit will be applied to the size of cache size increases.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>max_increment</code> </td>
<td valign="top">OUT: The maximum number of bytes by which the
maximum cache size can be increased in a single step -- if
applicable.</td></tr>
<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2"><strong>Decrement configuration section:</strong></td>
</tr>
<tr>
<td valign="top"><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code> </td>
<td valign="top">OUT: Enumerated value indicating the operational
mode of the automatic cache size decrease code. At present,
the following values are legal:
<p>H5C_decr__off: Automatic cache size decrease is disabled,
and the remaining decrement fields are ignored.
<p>H5C_decr__threshold: Automatic cache size decrease is
enabled using the hit rate threshold algorithm.
<p>H5C_decr__age_out: Automatic cache size decrease is enabled
using the ageout algorithm.
<p>H5C_decr__age_out_with_threshold: Automatic cache size
decrease is enabled using the ageout with hit rate
threshold algorithm</td></tr>
<tr>
<td valign="top"><em>double</em> <code>upper_hr_threshold</code> </td>
<td valign="top">OUT: Upper hit rate threshold. This value is only
used if the decr_mode is either H5C_decr__threshold or
H5C_decr__age_out_with_threshold.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>decrement</code> </td>
<td valign="top">OUT: Factor by which the current max cache size
is multiplied to obtain an initial value for the new cache
size when cache size reduction is triggered in the hit rate
threshold cache size reduction algorithm.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>apply_max_decrement</code> </td>
<td valign="top">OUT: Boolean flag indicating whether an upper
limit should be applied to the size of cache size
decreases.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>max_decrement</code> </td>
<td valign="top">OUT: The maximum number of bytes by which cache
size can be decreased if any single step, if applicable.</td></tr>
<tr>
<td valign="top"><em>int</em> <code>epochs_before_eviction</code> </td>
<td valign="top">OUT: The minimum number of epochs that an entry
must reside unaccessed in cache before being evicted under
either of the ageout cache size reduction algorithms.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>apply_empty_reserve</code> </td>
<td valign="top">OUT: Boolean flag indicating whether an empty
reserve should be maintained under either of the ageout
cache size reduction algorithms.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>empty_reserve</code> </td>
<td valign="top">OUT: Empty reserve for use with the ageout
cache size reduction algorithms, if applicable.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful; otherwise returns a negative value.
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_mdc_hit_rate" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetMdcHitRate">H5Fget_mdc_hit_rate</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Fget_mdc_hit_rate</code>(<em>hid_t</em>
<code>file_id</code>, <em>double *</em><code>hit_rate_ptr</code>)
<dt><strong>Purpose:</strong>
<dd>Obtain target file's metadata cache hit rate.
<dt><strong>Description:</strong>
<dd>H5Fget_mdc_hit_rate queries the metadata cache of the target
file to obtain its hit rate (cache hits / (cache hits + cache misses))
since the last time hit rate statistics were reset. If the cache has
not been accessed since the last time the hit rate stats were reset,
the hit rate is defined to be 0.0.
<p>The hit rate stats can be reset either manually (via
H5Freset_mdc_hit_rate_stats()), or automatically. If the cache's
adaptive resize code is enabled, the hit rate stats will be reset
once per epoch. If they are reset manually as well,
the cache may behave oddly.
<p>See the overview of the metadata cache in the special
topics section of the user manual for details on the metadata
cache and its adaptive resize algorithms.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id</code>
</td>
<td valign="top">IN: Identifier of the target file.</td></tr>
<tr>
<td valign="top"><em>double *</em> <code>hit_rate_ptr</code>
</td>
<td valign="top">OUT: Pointer to the double in which the
hit rate is returned. Note that *<code>hit_rate_ptr</code> is
undefined if the API call fails.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful; otherwise
returns a negative value.
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_mdc_size" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetMdcSize">H5Fget_mdc_size</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Fget_mdc_size</code>(<em>hid_t</em> <code>file_id</code>,
<em>size_t *</em><code>max_size_ptr</code>,
<em>size_t *</em><code>min_clean_size_ptr</code>,
<em>size_t *</em><code>cur_size_ptr</code>,
<em>int *</em><code>cur_num_entries_ptr</code>)
<dt><strong>Purpose:</strong>
<dd>Obtain current metadata cache size data for specified file.
<dt><strong>Description:</strong>
<dd>H5Fget_mdc_size queries the metadata cache of the target file
for the desired size information, and returns this information in
the locations indicated by the pointer parameters. If any pointer
parameter is NULL, the associated data is not returned.
<p>If the API call fails, the values returned via the pointer
parameters are undefined.
<p>If adaptive cache resizing is enabled, the cache maximum size
and minimum clean size may change at the end of each epoch. Current
size and current number of entries can change on each cache access.
<p>Current size can exceed maximum size under certain conditions.
See the overview of the metadata cache in the special topics
section of the user manual for a discussion of this.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id</code>
</td>
<td valign="top">IN: Identifier of the target file.</td></tr>
<tr>
<td valign="top"><em>size_t *</em><code>max_size_ptr</code>
</td>
<td valign="top">OUT: Pointer to the location in which the
current cache maximum size is to be returned, or NULL if
this datum is not desired.</td></tr>
<tr>
<td valign="top"><em>size_t *</em><code>min_clean_size_ptr</code>
</td>
<td valign="top">OUT: Pointer to the location in which the
current cache minimum clean size is to be returned, or
NULL if that datum is not desired.</td></tr>
<tr>
<td valign="top"><em>size_t *</em><code>cur_size_ptr</code>
</td>
<td valign="top">OUT: Pointer to the location in which the
current cache size is to be returned, or NULL if that
datum is not desired.</td></tr>
<tr>
<td valign="top"><em>int *</em><code>cur_num_entries_ptr</code>
</td>
<td valign="top">OUT: Pointer to the location in which the
current number of entries in the cache is to be returned,
or NULL if that datum is not desired.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful; otherwise returns a
negative value.
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_name" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetName">H5Fget_name</a>
<dt><strong>Signature:</strong>
<dd><em>ssize_t</em> <code>H5Fget_name</code>(<em>hid_t</em> <code>obj_id</code>,
<em>char *</em><code>name</code>,
<em>size_t</em> <code>size</code>
)
<dt><strong>Purpose:</strong>
<dd>Retrieves name of file to which object belongs.
<dt><strong>Description:</strong>
<dd><code>H5Fget_name</code> retrieves the name of the file
to which the object <code>obj_id</code> belongs.
The object can be a group, dataset, attribute, or
named datatype.
<p>
Up to <code>size</code> characters of the filename
are returned in <code>name</code>;
additional characters, if any, are not returned to
the user application.
<p>
If the length of the name,
which determines the required value of <code>size</code>,
is unknown, a preliminary <code>H5Fget_name</code> call
can be made by setting <code>name</code> to NULL.
The return value of this call will be the size of the filename;
that value can then be assigned to <code>size</code>
for a second <code>H5Fget_name</code> call,
which will retrieve the actual name.
<p>
If an error occurs, the buffer pointed to by
<code>name</code> is unchanged and
the function returns a negative value.
<dt><strong>Parameters:</strong>
<dl>
<dt><em>hid_t</em> <code>obj_id</code>
<dd>IN: Identifier of the object for which the
associated filename is sought.
The object can be a group, dataset, attribute, or
named datatype.
<dt><em>char *</em><code>name</code>
<dd>OUT: Buffer to contain the returned filename.
<dt><em>size_t</em> <code>size</code>
<dd>IN: Size, in bytes, of the <code>name</code> buffer.
</dl>
<dt><strong>Returns:</strong>
<dd>Returns the length of the filename if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fget_name_f
<dd>
<pre>
SUBROUTINE h5fget_name_f(obj_id, buf, size, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: obj_id ! Object identifier
CHARACTER(LEN=*), INTENT(INOUT) :: buf ! Buffer to hold filename
INTEGER(SIZE_T), INTENT(OUT) :: size ! Size of the filename
INTEGER, INTENT(OUT) :: hdferr ! Error code: 0 on success,
! -1 if fail
END SUBROUTINE h5fget_name_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_obj_count" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetObjCount">H5Fget_obj_count</a>
<dt><strong>Signature:</strong>
<dd><em>int </em><code>H5Fget_obj_count</code>(<em>hid_t</em> <code>file_id</code>,
<em>unsigned int</em> <code>types</code>
)
<dt><strong>Purpose:</strong>
<dd>Returns the number of open object identifiers for an open file.
<dt><strong>Description:</strong>
<dd>Given the identifier of an open file, <code>file_id</code>,
and the desired object types, <code>types</code>,
<code>H5Fget_obj_count</code> returns the number of
open object identifiers for the file.
<p>
To retrieve a count of open identifiers for open objects in
all HDF5 application files that are currently open,
pass the value <code>H5F_OBJ_ALL</code> in <code>file_id</code>.
<p>
The types of objects to be counted are specified
in <code>types</code> as follows:
<center>
<table width=90% border=0>
<tr><td valign=top>
<code>H5F_OBJ_FILE</code>
</td><td valign=top>
Files only
</td></tr><tr><td valign=top>
<code>H5F_OBJ_DATASET</code>
</td><td valign=top>
Datasets only
</td></tr><tr><td valign=top>
<code>H5F_OBJ_GROUP</code>
</td><td valign=top>
Groups only
</td></tr><tr><td valign=top>
<code>H5F_OBJ_DATATYPE </code>
</td><td valign=top>
Named datatypes only
</td></tr><tr><td valign=top>
<code>H5F_OBJ_ATTR </code>
</td><td valign=top>
Attributes only
</td></tr><tr><td valign=top>
<code>H5F_OBJ_ALL</code>
</td><td valign=top>
All of the above
<br>
(I.e., <code>H5F_OBJ_FILE</code> | <code>H5F_OBJ_DATASET</code> |
<code>H5F_OBJ_GROUP</code> | <code>H5F_OBJ_DATATYPE</code>
| <code>H5F_OBJ_ATTR</code> )
</td></tr>
</table>
</center>
Multiple object types can be combined with the
logical <code>OR</code> operator (<code>|</code>).
For example, the expression <code>(H5F_OBJ_DATASET|H5F_OBJ_GROUP)</code> would call for
datasets and groups.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id</code></td>
<td valign="top">IN: Identifier of a currently-open HDF5 file or
<code>H5F_OBJ_ALL</code> for all currently-open HDF5 files.</td></tr>
<tr>
<td valign="top"><em>unsigned int</em> <code>types </code></td>
<td valign="top">IN: Type of object for which identifiers are to be returned.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a the number of open objects if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fget_obj_count_f
<dd>
<pre>
SUBROUTINE h5fget_obj_count_f(file_id, obj_type, obj_count, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
INTEGER, INTENT(IN) :: obj_type ! Object types, possible values are:
! H5F_OBJ_FILE_F
! H5F_OBJ_GROUP_F
! H5F_OBJ_DATASET_F
! H5F_OBJ_DATATYPE_F
! H5F_OBJ_ALL_F
INTEGER, INTENT(OUT) :: obj_count ! Number of opened objects
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fget_obj_count_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_obj_ids" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetObjIDs">H5Fget_obj_ids</a>
<dt><strong>Signature:</strong>
<dd><em>int </em><code>H5Fget_obj_ids</code>(<em>hid_t</em> <code>file_id</code>,
<em>unsigned int</em> <code>types</code>,
<em>int</em> <code>max_objs</code>,
<em>hid_t *</em><code>obj_id_list</code>
)
<dt><strong>Purpose:</strong>
<dd>Returns a list of open object identifiers.
<dt><strong>Description:</strong>
<dd>Given the file identifier <code>file_id</code> and
the type of objects to be identified, <code>types</code>,
<code>H5Fget_obj_ids</code> returns the list of identifiers
for all open HDF5 objects fitting the specified criteria.
<p>
To retrieve identifiers for open objects in all HDF5 application
files that are currently open, pass the value
<code>H5F_OBJ_ALL</code> in <code>file_id</code>.
<p>
The types of object identifiers to be retrieved are specified
in <code>types</code> using the codes listed for the same
parameter in <a href="#File-GetObjCount"><code>H5Fget_obj_count</code></a>
<p>
To retrieve identifiers for all open objects, pass a negative value
for the <code>max_objs</code>.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id</code></td>
<td valign="top">IN: Identifier of a currently-open HDF5 file or
<code>H5F_OBJ_ALL</code> for all currently-open HDF5 files.</td></tr>
<tr>
<td valign="top"><em>unsigned int</em> <code>types</code></td>
<td valign="top">IN: Type of object for which identifiers are to be returned.</td></tr>
<tr>
<td valign="top"><em>int</em> <code>max_objs</code></td>
<td valign="top">IN: Maximum number of object identifiers to place into
<code>obj_id_list</code>.</td></tr>
<tr>
<td valign="top"><em>hid_t *</em><code>obj_id_list </code></td>
<td valign="top">OUT: Pointer to the returned list of open object identifiers.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns number of objects placed into <code>obj_id_list</code> if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fget_obj_ids_f
<dd>
<pre>
SUBROUTINE h5fget_obj_ids_f(file_id, obj_type, max_objs, obj_ids, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
INTEGER, INTENT(IN) :: obj_type ! Object types, possible values are:
! H5F_OBJ_FILE_F
! H5F_OBJ_GROUP_F
! H5F_OBJ_DATASET_F
! H5F_OBJ_DATATYPE_F
! H5F_OBJ_ALL_F
INTEGER, INTENT(IN) :: max_objs ! Maximum number of object
! identifiers to retrieve
INTEGER(HID_T), DIMENSION(*), INTENT(OUT) :: obj_ids
! Array of requested object
! identifiers
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fget_obj_ids_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fget_vfd_handle" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-GetVfdHandle">H5Fget_vfd_handle</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t </em><code>H5Fget_vfd_handle</code>(<em>hid_t</em> <code>file_id</code>,
<em>hid_t</em> <code>fapl_id</code>,
<em>void *</em><code>file_handle</code>
)
<dt><strong>Purpose:</strong>
<dd>Returns pointer to the file handle from the virtual file driver.
<dt><strong>Description:</strong>
<dd>Given the file identifier <code>file_id</code> and
the file access property list <code>fapl_id</code>,
<code>H5Fget_vfd_handle</code> returns a pointer to the file handle
from the low-level file driver currently being used by the
HDF5 library for file I/O.
<dt><strong>Notes:</strong>
<dd>Users are not supposed to modify any file through this file handle.
<p>
This file handle is dynamic and is valid only while the file remains
open; it will be invalid if the file is closed and reopened or
opened during a subsequent session.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id</code></td>
<td valign="top">IN: Identifier of the file to be queried.</td></tr>
<tr>
<td valign="top"><em>hid_t</em> <code>fapl_id</code></td>
<td valign="top">IN: File access property list identifier.
For most drivers, the value will be <code>H5P_DEFAULT</code>.
For the <code>FAMILY</code> or <code>MULTI</code> drivers,
this value should be defined through the property list
functions:
<code>H5Pset_family_offset</code> for the <code>FAMILY</code>
driver and <code>H5Pset_multi_type</code> for the
<code>MULTI</code> driver.</td></tr>
<tr>
<td valign="top"><em>void *</em><code>file_handle </code></td>
<td valign="top">OUT: Pointer to the file handle being used by
the low-level virtual file driver.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong>
<dd>None.
<!--
<pre>
SUBROUTINE
</pre>
-->
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fis_hdf5" -->
<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>
<ul><table>
<tr>
<td valign="top"><em>const char *</em><code>name </code></td>
<td valign="top">IN: File name to check format.</td></tr>
</table></ul>
<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.
<dt><strong>Fortran90 Interface:</strong> h5fis_hdf5_f
<dd>
<pre>
SUBROUTINE h5fis_hdf5_f(name, status, hdferr)
IMPLICIT NONE
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the file
LOGICAL, INTENT(OUT) :: status ! This parameter indicates
! whether file is an HDF5 file
! ( TRUE or FALSE )
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fis_hdf5_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fmount" -->
<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>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
<td valign="top">IN: Identifier for of file or group in
which <code>name</code> is defined.</td>
<tr>
<td valign="top"><em>const char *</em><code>name </code></td>
<td valign="top">IN: Name of the group onto which the
file specified by <code>child_id</code>
is to be mounted.</td>
<tr>
<td valign="top"><em>hid_t</em> <code>child_id</code></td>
<td valign="top">IN: Identifier of the file to be mounted.</td>
<tr>
<td valign="top"><em>hid_t</em> <code>plist_id</code></td>
<td valign="top">IN: Identifier of the property list to be used.</td>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fmount_f
<dd>
<pre>
SUBROUTINE h5fmount_f(loc_id, name, child_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN):: name ! Group name at locationloc_id
INTEGER(HID_T), INTENT(IN) :: child_id ! File(to be mounted) identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5fmount_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fopen" -->
<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> if the
default I/O access parameters are to be used
<p>
The <code>flags</code> argument determines whether writing
to an existing file will be allowed.
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.
More complex behaviors of file access are controlled
through the file-access property list.
<p>
The return value is a file identifier for the open file;
this file identifier should be closed by calling
<code>H5Fclose</code> when it is no longer needed.
<p>
<b>Special case -- Multiple opens:</b>
<br>
A file can often be opened with a new <code>H5Fopen</code>
call without closing an already-open identifier established
in a previous <code>H5Fopen</code> or <code>H5Fcreate</code>
call. Each such <code>H5Fopen</code> call will return a
unique identifier and the file can be accessed through any
of these identifiers as long as the identifier remains valid.
In such multiply-opened cases, all the open calls should
use the same <code>flags</code> argument.
<p>
In some cases, such as files on a local Unix file system,
the HDF5 library can detect that a file is multiply opened and
will maintain coherent access among the file identifiers.
<p>
But in many other cases, such as parallel file systems or
networked file systems, it is not always possible to detect
multiple opens of the same physical file.
In such cases, HDF5 will treat the file identifiers
as though they are accessing different files and
will be unable to maintain coherent access.
Errors are likely to result in these cases.
While unlikely, the HDF5 library may not be able to detect,
and thus report, such errors.
<p>
It is generally recommended that applications avoid
multiple opens of the same file.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>const char *</em><code>name </code></td>
<td valign="top">IN: Name of the file to access.</td></tr>
<tr>
<td valign="top"><em>unsigned</em> <code>flags</code></td>
<td valign="top">IN: File access flags. Allowable values are:
<ul><dl>
<dt><code>H5F_ACC_RDWR</code>
<dd>Allow read and write access to file.
<dt><code>H5F_ACC_RDONLY</code>
<dd>Allow read-only access to file.
</dl>
<li><code>H5F_ACC_RDWR</code> and <code>H5F_ACC_RDONLY</code>
are mutually exclusive; use exactly one.
<li>An additional flag, <code>H5F_ACC_DEBUG</code>, prints
debug information. This flag is used only by HDF5 library
developers; it is neither tested nor supported
for use in applications.
</ul></td></tr>
<!-- NEW PAGE -->
<tr>
<td valign="top"><em>hid_t</em> <code>access_id </code></td>
<td valign="top">IN: 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.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a file identifier if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5fopen_f
<dd>
<pre>
SUBROUTINE h5fopen_f(name, access_flags, file_id, hdferr, &
access_prp)
IMPLICIT NONE
CHARACTER(LEN=*), INTENT(IN) :: name ! Name of the file
INTEGER, INTENT(IN) :: access_flag ! File access flags
! Possible values are:
! H5F_ACC_RDWR_F
! H5F_ACC_RDONLY_F
INTEGER(HID_T), INTENT(OUT) :: file_id ! File identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
INTEGER(HID_T), OPTIONAL, INTENT(IN) :: access_prp
! File access property list
! identifier
END SUBROUTINE h5fopen_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Freopen" -->
<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>Returns a new identifier for a previously-opened HDF5 file.
<dt><strong>Description:</strong>
<dd><code>H5Freopen</code> returns a new file identifier for an
already-open HDF5 file, as specified by <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.
<p>
Note that there is no circumstance under which
<code>H5Freopen</code> can actually open a closed file;
the file must already be open and have an active
<code>file_id</code>. E.g., one cannot close a file with
<code> H5Fclose (file_id) </code> then use
<code> H5Freopen (file_id) </code> to reopen it.
<p>
The new file identifier should be closed by calling
<code>H5Fclose</code> when it is no longer needed.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id </code></td>
<td valign="top">IN: Identifier of a file for which an additional identifier
is required.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a new file identifier if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5freopen_f
<dd>
<pre>
SUBROUTINE h5freopen_f(file_id, new_file_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: file_id ! File identifier
INTEGER(HID_T), INTENT(OUT) :: new_file_id ! New file identifier
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5freopen_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Freset_mdc_hit_rate_stats" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-ResetMdcHitRateStats">H5Freset_mdc_hit_rate_stats</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Freset_mdc_hit_rate_stats</code>(<em>hid_t</em>
<code>file_id</code>)
<dt><strong>Purpose:</strong>
<dd>Reset hit rate statistics counters for the target file.
<dt><strong>Description:</strong>
<dd>H5Freset_mdc_hit_rate_stats resets the hit rate statistics
counters in the metadata cache associated with the specified
file.
<p>If the adaptive cache resizing code is enabled, the hit
rate statistics are reset at the beginning of each epoch.
This API call allows you to do the same thing from your program.
<p>The adaptive cache resizing code may behave oddly if you use
this call when adaptive cache resizing is enabled. However,
the call should be useful if you choose to control metadata
cache size from your program.
<p>See the overview of the metadata cache in the special topics
section of the user manual for details of the metadata cache and
the adaptive cache resizing algorithms. If you haven't read,
understood, and thought about the material covered in that
documentation, you shouldn't be using this API call.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id </code></td>
<td valign="top">IN: Identifier of the target file.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful; otherwise returns a
negative value.
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Fset_mdc_config" -->
<hr>
<dl>
<dt><strong>Name:</strong> <a name="File-SetMdcConfig">H5Fset_mdc_config</a>
<dt><strong>Signature:</strong>
<dd><em>herr_t</em> <code>H5Fset_mdc_config</code>(<em>hid_t</em>
<code>file_id</code>, <em>H5AC_cache_config_t *</em><code>config_ptr</code>)
<dt><strong>Purpose:</strong>
<dd>Attempt to configure metadata cache of target file.
<dt><strong>Description:</strong>
<dd>H5Fset_mdc_config attempts to configure the file's metadata cache
according configuration supplied in *config_ptr.
<p>See the overview of the metadata cache in the special topics
section of the user manual for details on what is being configured.
If you haven't read and understood that documentation, you really
shouldn't be using this API call.
<dt><strong>Parameters:</strong>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>file_id</code>
</td>
<td valign="top">IN: Identifier of the target file</td></tr>
<tr>
<td valign="top"><em>H5AC_cache_config_t *</em><code>config_ptr</code>
</td>
<td valign="top">IN: Pointer to the instance of H5AC_cache_config_t
containing the desired configuration. The fields of this structure
are discussed below:</td></tr>
<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2"><strong>General configuration section:</strong></td>
</tr>
<tr>
<td valign="top"><em>int</em> <code>version</code>
</td>
<td valign="top">IN: Integer field indicating the the version of
the H5AC_cache_config_t in use. This field should be set to
H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>rpt_fcn_enabled</code>
</td>
<td valign="top">IN: Boolean flag indicating whether the adaptive
cache resize report function is enabled. This field should almost
always be set to FALSE. Since resize algorithm activity is reported
via stdout, it MUST be set to FALSE on Windows machines.
<p>The report function is not supported code, and can be expected to
change between versions of the library. Use it at your own risk.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>set_initial_size</code>
</td>
<td valign="top">IN: Boolean flag indicating whether the cache should be
forced to the user specified initial size.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>initial_size</code>
</td>
<td valign="top">IN: If set_initial_size is TRUE, initial_size must
contains the desired initial size in bytes. This value must lie
in the closed interval [min_size, max_size]. (see below)</td></tr>
<tr>
<td valign="top"><em>double</em> <code>min_clean_fraction</code>
</td>
<td valign="top">IN: This field is only used in the parallel version
of the library. It specifies the minimum fraction of the cache that
must be kept either clean or empty.
<p>The value must lie in the interval [0.0, 1.0]. 0.25 is a good place
to start.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>max_size</code>
</td>
<td valign="top">IN: Upper bound (in bytes) on the range of values
that the adaptive cache resize code can select as the maximum
cache size.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>min_size</code>
</td>
<td valign="top">IN: Lower bound (in bytes) on the range of values
that the adaptive cache resize code can select as the maximum
cache size.</td></tr>
<tr>
<td valign="top"><em>long int</em> <code>epoch_length</code>
</td>
<td valign="top">IN: Number of cache accesses between runs of the
adaptive cache resize code. 50,000 is a good starting number.</td></tr>
<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2"><strong>Increment configuration section:</strong></td>
</tr>
<tr>
<td valign="top"><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code>
</td>
<td valign="top">IN: Enumerated value indicating the operational mode
of the automatic cache size increase code. At present, only two
values are legal:
<p>H5C_incr__off: Automatic cache size increase is disabled,
and the remaining increment fields are ignored.
<p>H5C_incr__threshold: Automatic cache size increase is enabled
using the hit rate threshold algorithm.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>lower_hr_threshold</code>
</td>
<td valign="top">IN: Hit rate threshold used by the hit rate threshold
cache size increment algorithm.
<p>When the hit rate over an epoch is below this threshold and the
cache is full, the maximum size of the cache is multiplied by
increment (below), and then clipped as necessary to stay within
max_size, and possibly max_increment.
<p>This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9
is a good starting point.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>increment</code>
</td>
<td valign="top">IN: Factor by which the hit rate threshold cache
size increment algorithm multiplies the current cache max size
to obtain a tentative new cache size.
<p>The actual cache size increase will be clipped to satisfy the
max_size specified in the general configuration, and possibly
max_increment below.
<p>The parameter must be greater than or equal to 1.0 -- 2.0
is a reasonable value.
<p>If you set it to 1.0, you will effectively disable cache size
increases.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>apply_max_increment</code>
</td>
<td valign="top">IN: Boolean flag indicating whether an upper limit
should be applied to the size of cache size increases.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>max_increment</code>
</td>
<td valign="top">IN: Maximum number of bytes by which cache size can
be increased in a single step -- if applicable.</td></tr>
<tr>
<td colspan="2"> </td>
</tr>
<tr>
<td colspan="2"><strong>Decrement configuration section:</strong></td>
</tr>
<tr>
<td valign="top"><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code>
</td>
<td valign="top">IN: Enumerated value indicating the operational
mode of the automatic cache size decrease code. At present,
the following values are legal:
<p>H5C_decr__off: Automatic cache size decrease is disabled.
<p>H5C_decr__threshold: Automatic cache size decrease is
enabled using the hit rate threshold algorithm.
<p>H5C_decr__age_out: Automatic cache size decrease is enabled
using the ageout algorithm.
<p>H5C_decr__age_out_with_threshold: Automatic cache size
decrease is enabled using the ageout with hit rate threshold
algorithm</td></tr>
<tr>
<td valign="top"><em>double</em> <code>upper_hr_threshold</code>
</td>
<td valign="top">IN: Hit rate threshold for the hit rate threshold and
ageout with hit rate threshold cache size decrement algorithms.
<p>When decr_mode is H5C_decr__threshold, and the hit rate over a
given epoch exceeds the supplied threshold, the current maximum
cache size is multiplied by decrement to obtain a tentative new
(and smaller) maximum cache size.
<p>When decr_mode is H5C_decr__age_out_with_threshold, there is no
attempt to find and evict aged out entries unless the hit rate in
the previous epoch exceeded the supplied threshold.
<p>This field must lie in the interval [0.0, 1.0].
<p>For H5C_incr__threshold, .9995 or .99995 is a good place to start.
<p>For H5C_decr__age_out_with_threshold, .999 might be
more useful.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>decrement</code>
</td>
<td valign="top">IN: In the hit rate threshold cache size decrease
algorithm, this parameter contains the factor by which the
current max cache size is multiplied to produce a tentative
new cache size.
<p>The actual cache size decrease will be clipped to satisfy the
min_size specified in the general configuration, and possibly
max_decrement below.
<p>The parameter must be be in the interval [0.0, 1.0].
<p>If you set it to 1.0, you will effectively disable cache size
decreases. 0.9 is a reasonable starting point.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>apply_max_decrement</code>
</td>
<td valign="top">IN: Boolean flag indicating whether an upper limit
should be applied to the size of cache size decreases.</td></tr>
<tr>
<td valign="top"><em>size_t</em> <code>max_decrement</code>
</td>
<td valign="top">IN: Maximum number of bytes by which the maximum cache
size can be decreased in any single step -- if applicable.</td></tr>
<tr>
<td valign="top"><em>int</em> <code>epochs_before_eviction</code>
</td>
<td valign="top">IN: In the ageout based cache size reduction algorithms,
this field contains the minimum number of epochs an entry must remain
unaccessed in cache before the cache size reduction algorithm tries to
evict it. 3 is a reasonable value.</td></tr>
<tr>
<td valign="top"><em>hbool_t</em> <code>apply_empty_reserve</code>
</td>
<td valign="top">IN: Boolean flag indicating whether the ageout based
decrement algorithms will maintain a empty reserve when decreasing
cache size.</td></tr>
<tr>
<td valign="top"><em>double</em> <code>empty_reserve</code>
</td>
<td valign="top">IN: Empty reserve as a fraction of maximum cache
size if applicable.
<p>When so directed, the ageout based algorithms will not decrease
the maximum cache size unless the empty reserve can be met.
<p>The parameter must lie in the interval [0.0, 1.0].
0.1 or 0.05 is a good place to start.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful; otherwise returns a
negative value.
</dl>
<!-- NEW PAGE -->
<!-- HEADER RIGHT "H5Funmount" -->
<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>
<ul><table>
<tr>
<td valign="top"><em>hid_t</em> <code>loc_id</code></td>
<td valign="top">IN: File or group identifier for the location at which
the specified file is to be unmounted.</td></tr>
<tr>
<td valign="top"><em>const char *</em><code>name </code></td>
<td valign="top">IN: Name of the mount point.</td></tr>
</table></ul>
<dt><strong>Returns:</strong>
<dd>Returns a non-negative value if successful;
otherwise returns a negative value.
<dt><strong>Fortran90 Interface:</strong> h5funmount_f
<dd>
<pre>
SUBROUTINE h5funmount_f(loc_id, name, child_id, hdferr)
IMPLICIT NONE
INTEGER(HID_T), INTENT(IN) :: loc_id ! File or group identifier
CHARACTER(LEN=*), INTENT(IN):: name ! Group name at location loc_id
INTEGER, INTENT(OUT) :: hdferr ! Error code
! 0 on success and -1 on failure
END SUBROUTINE h5funmount_f
</pre>
<!--<dt><strong>Non-C API(s):</strong>
<dd>
<img src="Graphics/Java.gif">
<img src="Graphics/C++.gif">
-->
</dl>
<!-- #BeginLibraryItem "/ed_libs/NavBar_RM.lbi" --><hr>
<center>
<table border=0 width=98%>
<tr><td valign=top align=left>
<a href="index.html">HDF5 documents and links</a> <br>
<a href="H5.intro.html">Introduction to HDF5</a> <br>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/doc/UG/index.html">HDF5 User Guide</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="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5im.html">H5IM</a>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5lt.html">H5LT</a>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5pt.html">H5PT</a>
<a href="http://hdf.ncsa.uiuc.edu/HDF5/hdf5_hl/doc/RM_hdf5tb.html">H5TB</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>
<a href="RM_H5F.html">H5F</a>
<a href="RM_H5G.html">H5G</a>
<a href="RM_H5I.html">H5I</a>
<a href="RM_H5P.html">H5P</a>
<br>
<a href="RM_H5R.html">H5R</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="PredefDTypes.html">Datatypes</a>
</td></tr>
</table>
</center>
<hr><!-- #EndLibraryItem --><!-- #BeginLibraryItem "/ed_libs/Footer.lbi" --><address>
<a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a>
<br>
Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0
</address><!-- #EndLibraryItem --><SCRIPT LANGUAGE="JAVASCRIPT">
<!--
document.writeln("Last modified: 24 August 2004");
-->
</SCRIPT>
</body>
</html>