| (NYI = Not yet implemented) | ||||
A group associates names with objects and provides a mechanism for mapping a name to an object. Since all objects appear in at least one group (with the possible exception of the root object) and since objects can have names in more than one group, the set of all objects in an HDF5 file is a directed graph. The internal nodes (nodes with out-degree greater than zero) must be groups while the leaf nodes (nodes with out-degree zero) are either empty groups or objects of some other type. Exactly one object in every non-empty file is the root object. The root object always has a positive in-degree because it is pointed to by the file boot block.
Every file identifier returned by H5Fcreate or
H5Fopen maintains an independent current working group
stack, the top item of which is the current working group. The
stack can be manipulated with H5Gset, H5Gpush,
and H5Gpop. The root object is the current working group
if the stack is empty.
An object name consists of one or more components separated from one another by slashes. An absolute name begins with a slash and the object is located by looking for the first component in the root object, then looking for the second component in the first object, etc., until the entire name is traversed. A relative name does not begin with a slash and the traversal begins with the current working group.
The library does not maintain the full absolute name of its current
working group because (1) cycles in the graph can make the name length
unbounded and (2) a group does not necessarily have a unique name. A
more Unix-like hierarchical naming scheme can be implemented on top of
the directed graph scheme by creating a ".." entry in each group that
points to its single predecessor; a getcwd function would
then be trivial.
H5Gcreate(hid_t loc_id,
const char *name,
size_t size_hint
)
H5Gcreate 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.
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.
loc_id
name
size_hint
H5Gopen(hid_t loc_id,
const char *name
)
H5Gopen opens an existing group with the specified name at
the specified location, loc_id.
The location is identified by a file or
group identifier, and returns a group identifier for the group.
The obtained group identifier should be released by calling
H5Gclose() when it is no longer needed.
loc_id
name
H5Gset (hid_t loc_id,
const char *name
)
H5Gset sets the group with the specified name
to be the current working group for the file which contains it.
This function sets the current working group by modifying the
top element of the current working group stack or, if the
stack is empty, by pushing a new element onto the stack.
The initial current working group is the root group.
loc_id can be a file identifier or a group identifier.
name is an absolute or relative name and is resolved as follows. Each file identifier
has a current working group, initially the root group of the
file. Relative names do not begin with a slash and are relative
to the specified group or to the current working group.
Absolute names begin with a slash and are relative to the file's
root group. For instance, the name /Foo/Bar/Baz is
resolved by first looking up Foo in the root group;
the name Foo/Bar/Baz is resolved by first looking
up the name Foo in the current working group.
Each file identifier maintains its own notion of the current
working group. If loc_id is a group identifier, the
file identifier is derived from the group identifier.
If a single file is opened with multiple calls to H5Fopen(),
which would return multiple file identifiers, then each
identifier's current working group can be set independently
of the other file identifiers for that file.
loc_id
name
H5Gpush (hid_t loc_id,
const char *name
)
H5Gpush pushes a new group
onto the stack, thus setting a new current working group.
loc_id
name
H5Gpop (hid_t loc_id)
H5Gpop restores the previous current working group by
popping an element from the current working group stack.
An empty stack implies that the current working group is the root
object. Attempting to pop an empty stack results in failure.
Each file identfier maintains its own notion of the current
working group. That is, if a single file is opened with
multiple calls to H5Fopen(), which returns multiple file
handles, then each identfier's current working group can be
set independently of the other file identfiers for that file.
If loc_id is a group identifier, it is used only to determine the
file identifier for the stack from which to pop the top entry.
loc_id
H5Gclose(hid_t group_id)
H5Gclose releases resources used by a group which was
opened by H5Gcreate() or H5Gopen().
After closing a group, the group_id cannot be used again.
Failure to release a group with this call will result in resource leaks.
group_id
H5Glink(hid_t loc_id,
H5G_link_t link_type,
const char *current_name,
const char *new_name
)
new_name
to current_name.
H5Glink creates a new name for an object that has some current
name, possibly one of many names it currently has.
If link_type is H5G_LINK_HARD, then
current_name must name an existing object and both
names are interpreted relative to loc_id, which is
either a file identifier or a group identifier.
If link_type is H5G_LINK_SOFT, then
current_name can be anything and is interpreted at
lookup time relative to the group which contains the final
component of new_name. For instance, if
current_name is ./foo,
new_name is ./x/y/bar, and a request
is made for ./x/y/bar, then the actual object looked
up is ./x/y/./foo.
loc_id
link_type
H5G_LINK_HARD and H5G_LINK_SOFT.
current_name
new_name
H5Gunlink(hid_t loc_id,
const char *name
)
name from the group graph and
decrements the link count for the object to which name points
H5Gunlink removes an association between a name and an object.
Object headers keep track of how many hard links refer to the object;
when the hard link count reaches zero, the object can be removed
from the file. Objects which are open are not removed until all
identifiers to the object are closed.
If the link count reaches zero, all file-space associated with the object will be reclaimed. If the object is open, the reclamation of the file space is delayed until all handles to the object are closed.
loc_id
name
H5Giterate(hid_t loc_id,
const char *name,
int *idx,
H5G_operator_t operator,
void *operator_data
)
H5Giterate iterates over the members of
name in the file or group specified with
loc_id.
For each object in the group, the operator_data
and some additional information, specified below, are
passed to the operator function.
The iteration begins with the idx object in the
group and the next element to be processed by the operator is
returned in idx. If idx
is NULL, then the iterator starts at the first group member;
since no stopping point is returned in this case, the iterator
cannot be restarted if one of the calls to its operator returns
non-zero.
The prototype for H5G_operator_t is:
typedef herr_t *(H5G_operator_t)(hid_t group_id,
const char *member_name, void *operator_data/*in,out*/);
group_id, the name of the current
object within the group, member_name, and the
pointer to the operator data passed in to H5Giterate,
operator_data.
The return values from an operator are:
loc_id
*name
*idx
operator
*operator_data
H5Gmove(hid_t loc_id,
const char *src,
const char *dst
)
H5Gmove renames an object within an HDF5 file.
The original name, src, is unlinked from the
group graph and the new name, dst, is inserted
as an atomic operation. Both names are interpreted relative
to loc_id, which is either a file or a group
identifier.
loc_id
*src
*dst
H5Gstat(hid_t loc_id,
const char *name,
hbool_t follow_link,
H5G_stat_t *statbuf
)
H5Gstat returns information about the
specified object through the statbuf argument.
loc_id (a file, group, or dataset identifier) and
name together determine the object.
If the object is a symbolic link and follow_link is
zero (0), then the information returned is that for the link itself;
otherwise the link is followed and information is returned about
the object to which the link points.
If follow_link is non-zero but the final symbolic link
is dangling (does not point to anything), then an error is returned.
The statbuf fields are undefined for an error.
The existence of an object can be tested by calling this function
with a null statbuf.
H5Gstat() fills in the following data structure:
typedef struct H5G_stat_t {
unsigned long fileno[2];
unsigned long objno[2];
unsigned nlink;
H5G_type_t type;
size_t linklen;
} H5G_stat_t
The fileno and objno fields contain
four values which uniquely itentify an object among those
HDF5 files which are open: if all four values are the same
between two objects, then the two objects are the same
(provided both files are still open).
The nlink field is the number of hard links to
the object or zero when information is being returned about a
symbolic link (symbolic links do not have hard links but
all other objects always have at least one).
The type field contains the type of the object,
one of H5G_GROUP, H5G_DATASET,
or H5G_LINK.
If information is being returned about a symbolic link then
linklen will be the length of the link value
(the name of the pointed-to object with the null terminator);
otherwise linklen will be zero.
Other fields may be added to this structure in the future.
loc_id
*name
follow_link
*statbuf
H5Gget_linkval(hid_t loc_id,
const char *name,
size_t size,
char *value
)
H5Gget_linkval returns size
characters of the link value through the value
argument if loc_id (a file or group identifier)
and name specify a symbolic link.
If size is smaller than the link value, then
value will not be null terminated.
This function fails if the specified object is not a symbolic link.
The presence of a symbolic link can be tested by passing zero for
size and NULL for value.
Use H5Gstat() to get the size of a link value.
loc_id
name
size
value
to be returned.
value
value,
if successful.
Otherwise returns FAIL (-1).
.... in left margin indicates where material was pulled out for use.
Hi Elena, here's a hodgepodge of stuff from html documents and
previous e-mails to answer your questions. Let me know if you need
further clarification.
....
.... [H5Gmove and H5Gunlink "NYI" comments were here]
....
Elena> We need little bit more user-friendly description of the H5Gstat and
Elena> H5Giterate functions.
>From a Mar 31 e-mail...
Robb>
....
.... [H5Giterate was here]
....
Robb>
Robb>
Robb> Group Information Functions:
....
.... [H5Gstat was here]
....
Robb>
Robb> herr_t H5Gname(hid_t group_id, char *name, size_t max_name_len);
Robb>
Robb> This function retrieves the name of the group for a group ID. The
Robb> name is returned in 'name' up to the length specified in 'max_name_len'.
Robb>
....
.... [H5Gget_linkval was here]
....
Robb>
Robb> H5Giterate example #1: The operator just looks at the member name and if it has an
Robb> `X' in it then it returns 1, otherwise return zero. Returning 1 (or any
Robb> positive value) causes the iterator to immediately return that value. If
Robb> none of the operators return 1 then the iterator eventually returns zero.
Robb>
Robb> 1 herr_t
Robb> 2 any_X (hid_t group_id/*unused*/,
Robb> 4 const char *member_name,
Robb> 5 void *op_data/*unused*/)
Robb> 6 {
Robb> 7 return strchr(member_name,'X') ? 1 : 0;
Robb> 8 }
Robb>
Robb> The iterator is invoked as:
Robb>
Robb> 9 int elmt=0;
Robb> 10 herr_t found = H5Giterate(file_id, "/foo", &elmt, any_X, NULL);
Robb> 11
Robb> 12 if (found<0) {
Robb> 13 printf ("Error iterating through group, at member %d\n", elmt);
Robb> 14 } else if (found) {
Robb> 15 printf ("Yes, member %d has an `X' in the name\n", elmt);
Robb> 16 } else {
Robb> 17 printf ("No member name contains an `X'\n");
Robb> 18 }
Robb>
Robb> H5Giterate example #2: An iterator to find an object whose name contains an `X'
Robb> This is the same as Example 1 except the operator also returns the name
Robb> that contains the `X'. We do this by passing a pointer to a `char*' as the
Robb> operator data and the operator will initialize that `char*' by strdup'ing
Robb> the object name.
Robb>
Robb> 1 herr_t
Robb> 2 find_X (hid_t group_id/*unused*/,
Robb> 4 const char *member_name,
Robb> 5 void *op_data/*out*/)
Robb> 6 {
Robb> 7 if (strchr(member_name,'X')) {
Robb> 8 *((char**)op_data) = strdup(member_name);
Robb> 9 return 1;
Robb> 10 }
Robb> 11 return 0;
Robb> 12 }
Robb>
Robb> To print all the names with an `X' the iterator is invoked
Robb> repeatedly until it returns zero.
Robb>
Robb> 13 int elmt = 0;
Robb> 14 char *name;
Robb> 15 while (H5Giterate(file_id, "/foo", &elmt, find_X, &name)) {
Robb> 16 puts (name);
Robb> 17 free (name);
Robb> 18 }
Robb>
Robb> H5Giterate example #3: Print all names that contain the specified character.
Robb> This is the same as Example 2 except we have to pass data into the operator
Robb> as well as get data out. We create a struct that contains the input data
Robb> (character to look for) and a slot for the output data (the name) and pass
Robb> that as the operator data.
Robb>
Robb> 1 typedef struct {
Robb> 2 char look_for;
Robb> 3 char *name;
Robb> 4 } find_char_t;
Robb> 5
Robb> 6 herr_t
Robb> 7 find_char (hid_t group_id/*unused*/,
Robb> 9 const char *member_name,
Robb> 10 find_char_t *op_data/*in,out*/)
Robb> 11 {
Robb> 13 if (strchr(member_name, op_data->look_for)) {
Robb> 14 op_data->name = strdup (member_name);
Robb> 15 return 1;
Robb> 16 }
Robb> 17 return 0;
Robb> 18 }
Robb>
Robb> To print all names that have a `Y' one would say
Robb>
Robb> 19 find_char_t op_data;
Robb> 20 int elmt = 0;
Robb> 21 op_data->look_for = 'Y';
Robb> 22 while (H5Giterate(file_id, "/foo", &elmt, find_X, &op_data)) {
Robb> 23 puts (op_data->name);
Robb> 24 free (op_data->name);
Robb> 25 }
Robb>
Robb> H5Giterate example #4: Efficient version of Example 3.
Robb> Examples 2 and 3 weren't too efficient because we kept interrupting the
Robb> iterator and it had to start over, albeit from the middle of the search. If
Robb> we could allow the iterator to go further then we wouldn't end up scanning
Robb> through the leaf nodes of the symbol table so often (searching for a
Robb> particular index, n, in a B-tree is an O(n) operation).
Robb> The H5Glist() function defined earlier returns the names of all the group
Robb> members which belong to a certain class, H5G_ALL, H5G_DATASET, or H5G_GROUP.
Robb> This example shows how to implement that functionality.
Robb> First we need a struct to describe the operator data and it's return
Robb> value(s). These correspond to the arguments presented for H5Glist, whose
Robb> definition is at the end of this example. (Since most of the work is done by
Robb> the operator we have to pass all this stuff back and forth through the
Robb> iterator).
Robb>
Robb> 1 typedef struct {
Robb> 2 size_t name_heap_size;
Robb> 3 char *name_heap;
Robb> 4 unsigned max_entries;
Robb> 5 char *names[];
Robb> 6 int type;
Robb> 7 unsigned cur_entries; /* How many names read so far */
Robb> 8 size_t cur_heap_size; /* How large is the heap */
Robb> 9 } H5G_list_t;
Robb>
Robb> The operator checks if an object is the right type, and if so adds it to
Robb> the return value arrays in the op_data struct. If the arrays become full
Robb> then the operator returns 1 to stop the iterator. The H5*isa() functions
Robb> return true iff the named object is of the * type (sans error handling).
Robb>
Robb> 10 herr_t
Robb> 11 H5G_list_op (hid_t grp_id, const char *memb_name,
Robb> 12 H5G_list_t *op_data)
Robb> 13 {
Robb> 14 char *out_name;
Robb> 15
Robb> 16 if (H5G_ALL==op_data->type ||
Robb> 17 (H5G_DATASET==op_data->type && H5Disa(grp_id,memb_name)) ||
Robb> 18 (H5G_GROUP==op_data->type && H5Gisa(grp_id, memb_name))) {
Robb> 19
Robb> 20 /* Is there enough room for the name in the heap? */
Robb> 21 if (op_data->cur_heap_size + strlen(memb_name) + 1 >
Robb> 22 op_data->name_heap_size) {
Robb> 23 return 2; /*try again later, see lines 59-62*/
Robb> 24 }
Robb> 25
Robb> 26 /* Add name to op_data return value arrays */
Robb> 27 out_name = op_data->name_heap + op_data->cur_heap_size;
Robb> 28 strcpy (out_name, memb_name);
Robb> 29 op_data->names[op_data->cur_entries] = out_name;
Robb> 30 op_data->cur_heap_size += strlen(memb_name) + 1;
Robb> 31
Robb> 32 /* Is the output full? */
Robb> 33 if (op_data->cur_entries >= op_data->max_entries) {
Robb> 34 return 1;
Robb> 35 }
Robb> 36 }
Robb> 37 return 0;
Robb> 38 }
Robb>
Robb> And finally, the definition of H5Glist():
Robb>
Robb> 39 int
Robb> 40 H5Glist (hid_t group_id, size_t name_heap_size, char *name_heap,
Robb> 41 int *start_idx, unsigned max_entries, char *names[],
Robb> 42 int type)
Robb> 43 {
Robb> 44 H5G_list_t op_data;
Robb> 45 herr_t status;
Robb> 46
Robb> 47 op_data->name_heap_size = name_heap_size;
Robb> 48 op_data->name_heap = name_heap;
Robb> 49 op_data->max_entries = max_entries;
Robb> 50 op_data->names = names;
Robb> 51 op_data->type = type;
Robb> 52 op_data->cur_entries = 0;
Robb> 53 op_data->cur_heap_size = 0;
Robb> 54
Robb> 55 if (0==cur_entries) return 0;
Robb> 56 status = H5Giterate (group_id, ".", start_idx, H5G_list_op,
Robb> 57 &op_data);
Robb> 58
Robb> 59 if (2==status && 0==op_data->cur_entries) {
Robb> 60 return -1; /*heap not large enough for even one name*/
Robb> 61 } else if (2==status) {
Robb> 62 --*start_idx; /*heap overflow, try again later*/
Robb> 63 } else if (status<0) {
Robb> 64 return status; /*iterator or operator error*/
Robb> 65 }
Robb> 66 return op_data->cur_entries;
Robb> 67 }
Robb>
Robb> The only other really interesting thing in this example are lines 23, 61,
Robb> and 62. We don't know if the name heap will overflow until we find a name to
Robb> put there. And then if it does, we need to be able to restart the iterator at
Robb> the entry that failed instead of the following entry.
Robb>
Robb> H5Giterate example #5: Print all the names of objects in a group, without any
Robb> buffers.
Robb> ---------------------
Robb>
Robb> herr_t print_names (hid_t grp_id, const char *name, void *opdata)
Robb> {
Robb> puts (name);
Robb> return 0;
Robb> }
Robb>
Robb> {
Robb> H5Giterate (file_id, "/foo/bar", NULL, print_names, NULL);
Robb> }
Elena> I believe there is a typo in the H5Pget_layout function in the source
Elena> code. Second argument ( H5D_layout_t *layout is missing....)
It's returned by value, not reference. It returns only the class of
layout and then, based on the class, you must call some other H5Pget
function like H5Pget_chunk() like this:
hid_t dcpl; /*dataset creation property list*/
hsize_t dims[32]; /*chunk dimensions*/
...
switch (H5Pget_layout(dcpl)) {
case H5D_CHUNKED:
H5Pget_chunk(dcpl, NELMTS(dims), dims);
break;
...
case H5D_LAYOUT_ERROR:
...
...
}
Quincy and html>
Quincy and html>
....
.... [Datatype material move to H5T.html]
....
Quincy and html>
Quincy and html>