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