Last modified: 15 May 2009
Name: H5Fcreate
Signature:
  hid_t `H5Fcreate`( const char *`name`, unsigned `flags`, hid_t `fcpl_id`, hid_t `fapl_id` )

Purpose:
  Creates an HDF5 file.

Description:
  `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.

Parameters:

  const char *`name` | IN: Name of the file to access.
  uintn `flags` | IN: File access flags. Allowable values are: `H5F_ACC_TRUNC` Truncate file, if it already exists, erasing all data previously stored in the file. `H5F_ACC_EXCL` Fail if file already exists. `H5F_ACC_TRUNC` and `H5F_ACC_EXCL` are mutually exclusive; use exactly one. An additional flag, `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.

Returns:
  Returns a file identifier if successful; otherwise returns a negative value.

Fortran90 Interface: h5fcreate_f

      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