|
HDF5 documents and links Introduction to HDF5 HDF5 User Guide |
And in this document, the
HDF5 Reference Manual H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes Collective Calls in Parallel |
| (PDF of complete manual formatted as print volume) | |
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, however, 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 fcpl_id,
hid_t fapl_id
)
H5Fcreate is the primary function for creating
HDF5 files; it creates a new HDF5 file with the specified
name and property lists and specifies whether an existing file of
same name should be overwritten.
The name parameter specifies the name of the new file.
The flags parameter specifies whether an
existing file is to be overwritten.
It should be set to either H5F_ACC_TRUNC to
overwrite an existing file or H5F_ACC_EXCL,
instructing the function to fail if the file already exists.
New files are always created in read-write mode,
so the read-write and read-only flags, H5F_ACC_RDWR
and H5F_ACC_RDONLY, respectively, are not relevant
in this function.
Further note that a specification of H5F_ACC_RDONLY
will be ignored; the file will be created in read-write mode,
regardless.
More complex behaviors of file creation and access
are controlled through the file creation and file access
property lists, fcpl_id and fapl_id,
respectively. The value of H5P_DEFAULT for
any property list value indicates that the library should use
the default values for that 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 can be combined with one of the
above values using the bit-wise OR operator (`|'),
but it is used only by HDF5 Library developers; it is neither
tested nor supported for use in applications. |
hid_t fcpl_id |
IN: File creation property list identifier,
used when modifying default file meta-data.
Use H5P_DEFAULT to specify default file creation
properties. |
hid_t fapl_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
fapl_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, scope, 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
| Release | C | Fortran90 | |
| 1.6.3 | Function introduced in this release. | Fortran subroutine introduced in this release. |
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
| Release | C |
| 1.6.1 | Function introduced in this release. |
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 plus one (1) can then be assigned to size
for a second H5Fget_name call,
which will retrieve the actual name.
(The value passed in with the parameter size must be
one greater than size in bytes of the actual name in order to
accommodate the null terminator; if size is set to
the exact size of the name, the last byte passed back will
contain the null terminator and the last character will be
missing from the name passed back to the calling application.)
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
| Release | C | Fortran90 | |
| 1.6.3 | Function introduced in this release. | Fortran subroutine introduced in this release. |
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
(That is, H5F_OBJ_FILE |
H5F_OBJ_DATASET |
H5F_OBJ_GROUP |
H5F_OBJ_DATATYPE |
H5F_OBJ_ATTR)
|
H5F_OBJ_LOCAL
|
Restrict search to objects opened through current file identifier.
Note: H5F_OBJ_LOCAL does not stand alone;
it is effective only when used in combination with one or more
of the preceding types.
For example,
H5F_OBJ_DATASET
| H5F_OBJ_GROUP
| H5F_OBJ_LOCAL
would count all datasets and groups opened through the current file identifier. |
Multiple object types can be combined with the
logical 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
| Release | Change |
| 1.6.5 |
H5F_OBJ_LOCAL has been added as a qualifier
on the types of objects to be counted.
H5F_OBJ_LOCAL restricts the search to objects
opened through current file identifier. |
| 1.6.8 |
C function return type changed to ssize_t.
|
H5Fget_obj_ids(
hid_t file_id,
unsigned int types,
size_t 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. |
size_t 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
| Release | Change |
| 1.6.0 | C function introduced in this release. |
| 1.6.8 |
C function return type changed to ssize_t
and max_objs parameter datatype changed to
size_t. |
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. |
| Release | C |
| 1.6.0 | Function introduced in this release. |
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.
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 fapl_id
)
H5Fopen is the primary function for accessing
existing HDF5 files.
This function opens the named file in the specified access mode
and with the specified access property list.
Note that H5Fopen does not create a file
if it does not already exist;
see H5Fcreate.
The name parameter specifies the name of the file
to be opened.
The fapl_id parameter specifies the file access
property list. Use of H5P_DEFAULT specifies that
default I/O access properties are to be used
The flags parameter specifies whether the file
will be opened in read-write or read-only mode,
H5F_ACC_RDWR or H5F_ACC_RDONLY,
respectively.
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 be created. |
unsigned flags |
IN: File access flags. Allowable values are:
|
hid_t fapl_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
fapl_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
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 H5 H5A H5D H5E H5F H5G H5I H5P H5R H5S H5T H5Z Tools Datatypes Collective Calls in Parallel |
| (PDF of complete manual formatted as print volume) | |
