Documentation

Types of link storage for groups

Unknown link storage type

Links in group are stored with a "symbol table" (this is sometimes called "old-style" groups)

Links are stored in object header

Links are stored in fractal heap & indexed with v2 B-tree

Information struct for group (for h5g_get_info h5g_get_info_by_name h5g_get_info_by_idx)

Type of storage for links in group

Number of links in group

Current max. creation order value for group

Whether group has a file mounted on it

Creates a new group relative to loc_id, giving it the specified creation property list gcpl_id and access property list gapl_id. The link to the new group is created with the lcpl_id.

Parameters:

loc_id :: HId_t

File or group identifier

name :: CString

Absolute or relative name of the new group

lcpl_id :: HId_t

Property list for link creation

gcpl_id :: HId_t

Property list for group creation

gapl_id :: HId_t

Property list for group access

On success, returns the object ID of a new, empty group open for writing. Call h5g_close when finished with the group. Returns a negative value on failure.

hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id,
    hid_t gcpl_id, hid_t gapl_id);

Creates a new group relative to loc_id, giving it the specified creation property list gcpl_id and access property list gapl_id.

The resulting ID should be linked into the file with h5o_link or it will be deleted when closed.

Given the default setting, h5g_create_anon followed by h5o_link will have the same function as h5g_create2.

Parameters:

loc_id :: HId_t

File or group identifier

name :: CString

Absolute or relative name of the new group

gcpl_id :: HId_t

Property list for group creation

gapl_id :: HId_t

Property list for group access

Example: To create missing groups "A" and "B01" along the given path "AB01/grp" (TODO: translate to Haskell):

hid_t create_id = H5Pcreate(H5P_GROUP_CREATE);
int   status = H5Pset_create_intermediate_group(create_id, TRUE);
hid_t gid = H5Gcreate_anon(file_id, "/A/B01/grp", create_id, H5P_DEFAULT);

On success, returns the object ID of a new, empty group open for writing. Call h5g_close when finished with the group. On failure, returns a negative value.

hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id);

Opens an existing group for modification. When finished, call h5g_close to close it and release resources.

This function allows the user the pass in a Group Access Property List, which h5g_open1 does not.

On success, returns the object ID of the group. On failure, returns a negative value.

hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id);

Returns a copy of the group creation property list.

On success, returns the ID for a copy of the group creation property list. The property list ID should be released by calling h5p_close.

hid_t H5Gget_create_plist(hid_t group_id);

Retrieve information about a group.

Returns non-negative on success, negative on failure.

herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo);

Retrieve information about a group.

Returns non-negative on success, negative on failure.

herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo,
    hid_t lapl_id);

Retrieve information about a group, according to the order of an index.

Returns non-negative on success, negative on failure.

herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name,
    H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo,
    hid_t lapl_id);

Closes the specified group. The group ID will no longer be valid for accessing the group.

Returns non-negative on success, negative on failure.

herr_t H5Gclose(hid_t group_id);

An object has a certain type. The first few numbers are reserved for use internally by HDF5. Users may add their own types with higher values. The values are never stored in the file - they only exist while an application is running. An object may satisfy the isa function for more than one type.

Unknown object type

Object is a group

Object is a dataset

Object is a named data type

Object is a symbolic link

Object is a user-defined link

Reserved for future use

Reserved for future use

Reserved for future use

Type of h5g_iterate operator

typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data);

Information about an object

file number

object number

number of hard links to object

basic object type

modification time

symbolic link value length

Object header information

Creates a new group relative to loc_id and gives it the specified name. The group is opened for write access and it's object ID is returned.

The optional size_hint specifies how much file space to reserve to store the names that will appear in this group. If a non-positive value is supplied for the size_hint then a default size is chosen.

Note: Deprecated in favor of h5g_create2

On success, returns the object ID of a new, empty group open for writing. Call h5g_close when finished with the group. On failure, returns a negative value.

hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);

Opens an existing group for modification. When finished, call h5g_close to close it and release resources.

Note: Deprecated in favor of h5g_open2

On success, returns the Object ID of the group. On failure, returns a negative value.

hid_t H5Gopen1(hid_t loc_id, const char *name);

Creates a link between two existing objects. The new APIs to do this are h5l_create_hard and h5l_create_soft.

herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name,
    const char *new_name);

Creates a link between two existing objects. The new APIs to do this are h5l_create_hard and h5l_create_soft.

herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id, const char *new_name);

Moves and renames a link. The new API to do this is h5l_move.

herr_t H5Gmove(hid_t src_loc_id, const char *src_name,
    const char *dst_name);

Moves and renames a link. The new API to do this is h5l_move.

herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id,
    const char *dst_name);

Removes a link. The new API is h5l_delete / h5l_delete_by_idx.

herr_t H5Gunlink(hid_t loc_id, const char *name);

Retrieve's a soft link's data. The new API is h5l_get_val / h5l_get_val_by_idx.

herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size,
    char *buf/*out*/);

Gives the specified object a comment. The comment string should be a null terminated string. An object can have only one comment at a time. Passing nullPtr for the comment argument will remove the comment property from the object.

Note: Deprecated in favor of h5o_set_comment / h5o_set_comment_by_name

Returns non-negative on success / negative on failure

herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment);

Return at most bufsize characters of the comment for the specified object. If bufsize is large enough to hold the entire comment then the comment string will be null terminated, otherwise it will not. If the object does not have a comment value then no bytes are copied to the BUF buffer.

Note: Deprecated in favor of h5o_get_comment / h5o_get_comment_by_name

On success, returns the number of characters in the comment counting the null terminator. The value returned may be larger than the bufsize argument.

int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize,
    char *buf);

Iterates over the entries of a group. The loc_id and name identify the group over which to iterate and idx indicates where to start iterating (zero means at the beginning). The operator is called for each member and the iteration continues until the operator returns non-zero or all members are processed. The operator is passed a group ID for the group being iterated, a member name, and op_data for each member.

Note: Deprecated in favor of h5l_iterate

Returns the return value of the first operator that returns non-zero, or zero if all members were processed with no operator returning non-zero.

Returns negative if something goes wrong within the library, or the negative value returned by one of the operators.

herr_t H5Giterate(hid_t loc_id, const char *name, int *idx,
        H5G_iterate_t op, void *op_data);

Returns the number of objects in the group. It iterates all B-tree leaves and sum up total number of group members.

Note: Deprecated in favor of h5g_get_info

Returns non-negative on success, negative on failure

herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);

Returns information about an object. If follow_link is non-zero then all symbolic links are followed; otherwise all links except the last component of the name are followed.

Note: Deprecated in favor of h5l_get_info / h5o_get_info

Returns non-negative on success, with the fields of statbuf (if non-null) initialized. Negative on failure.

herr_t H5Gget_objinfo(hid_t loc_id, const char *name,
    hbool_t follow_link, H5G_stat_t *statbuf/*out*/);

Returns the name of objects in the group by giving index. If name is non-NULL then write up to size bytes into that buffer and always return the length of the entry name. Otherwise size is ignored and the function does not store the name, just returning the number of characters required to store the name. If an error occurs then the buffer pointed to by name (NULL or non-NULL) is unchanged and the function returns a negative value. If a zero is returned for the name's length, then there is no name associated with the ID.

Note: Deprecated in favor of h5l_get_name_by_idx

Returns non-negative on success, negative on failure.

ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char* name,
    size_t size);

Returns the type of objects in the group by giving index.

Note: Deprecated in favor of h5l_get_info / h5o_get_info

Returns h5g_GROUP, h5g_DATASET, or h5g_TYPE on success, or h5g_UNKNOWN on failure.

H5G_obj_t H5Gget_objtype_by_idx(hid_t loc_id, hsize_t idx);