|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |
The C Interfaces:
H5Fclose(hid_t file_id
)
H5Fclose terminates access to an HDF5 file
by flushing all data to storage and terminating access
to the file through file_id.
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.
Delayed close:
Note the following deviation from the above-described behavior.
If H5Fclose 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 data_sample is open when
H5Fclose is called for the file containing it,
data_sample 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.
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
H5Fclose has returned successfully.
This would make any future access to the file, or any object
within it, illegal.
In such situations, applications must close all open objects
in a file before calling H5Fclose.
It is generally recommended to do so in all cases.
hid_t file_id |
IN: Identifier of a file to terminate access to. |
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
H5Fcreate(const char *name,
unsigned flags,
hid_t create_id,
hid_t access_id
)
H5Fcreate is the primary function for creating
HDF5 files .
The flags 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 H5Fcreate call.
The more complex behaviors of file creation and access
are controlled through the file-creation and file-access
property lists. The value of H5P_DEFAULT for
a property list value indicates that the library should use
the default values for the appropriate property list.
The return value is a file identifier for the newly-created file;
this file identifier should be closed by calling
H5Fclose when it is no longer needed.
Special case -- File creation in the case of an
already-open file:
If a file being created is already opened, by either a
previous H5Fopen or H5Fcreate call,
the HDF5 library may or may not detect that the open file and
the new file are the same physical file.
(See H5Fopen regarding
the limitations in detecting the re-opening of an already-open
file.)
If the library detects that the file is already opened,
H5Fcreate will return a failure, regardless
of the use of H5F_ACC_TRUNC.
If the library does not detect that the file is already opened
and H5F_ACC_TRUNC is not used,
H5Fcreate will return a failure because the file
already exists. Note that this is correct behavior.
But if the library does not detect that the file is already
opened and H5F_ACC_TRUNC is used,
H5Fcreate 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.
Applications should avoid calling H5Fcreate
with an already opened file.
const char *name |
IN: Name of the file to access. |
uintn flags |
IN: File access flags. Allowable values are:
H5F_ACC_TRUNC and H5F_ACC_EXCL
are mutually exclusive; use exactly one.
H5F_ACC_DEBUG, prints
debug information. This flag is used only by HDF5 library
developers; it is neither tested nor supported
for use in applications. |
hid_t create_id |
IN: File creation property list identifier, used when modifying
default file meta-data.
Use H5P_DEFAULT for default file creation properties. |
hid_t access_id |
IN: File access property list identifier.
If parallel file access is desired, this is a collective
call according to the communicator stored in the
access_id.
Use H5P_DEFAULT for default file access properties. |
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
H5Fflush(hid_t object_id,
H5F_scope_t scope
)
H5Fflush causes all buffers associated with a
file to be immediately flushed to disk without removing the
data from the cache.
object_id can be any object associated with the file,
including the file itself, a dataset, a group, an attribute, or
a named data type.
scope specifies whether the scope of the flushing
action is global or local. Valid values are
H5F_SCOPE_GLOBAL |
Flushes the entire virtual file. | |
H5F_SCOPE_LOCAL |
Flushes only the specified file. |
H5Fflush 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.
hid_t object_id |
IN: Identifier of object used to identify the file. |
H5F_scope_t scope |
IN: Specifies the scope of the flushing action. |
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
H5Fget_access_plist(hid_t file_id)
H5Fget_access_plist returns the
file access property list identifier of the specified file.
See "File Access Properties" in H5P: Property List Interface in this reference manual and "File Access Property Lists" in Files in the HDF5 User's Guide for additional information and related functions.
hid_t file_id |
IN: Identifier of file to get access property list of |
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
H5Fget_create_plist(hid_t file_id
)
H5Fget_create_plist 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.
See "File Creation Properties" in H5P: Property List Interface in this reference manual and "File Creation Properties" in Files in the HDF5 User's Guide for additional information and related functions.
hid_t file_id |
IN: Identifier of the file to get creation property list of |
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
H5Fget_filesize(hid_t file_id,
hsize_t *size
)
H5Fget_filesize returns the size
of the HDF5 file specified by file_id.
The returned size is that of the entire file,
as opposed to only the HDF5 portion of the file.
I.e., size 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.
file_id
size
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
H5Fget_freespace(hid_t file_id)
file_id,
H5Fget_freespace returns the amount of space that is
unused by any objects in the file.
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.
hid_t file_id |
IN: Identifier of a currently-open HDF5 file |
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
H5Fget_mdc_config(hid_t
file_id, H5AC_cache_config_t *config_ptr)
H5Fget_mdc_config loads the current metadata cache
configuration into the instance of H5AC_cache_config_t
pointed to by the config_ptr parameter.
Note that the version field of *config_ptr must
be initialized --this allows the library to support old versions
of the H5AC_cache_config_t structure.
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.
hid_t file_id |
IN: Identifier of the target file |
H5AC_cache_config_t *config_ptr |
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: |
| General configuration section: | |
int version |
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). |
hbool_t rpt_fcn_enabled |
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.
The report function is not supported code, and can be expected to change between versions of the library. Use it at your own risk. |
hbool_t set_initial_size |
OUT: Boolean flag indicating whether the cache
should be created with a user specified initial maximum size.
If the configuration is loaded from the cache, this flag will always be FALSE. |
size_t initial_size |
OUT: Initial maximum size of the cache in bytes,
if applicable.
If the configuration is loaded from the cache, this field will contain the cache maximum size as of the time of the call. |
double min_clean_fraction |
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. |
size_t max_size |
OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size. |
size_t min_size |
OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size. |
long int epoch_length |
OUT: Number of cache accesses between runs of the adaptive cache resize code. |
| Increment configuration section: | |
enum H5C_cache_incr_mode incr_mode |
OUT: Enumerated value indicating the operational
mode of the automatic cache size increase code. At present,
only the following values are legal:
H5C_incr__off: Automatic cache size increase is disabled. H5C_incr__threshold: Automatic cache size increase is enabled using the hit rate threshold algorithm. |
double lower_hr_threshold |
OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm. |
double increment |
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. |
hbool_t apply_max_increment |
OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size increases. |
size_t max_increment |
OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step -- if applicable. |
| Decrement configuration section: | |
enum H5C_cache_decr_mode decr_mode |
OUT: Enumerated value indicating the operational
mode of the automatic cache size decrease code. At present,
the following values are legal:
H5C_decr__off: Automatic cache size decrease is disabled, and the remaining decrement fields are ignored. H5C_decr__threshold: Automatic cache size decrease is enabled using the hit rate threshold algorithm. H5C_decr__age_out: Automatic cache size decrease is enabled using the ageout algorithm. H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm |
double upper_hr_threshold |
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. |
double decrement |
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. |
hbool_t apply_max_decrement |
OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size decreases. |
size_t max_decrement |
OUT: The maximum number of bytes by which cache size can be decreased if any single step, if applicable. |
int epochs_before_eviction |
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. |
hbool_t apply_empty_reserve |
OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the ageout cache size reduction algorithms. |
double empty_reserve |
OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable. |
H5Fget_mdc_hit_rate(hid_t
file_id, double *hit_rate_ptr)
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.
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.
hid_t file_id
|
IN: Identifier of the target file. |
double * hit_rate_ptr
|
OUT: Pointer to the double in which the
hit rate is returned. Note that *hit_rate_ptr is
undefined if the API call fails. |
H5Fget_mdc_size(hid_t file_id,
size_t *max_size_ptr,
size_t *min_clean_size_ptr,
size_t *cur_size_ptr,
int *cur_num_entries_ptr)
If the API call fails, the values returned via the pointer parameters are undefined.
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.
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.
hid_t file_id
|
IN: Identifier of the target file. |
size_t *max_size_ptr
|
OUT: Pointer to the location in which the current cache maximum size is to be returned, or NULL if this datum is not desired. |
size_t *min_clean_size_ptr
|
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. |
size_t *cur_size_ptr
|
OUT: Pointer to the location in which the current cache size is to be returned, or NULL if that datum is not desired. |
int *cur_num_entries_ptr
|
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. |
H5Fget_name(hid_t obj_id,
char *name,
size_t size
)
H5Fget_name retrieves the name of the file
to which the object obj_id belongs.
The object can be a group, dataset, attribute, or
named datatype.
Up to size characters of the filename
are returned in name;
additional characters, if any, are not returned to
the user application.
If the length of the name,
which determines the required value of size,
is unknown, a preliminary H5Fget_name call
can be made by setting name to NULL.
The return value of this call will be the size of the filename;
that value can then be assigned to size
for a second H5Fget_name call,
which will retrieve the actual name.
If an error occurs, the buffer pointed to by
name is unchanged and
the function returns a negative value.
obj_id
name
size
name buffer.
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
H5Fget_obj_count(hid_t file_id,
unsigned int types
)
file_id,
and the desired object types, types,
H5Fget_obj_count returns the number of
open object identifiers for the file.
To retrieve a count of open identifiers for open objects in
all HDF5 application files that are currently open,
pass the value H5F_OBJ_ALL in file_id.
The types of objects to be counted are specified
in types as follows:
H5F_OBJ_FILE
| Files only |
H5F_OBJ_DATASET
| Datasets only |
H5F_OBJ_GROUP
| Groups only |
H5F_OBJ_DATATYPE
| Named datatypes only |
H5F_OBJ_ATTR
| Attributes only |
H5F_OBJ_ALL
|
All of the above
(I.e., H5F_OBJ_FILE | H5F_OBJ_DATASET |
H5F_OBJ_GROUP | H5F_OBJ_DATATYPE
| H5F_OBJ_ATTR )
|
OR operator (|).
For example, the expression (H5F_OBJ_DATASET|H5F_OBJ_GROUP) would call for
datasets and groups.
hid_t file_id |
IN: Identifier of a currently-open HDF5 file or
H5F_OBJ_ALL for all currently-open HDF5 files. |
unsigned int types |
IN: Type of object for which identifiers are to be returned. |
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
H5Fget_obj_ids(hid_t file_id,
unsigned int types,
int max_objs,
hid_t *obj_id_list
)
file_id and
the type of objects to be identified, types,
H5Fget_obj_ids returns the list of identifiers
for all open HDF5 objects fitting the specified criteria.
To retrieve identifiers for open objects in all HDF5 application
files that are currently open, pass the value
H5F_OBJ_ALL in file_id.
The types of object identifiers to be retrieved are specified
in types using the codes listed for the same
parameter in H5Fget_obj_count
To retrieve identifiers for all open objects, pass a negative value
for the max_objs.
hid_t file_id |
IN: Identifier of a currently-open HDF5 file or
H5F_OBJ_ALL for all currently-open HDF5 files. |
unsigned int types |
IN: Type of object for which identifiers are to be returned. |
int max_objs |
IN: Maximum number of object identifiers to place into
obj_id_list. |
hid_t *obj_id_list |
OUT: Pointer to the returned list of open object identifiers. |
obj_id_list if successful;
otherwise returns a negative value.
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
H5Fget_vfd_handle(hid_t file_id,
hid_t fapl_id,
void *file_handle
)
file_id and
the file access property list fapl_id,
H5Fget_vfd_handle returns a pointer to the file handle
from the low-level file driver currently being used by the
HDF5 library for file I/O.
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.
hid_t file_id |
IN: Identifier of the file to be queried. |
hid_t fapl_id |
IN: File access property list identifier.
For most drivers, the value will be H5P_DEFAULT.
For the FAMILY or MULTI drivers,
this value should be defined through the property list
functions:
H5Pset_family_offset for the FAMILY
driver and H5Pset_multi_type for the
MULTI driver. |
void *file_handle |
OUT: Pointer to the file handle being used by the low-level virtual file driver. |
H5Fis_hdf5(const char *name
)
H5Fis_hdf5 determines whether a file is in
the HDF5 format.
const char *name |
IN: File name to check format. |
TRUE,
or 0 (zero), for FALSE.
Otherwise returns a negative value.
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
H5Fmount(hid_t loc_id,
const char *name,
hid_t child_id,
hid_t plist_id
)
H5Fmount mounts the file specified by
child_id onto the group specified by
loc_id and name using
the mount properties plist_id.
Note that loc_id is either a file or group identifier
and name is relative to loc_id.
hid_t loc_id |
IN: Identifier for of file or group in
which name is defined. |
const char *name |
IN: Name of the group onto which the
file specified by child_id
is to be mounted. |
hid_t child_id |
IN: Identifier of the file to be mounted. |
hid_t plist_id |
IN: Identifier of the property list to be used. |
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
H5Fopen(const char *name,
unsigned flags,
hid_t access_id
)
H5Fopen opens an existing file and is the primary
function for accessing existing HDF5 files.
The parameter access_id is a file access property
list identifier or H5P_DEFAULT if the
default I/O access parameters are to be used
The flags argument determines whether writing
to an existing file will be allowed.
The file is opened with read and write permission if
flags is set to H5F_ACC_RDWR.
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.
The return value is a file identifier for the open file;
this file identifier should be closed by calling
H5Fclose when it is no longer needed.
Special case -- Multiple opens:
A file can often be opened with a new H5Fopen
call without closing an already-open identifier established
in a previous H5Fopen or H5Fcreate
call. Each such H5Fopen 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 flags argument.
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.
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.
It is generally recommended that applications avoid multiple opens of the same file.
const char *name |
IN: Name of the file to access. |
unsigned flags |
IN: File access flags. Allowable values are:
|
hid_t access_id |
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
access_id.
Use H5P_DEFAULT for default file access properties. |
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
H5Freopen(hid_t file_id
)
H5Freopen returns a new file identifier for an
already-open HDF5 file, as specified by file_id.
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.
Note that there is no circumstance under which
H5Freopen can actually open a closed file;
the file must already be open and have an active
file_id. E.g., one cannot close a file with
H5Fclose (file_id) then use
H5Freopen (file_id) to reopen it.
The new file identifier should be closed by calling
H5Fclose when it is no longer needed.
hid_t file_id |
IN: Identifier of a file for which an additional identifier is required. |
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
H5Freset_mdc_hit_rate_stats(hid_t
file_id)
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.
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.
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.
hid_t file_id |
IN: Identifier of the target file. |
H5Fset_mdc_config(hid_t
file_id, H5AC_cache_config_t *config_ptr)
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.
hid_t file_id
|
IN: Identifier of the target file |
H5AC_cache_config_t *config_ptr
|
IN: Pointer to the instance of H5AC_cache_config_t containing the desired configuration. The fields of this structure are discussed below: |
| General configuration section: | |
int version
|
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). |
hbool_t rpt_fcn_enabled
|
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.
The report function is not supported code, and can be expected to change between versions of the library. Use it at your own risk. |
hbool_t set_initial_size
|
IN: Boolean flag indicating whether the cache should be forced to the user specified initial size. |
size_t initial_size
|
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) |
double min_clean_fraction
|
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.
The value must lie in the interval [0.0, 1.0]. 0.25 is a good place to start. |
size_t max_size
|
IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size. |
size_t min_size
|
IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select as the maximum cache size. |
long int epoch_length
|
IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good starting number. |
| Increment configuration section: | |
enum H5C_cache_incr_mode incr_mode
|
IN: Enumerated value indicating the operational mode
of the automatic cache size increase code. At present, only two
values are legal:
H5C_incr__off: Automatic cache size increase is disabled, and the remaining increment fields are ignored. H5C_incr__threshold: Automatic cache size increase is enabled using the hit rate threshold algorithm. |
double lower_hr_threshold
|
IN: Hit rate threshold used by the hit rate threshold
cache size increment algorithm.
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. This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good starting point. |
double increment
|
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.
The actual cache size increase will be clipped to satisfy the max_size specified in the general configuration, and possibly max_increment below. The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable value. If you set it to 1.0, you will effectively disable cache size increases. |
hbool_t apply_max_increment
|
IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size increases. |
size_t max_increment
|
IN: Maximum number of bytes by which cache size can be increased in a single step -- if applicable. |
| Decrement configuration section: | |
enum H5C_cache_decr_mode decr_mode
|
IN: Enumerated value indicating the operational
mode of the automatic cache size decrease code. At present,
the following values are legal:
H5C_decr__off: Automatic cache size decrease is disabled. H5C_decr__threshold: Automatic cache size decrease is enabled using the hit rate threshold algorithm. H5C_decr__age_out: Automatic cache size decrease is enabled using the ageout algorithm. H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm |
double upper_hr_threshold
|
IN: Hit rate threshold for the hit rate threshold and
ageout with hit rate threshold cache size decrement algorithms.
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. 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. This field must lie in the interval [0.0, 1.0]. For H5C_incr__threshold, .9995 or .99995 is a good place to start. For H5C_decr__age_out_with_threshold, .999 might be more useful. |
double decrement
|
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.
The actual cache size decrease will be clipped to satisfy the min_size specified in the general configuration, and possibly max_decrement below. The parameter must be be in the interval [0.0, 1.0]. If you set it to 1.0, you will effectively disable cache size decreases. 0.9 is a reasonable starting point. |
hbool_t apply_max_decrement
|
IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size decreases. |
size_t max_decrement
|
IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step -- if applicable. |
int epochs_before_eviction
|
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. |
hbool_t apply_empty_reserve
|
IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty reserve when decreasing cache size. |
double empty_reserve
|
IN: Empty reserve as a fraction of maximum cache
size if applicable.
When so directed, the ageout based algorithms will not decrease the maximum cache size unless the empty reserve can be met. The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start. |
H5Funmount(hid_t loc_id,
const char *name
)
H5Funmount
dissassociates the mount point's file
from the file mounted there. This function
does not close either file.
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.
Note that loc_id is either a file or group identifier
and name is relative to loc_id.
hid_t loc_id |
IN: File or group identifier for the location at which the specified file is to be unmounted. |
const char *name |
IN: Name of the mount point. |
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
|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual
H5IM H5LT H5PT H5TB H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes |