Last modified: 29 July 2009
Name: H5Gcreate1
Signature:
  hid_t `H5Gcreate1`( hid_t `loc_id`, const char *`name`, size_t `size_hint` )

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

Notice:
  This function is renamed from `H5Gcreate` and deprecated in favor of the functions `H5Gcreate2` and `H5Gcreate_anon`, or the new macro `H5Gcreate`.

Description:
  `H5Gcreate1` creates a new group with the specified name at the specified location, `loc_id`. The location is identified by a file or group identifier. The name, `name`, must not already be taken by some other object and all parent groups must already exist.

  `name` can be a relative path based at `loc_id` or an absolute path from the root of the file. Use of this function requires that any intermediate groups specified in the path already exist.

  The length of a group name, or of the name of any object within a group, is not limited.

  `size_hint` is a hint for the number of bytes to reserve to store the names which will be eventually added to the new group. Passing a value of zero for `size_hint` is usually adequate since the library is able to dynamically resize the name heap, but a correct hint may result in better performance. If a non-positive value is supplied for `size_hint`, then a default size is chosen.

  The return value is a group identifier for the open group. This group identifier should be closed by calling `H5Gclose` when it is no longer needed.

  See `H5Gcreate_anon` for a discussion of the differences between `H5Gcreate1` and `H5Gcreate_anon`.

Parameters:

hid_t `loc_id` | IN: File or group identifier.
const char *`name` | IN: Absolute or relative name of the o new group.
size_t `size_hint` | IN: Optional parameter indicating the number of bytes to reserve for the names that will appear in the group. A conservative estimate could result in multiple system-level I/O requests to read the group name heap; a liberal estimate could result in a single large I/O request even when the group has just a few names. HDF5 stores each name with a null terminator.

Returns:
  Returns a valid group identifier for the open group if successful; otherwise returns a negative value.

Fortran90 Interface: See listing under `H5Gcreate`.

History:

  Release | C
  1.8.0 | Function `H5Gcreate` renamed to `H5Gcreate1` and deprecated in this release.