Last modified: 9 October 2014
Name: H5Gcreate_anon
Signature:
  hid_t `H5Gcreate_anon`( hid_t `loc_id`, hid_t `gcpl_id`, hid_t `gapl_id` )

Purpose:
  Creates a new empty group without linking it into the file structure.

Description:
  `H5Gcreate_anon` creates a new empty group in the file specified by `loc_id`. With default settings, `H5Gcreate_anon` provides similar functionality to that provided by `H5Gcreate`, with the differences described below.

  The new group’s creation and access properties are specified in `gcpl_id` and `gapl_id`, respectively.

  `H5Gcreate_anon` returns a new group identifier. This identifier must be linked into the HDF5 file structure with `H5Olink` or it will be deleted from the file when the file is closed.

  The differences between this function and `H5Gcreate1` are as follows:

  - `H5Gcreate1` does not provide for the use of custom property lists; `H5Gcreate1` always uses default properties.
  - `H5Gcreate_anon` neither provides the new group’s name nor links it into the HDF5 file structure; those actions must be performed separately through a call to `H5Olink`, which offers greater control over linking.
  - `H5Gcreate_anon` does not directly provide a hint mechanism for the group’s heap size. Comparable information can be included in the group creation property list `gcpl_id` through a `H5Pset_local_heap_size_hint` call.

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

Parameters:

  hid_t `loc_id` | IN: File or group identifier specifying the file in which the new group is to be created
  hid_t `gcpl_id` | IN: Group creation property list identifier (`H5P_DEFAULT` for the default property list)
  hid_t `gapl_id` | IN: Group access property list identifier (No group access properties have been implemented at this time; use `H5P_DEFAULT`.)

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

Fortran90 Interface: h5gcreate_anon_f

      SUBROUTINE h5gcreate_anon_f(loc_id, grp_id, hdferr, gcpl_id, gapl_id)

        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: loc_id   ! File or group identifier
        INTEGER(HID_T), INTENT(OUT) :: grp_id  ! Group identifier
        INTEGER, INTENT(OUT) :: hdferr         ! Error code
                                               ! 0 on success and -1 on failure
        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_anon_f

See Also:
  `H5Gcreate`
  `H5Olink`
  “Using Identifiers”

History:

  Release | C
  1.8.0 | Function introduced in this release.