H5F_CREATE is the primary function for creating HDF5 files; it creates a new HDF5 file with the specified name and property lists.
name parameter specifies the name of the new file.
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_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,
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 H5F_CLOSE when it is no longer needed.
PLEASE be aware that by default when opening and then closing objects in an HDF5 file, the file close is delayed until ALL objects in the file are closed (in other words, a WEAK file close degree is used). This behavior can be changed by modifying the file close degree file access property list with H5P_SET_FCLOSE_DEGREE when the file is opened. See the H5P_SET_FCLOSE_DEGREE function for more information.
Special case -- File creation in the case of an already-open file:
If a file being created is already opened, by either a previous H5F_OPEN or H5F_CREATE call, the HDF5 library may or may not detect that the open file and the new file are the same physical file. (See H5F_OPEN regarding the limitations in detecting the re-opening of an already-open file.)
If the library detects that the file is already opened, H5F_CREATE will return a failure, regardless of the use of
If the library does not detect that the file is already opened and
H5F_ACC_TRUNC is not used, H5F_CREATE 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, H5F_CREATE 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 H5F_CREATE with an already opened file.