diff options
author | Frank Baker <fbaker@hdfgroup.org> | 2005-07-19 17:28:56 (GMT) |
---|---|---|
committer | Frank Baker <fbaker@hdfgroup.org> | 2005-07-19 17:28:56 (GMT) |
commit | 794ba0a251af47b8e3c60afa2fe92d267e2a6b55 (patch) | |
tree | f24cea3b81ff02fa3f31c0a1c4e80fa10f4393c0 /doc/html/RM_H5F.html | |
parent | d2e92fd23610c3ccdddbbc55484e54a5a21a9252 (diff) | |
download | hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.zip hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.gz hdf5-794ba0a251af47b8e3c60afa2fe92d267e2a6b55.tar.bz2 |
[svn-r11084]
Description:
All HDF5 user documentation has been moved to a separate hdf5doc/
repository, managed under Subversion.
With this 'cvs commit', all files are stripped from hdf5/doc/.
THIS CHANGE IS APPLIED ONLY TO THE HDF5 DEVELOPMENT BRANCH,
post Release 1.6.x; it is not applied to the release branches.
Diffstat (limited to 'doc/html/RM_H5F.html')
-rw-r--r-- | doc/html/RM_H5F.html | 1970 |
1 files changed, 0 insertions, 1970 deletions
diff --git a/doc/html/RM_H5F.html b/doc/html/RM_H5F.html deleted file mode 100644 index b3cbb33..0000000 --- a/doc/html/RM_H5F.html +++ /dev/null @@ -1,1970 +0,0 @@ -<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> |