Last modified: 9 October 2014
Name: H5Gcreate
Signatures:

  hid_t `H5Gcreate`( hid_t `loc_id`, const char *`name`, size_t `size_hint` ) | [1]
  hid_t `H5Gcreate`( hid_t `loc_id`, const char *`name`, hid_t `lcpl_id`, hid_t `gcpl_id`, hid_t `gapl_id` ) | [2]

Purpose:
  Creates a new empty group and links it to a location in the file.

Description:
  `H5Gcreate` is a macro that is mapped to either `H5Gcreate1` or `H5Gcreate2`, depending on the HDF5 Library configuration and application compile-time compatibility macro mapping options.

  This macro is provided to facilitate application compatibility. For example:

  - The `H5Gcreate` macro will be mapped to `H5Gcreate1` and will use the `H5Gcreate1` syntax (first signature above) if the application is coded for HDF5 Release 1.6.x.
  - The `H5Gcreate` macro will be mapped to `H5Gcreate2` and will use the `H5Gcreate2` syntax (second signature above) if the application is coded for HDF5 Release 1.8.x.

  Macro use and compatibility macro mapping options are fully described in “API Compatibility Macros in HDF5.”

  When both the HDF5 Library and the application are built without specific compatibility macro mapping options, the default behavior occurs and `H5Gcreate` is mapped to the most recent version of the function, currently `H5Gcreate2`. If the library and/or application is compiled for Release 1.6 emulation, `H5Gcreate` will be mapped to `H5Gcreate1`.

  Function mapping flags can be used to override these settings on a function-by-function basis when the application is compiled. The `H5Gcreate` function mapping flags are shown:

  `h5cc` flag | macro maps to
  --- | ---
  `-DH5Acreate_vers=1` | `H5Acreate1`
  `-DH5Acreate_vers=2` | `H5Acreate2`

  A group created with this macro should be closed with `H5Gclose` when the group is no longer needed so that resource leaks will not develop.

  Interface history: Signature [1] above is the original `H5Gcreate` interface and the only interface available prior to HDF5 Release 1.8.0. This signature and the corresponding function are now deprecated but will remain directly callable as `H5Gcreate1`.

  Signature [2] above was introduced with HDF5 Release 1.8.0 and is the recommended and default interface. It is directly callable as `H5Gcreate2`.

  Deprecated functions may not be available in all installations of the HDF5 libary. See “API Compatibility Macros in HDF5” for details.

Fortran90 Interface: h5gcreate_f

      SUBROUTINE h5gcreate_f(loc_id, name, grp_id, hdferr, &
                              size_hint, lcpl_id, gcpl_id, gapl_id)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: loc_id   ! File or group identifier
        CHARACTER(LEN=*), INTENT(IN) :: name   ! Name of the group
        INTEGER(HID_T), INTENT(OUT) :: grp_id  ! Group identifier
        INTEGER, INTENT(OUT) :: hdferr         ! Error code
                                               ! 0 on success and -1 on failure
        INTEGER(SIZE_T), OPTIONAL, INTENT(IN) :: size_hint
                                               ! Parameter indicating the number of
                                               ! bytes to reserve for the names that
                                               ! will appear in the group.
                                               ! Note, set to OBJECT_NAMELEN_DEFAULT_F
                                               ! if using any of the optional
                                               ! parameters lcpl_id, gcpl_id,
                                               ! and/or gapl_id when not
                                               ! using keywords in specifying the
                                               ! optional parameters.
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: lcpl_id
                                               ! Property list for link creation
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gcpl_id
                                               ! Property list for group creation
        INTEGER(HID_T), OPTIONAL, INTENT(IN) :: gapl_id
                                               ! Property list for group access
      END SUBROUTINE h5gcreate_f

See Also:
  “Using Identifiers”

History:

  Release | C
  1.8.0 | The function `H5Gcreate` renamed to `H5Gcreate1` and deprecated in this release. The macro `H5Gcreate` and the function `H5Gcreate2` introduced in this release.