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:

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.