Chapter 4
HDF5 Groups and Links

4.1. Introduction

The core strengths of HDF5 are the capacity to handle large amounts of complex data and the flexibility to manage that data efficiently. The building blocks that give an HDF5 file its capacity and flexibility are groups and datasets. Datasets will be described in the next chapter. In this chapter, groups will be described, and since links are closely intertwined with groups, links will also be discussed.

Groups and links can be used to arrange data in a meaningful way. For example, objects (groups or datasets) that are used together can be grouped together. Data that comes from similar sources might also be grouped together.

When groups are nested, they create a hierarchy. This hierarchy is similar to the tree structure employed on UNIX file systems using directories and files and on Apple Macintosh and Microsoft Windows systems using folders and files. HDF5 groups are analogous to the directories and folders; HDF5 datasets are analogous to the files.

The structure of an HDF5 file can also be compared to a geographic map. Cities and towns are like datasets. They come in a wide variety of configurations. Roads are like links that help us get to datasets. Countries, states, and counties are like groups: they help us place the cities and towns where we live and work.

In the rest of this chapter, the following topics will be discussed:


4.2. Defining Groups and Links

Groups and links provide the way for application programs to navigate to datasets. A group is a collection of links. A link is a connection between a group and an object. When we use the term link, we mean a connection between a group and an object that is unidirectional, has a single source, and has a single target.

The purpose of this section is to describe the basic characteristics of groups and links.

4.2.1. Groups

A group is a collection of links. If we could peer inside a group, we would see a list of the links that are the members of the group.

Groups do not have names. When we speak of a group, we use the name of the link that is connected to the group.

Groups are used to organize objects. If we were organizing our data by year, we might set up groups for 2010, 2009, and 2008 data. To do this, our file might have three links named 2010, 2009, and 2008 in the root group. The groups that are the targets of these three links might have links to datasets that hold our data.

To work with groups, application programs use the Groups interface. The names of the function calls in this interface start with H5G.

4.2.2. The Root Group

When a file is created, a group that we call the root group is created. The root group is the designated starting point for access to objects in the file.

There is no name for this group just as there is no name applied to any object. When we write about the root group, when we need to specify the root group in a parameter, we use a slash, /.

Every group is created with a hard link. The link that is created with the root group is slightly different from other links in that it does not have a name and cannot be changed. This means the root group cannot be moved or deleted. See the “Hard and Symbolic Links” section for more information.

4.2.3. Link Paths

A link is a connection or association between a group and an object. A group is the source of the link, and the object is the target of the link.

Every link has a name, and no object has a name. When we talk about an object, we might call the object by the link's name. Suppose a group has a link named Y1, and the target of Y1 is a dataset. If we refer to the dataset as Y1, what we really mean is the dataset that is the target of the link called Y1. See the figure below.

As more data is added to our file, we can nest datasets within groups and groups within groups. As we add links to groups, we need to remember that link names need to be unique within each group.

To navigate to a group or dataset, we combine the links to the group or dataset into a link path. Link names can be used in more than one place as long as the link paths are unique.

A link path can be absolute or relative. An absolute link path starts at the root group. A relative link path starts from some other known position such as the current working group.

A link path looks like a path name in a file system tree structure. Each link name is separated from another link name by a slash, /. The link name following a slash is always a member of the object that is the target of the link name preceding that slash. For example, in the link path /GroupA/GroupB/Dataset1, the link GroupB is a member of the group that is the target of the link GroupA.

The first component in a link path may be any of the following:

Link names may be any string of ASCII or UTF-8 characters that do not contain a slash or a dot. These are reserved as noted above. However, users are advised to avoid the use of punctuation and non-printing characters in link names: these may create problems for other software.

In an absolute link path for an object, we start with a slash as the root group, and then we add other link names separated by slashes to get to the object. An example might be /GroupA/GroupB/Dataset1. What we are really saying when we write /GroupA/GroupB/Dataset1 is the following: to get to the dataset that is the target of the Dataset1 link, start at the root group, look for the link called GroupA, and follow it. The GroupA link is a member of the root group. Next, look for the link called GroupB, and follow it. GroupB is a member of the group that is the target of the link called GroupA. Finally, find the link called Dataset1 in the group that is the target of the link called GroupB, and follow it.

A relative link path starts from some group other than the root group. If the current working location in the file shown in the figure below is the group that is the target of the link YB, then the dataset that is the target of the Y3 link can be identified by the relative link path YC/Y3.

There may be multiple link paths to an object. In the figure below, the dataset that is the target of the absolute link path /YA/Y1 is the same dataset that is the target of the absolute link path /YA/YB/YC/Y3.

The dataset that is the target of the Y1 and Y3 links might be accessed using different relative link paths from the YB group (the group that is the target of the YB link). Possible relative link paths are YC/Y3 and YC/YD/Y1.

An HDF5 file with a directed graph group structure including a 
          circular reference
Figure 1. An HDF5 file with a directed graph group structure including a circular reference
Groups are represented by circles, links by arrows, and datasets by rectangles.

Note that relative link paths in HDF5 do not employ the ../ notation. The ../ notation is used in UNIX to indicate a parent directory and is not used in HDF5 to indicate a parent group.

Another feature to note in the figure above is what the link YD represents. Since the underlying structure of an HDF5 file is a directed graph, circular references such as YD are possible. If the structure of an HDF5 file kept to a strict tree structure like that used in file systems, then circular references would not be possible. In the figure above, the dataset specified by the /YA/Y1 link path could also be specified with the following link path: /YA/YB/YC/YD/Y1. Another example is the ZBB link in the “Examples of Groups and Links” section below.

4.2.4. Hard and Symbolic Links

There are two types of links: hard and symbolic. Hard links are constructed with a physical address, and symbolic links are constructed with names. Characteristics of hard and symbolic links are listed below.

Characteristics of a hard link:

Characteristics of a symbolic link:

For more information, see the “Reference Count” and “Creating Hard Links” sections below.

User-defined links might be hard or symbolic, or they might be some kind of combination. See the H5Lcreate_ud function call in the HDF5 Reference Manual.

4.2.5. Examples of Groups and Links

The figures below illustrate the range of possibilities for groups and links. In the figures, circles are used to represent groups, rectangles are used for datasets, and arrows are used for links.

In the figure below, the group structure is hierarchical in the same way a file system operates.

Strictly hierarchical HDF5 group structure
Figure 2. An HDF5 file with a strictly hierarchical group structure

In the figure below, the structure takes advantage of the directed graph’s allowance of circular references and illustrates an extreme case in which a group via link ZBB is a member of itself. A possible reference to a member dataset such as /ZA/ZB/ZBB/Z2 could be set up. Directed graph structures can become quite complex.

Directed graph HDF5 group structure with self-reference
Figure 3. An HDF5 file with a directed graph group structure and one group as a member of itself

The figure below shows an external link. The target of the link path /MA/MB/MC/NA/N2 is a dataset in FileN.h5.

An HDF5 file with a link to another HDF5 file
Figure 4. An HDF5 file with a symbolic link to another HDF5 file

4.2.6. Summary of Group and Link Characteristics

Here is a summary of group and link characteristics:

Groups

Links

See “Notes for Advanced Link Users” for more information.


4.3. Programming Model: Working with Groups and Links

The purpose of this section is to describe more specifically how common operations can be done.

The table below shows some common group and link operations and the function calls used. These operations are implemented in the H5G, the H5L, and the H5O APIs. See “Group and Link Function Summaries” below for more information.

Table 1. Common group, link, and object function calls

To do this operation:

Use this function call:

Create a group

H5Gcreate

Open a group

H5Gopen

Close a group

H5Gclose

Add an object to a group (create a link from a group to an object)

H5Lcreate_hard, H5Lcreate_soft, H5Lcreate_external

Remove an object from a group (remove from a group the link to an object)

H5Ldelete

Get the identifier for an object

H5Ovisit, H5Oget_info

Get the identifiers for all of the objects in a group

H5Ovisit

Get the name of a link

H5Lget_info

Get the names of all the links in a group

H5Literate, H5Lvisit

When a new object is created, the HDF5 Library executes the link operation in the background immediately after creating the object. In other words, the creation operation creates the object and creates the hard link that connects the object to a group.

4.3.1. Creating a Group

To create a group, use the H5Gcreate macro. When used, H5Gcreate creates a group, opens the group (returns an identifier that can be used in other operations), and creates a hard link.

To create a simple group, specify values for the loc_id and name parameters and use the default property list parameter value (H5P_DEFAULT) for the property list parameters. The loc_id parameter is used to specify the location identifier. The location identifier is the object identifier for the file or group where the new group will be connected. The value of the name parameter will be a link or link path. If the value of loc_id is a file identifier, then the value of the name parameter will be an absolute link path. If the value of loc_id is a group identifier, then the value of the name parameter should be a relative link path from the group specified with the loc_id parameter. See “Link Paths” and “Identifiers and Link Paths” for more information.

The code in the example below creates three groups.

The first group that is created is the target of the Data link. The Data link is a member of the root group, and the location identifier file_id is the object identifier for the file. The identifier for the file was returned to the application as a result of the file being opened in the second line of the example.

Two other groups are then created and linked to the group that is the target of the Data link. The first group uses the file identifier file_id and an absolute link path for the name of the link. The second group uses the group identifier group_id and a relative link path for the name of the link. The identifier group_id was returned when the group that is the target of the Data link was created.


  hid_t file;
  file = H5Fopen(....);

  group = H5Gcreate(file_id, "/Data", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
  group_new1 = H5Gcreate(file_id, "/Data/Data_new1", H5P_DEFAULT, H5P_DEFAULT, 
      H5P_DEFAULT);
  group_new2 = H5Gcreate(group_id, "Data_new2", H5P_DEFAULT, H5P_DEFAULT, 
      H5P_DEFAULT);
Example 1. Creating three new groups
The default property list parameter is H5P_DEFAULT.

The three groups created in the example above are shown in the figure below.

An HDF5 file with a link to another HDF5 file
Figure 5. Creating groups

Programming reminder

Applications should keep track of every identifier that is returned to the application. After the application is finished using an object or file, the appropriate close function call should be executed with the identifier of the object or file that will be closed. See “Closing a Group” for more information.

4.3.2. Opening a Group

It is often useful to explicitly open a group when working with objects that are the targets of links that are members of that group. To open a group, use the H5Gopen macro.

The example below refers to the groups in Figure 5 above and illustrates different ways to open groups. Opening a dataset is a similar process.

To open an object using a relative link path, an application must first open the group or file on which the relative link path is based. In the first line of the example below, a previously-acquired file identifier, file_id, is used to open the group that is the target of the /Data link path, and then the returned group identifier, group_id, and a relative link path, Data_new1, are used to open the group that is the target of the Data_new1 link.

To open an object using an absolute link path, the application can use the file identifier, file_id, and an absolute link path. In the third line of the example below, file_id is used with /Data/Data_new2 to open the group that is the target of the Data_new2 link.


  group = H5Gopen(file_id, "/Data", H5P_DEFAULT);
  group1 = H5Gopen(group_id, "Data_new1", H5P_DEFAULT);
  group2 = H5Gopen(file_id, "/Data/Data_new2", H5P_DEFAULT);
Example 2. Open groups with relative and absolute link paths

4.3.3. Creating a Dataset

The process of creating a dataset is like the process of creating a group that was discussed above. When a dataset is created, a hard link to it is automatically created. The link will be a member of a group, and when we talk about the dataset, we will use the name of the link to refer to the dataset. As with groups, a dataset may be created in a group by specifying an absolute link path or a relative link path. The example below illustrates both approaches to creating a dataset in the group that is the target of the /Data link. The absolute link path to the first dataset is /Data/CData. The H5Dcreate macro uses a previously-acquired file_id and the default property list parameter H5P_DEFAULT. For the second dataset, the example first opens the group which will be the source of the link to the dataset, and then uses the group_id and the relative link Cdata2 to create and locate the dataset.


   dataspace = H5Screate_simple(RANK, dims, NULL);
   dataset1 = H5Dcreate(file_id, "/Data/CData", H5T_NATIVE_INT,
                     dataspace, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);

   group = H5Gopen(file_id, "/Data", H5P_DEFAULT);
   dataset2 = H5Dcreate(group_id, "Cdata2", H5T_NATIVE_INT,
                     dataspace, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
Example 3. Create datasets using absolute and relative link paths

4.3.4. Closing a Group

To ensure the integrity of HDF5 objects and to release system resources, an application should always call the appropriate close function when it is through working with an HDF5 object. In the case of groups, H5Gclose ends access to the group and releases any resources the HDF5 Library has maintained in support of that access including the group identifier.

As illustrated in the example below, all that is required for an H5Gclose call is the group identifier acquired when the group was opened. There are no relative versus absolute link path considerations.


  herr_t status;
  status = H5Gclose(group_id);
Example 4. Close a group

A non-negative return value indicates that the group was successuflly closed and the resources released; a negative return value indicates that the attempt to close the group or release resources failed.

4.3.5. Creating Hard Links

When a group or a dataset is created, a hard link is also created. This hard link gives the group or dataset a location in the file. After a group or dataset is created, additional hard links can be explicitly added by means of the H5Lcreate_hard function call to improve access and resource efficiency. See the “Defining Groups and Links” section for more information.

The code in the example below illustrates the creation of a hard link named Y3. Once that link is created, the dataset that is the target of the absolute link path /YA/Y1 can also be accessed by means of the absolute link path /YA/YB/YC/Y3.

Here are some comments for each line in the example below.

  1. The file is opened. The identifier file_id is returned.
  2. The group that is the target of the /YA/YB/YC link is opened and returns the group_id identifier.
  3. The Y3 link is created. The file_id identifier and the absolute link path /YA/Y1 are used to specify the dataset that will be the target of the new link. The group_id identifier specifies the group that is the target of the /YA/YB/YC link is the source of the new link. The new link is named Y3. The default property list value (H5P_DEFAULT) is used for the property list parameters.
  4. This line shows an alternate way to create Y3. The difference between this line and the one above it is the file_id is used with an absolute link path to define the new link.

    file = H5Fopen(....);
    group = H5Gopen(file_id, "/YA/YB/YC", H5P_DEFAULT);
    
    status = H5Lcreate_hard(file_id, "/YA/Y1", group_id, "Y3", 
               H5P_DEFAULT, H5P_DEFAULT)

    status = H5Lcreate_hard(file_id, "/YA/Y1", file_id, "/YA/YB/YC/Y3", 
               H5P_DEFAULT, H5P_DEFAULT)

Example 5. Create a hard link

Create a hard link
Figure 6. Creating hard links

4.3.6. Deleting a Link

The H5Ldelete function call can be used to remove hard, soft, external, and user-defined links.

The example below refers to the link named Y3 that was created in the section above and shows how to remove a link using a relative link path and an absolute link path. The first line uses the group_id identifier for the group that is the source of the link, the name of the link, Y3, and the default property list parameter, H5P_DEFAULT. The second line uses the file_id identifier for the file, an absolute link path, and the default property list parameter. Only the final link in the absolute link path will be deleted.


    status = H5Ldelete(group_id, "Y3", H5P_DEFAULT);
    
    status = H5Ldelete(file_id, "/YA/YB/YC/Y3", H5P_DEFAULT);

Example 6. Delete a link

How to avoid deleting the last hard link

When the last hard link to an object is deleted, the object is no longer accessible. Note that H5Ldelete will not prevent you from deleting the last link to an object. To see if an object has only one link, use the H5Oget_info function. If the value of the rc (reference count) field in object_info is greater than 1, then a link to the object can be deleted without making the object inaccessible.

It is possible to delete the last hard link to an object and not make the object inaccessible. Suppose your application opens a dataset and then deletes the last hard link to the dataset. While the dataset is open, your application still has a connection to the dataset through the identifier returned when the dataset was opened. If your application creates a hard link to the dataset before it closes the dataset, then the dataset will still be accessible after the dataset is closed.

4.3.7. Creating Symbolic Links

Symbolic links are based on names and not on physical file addresses. Symbolic links are similar to the soft links, aliases, and shortcuts that are used with various operating systems. Programmers can use symbolic links to more easily work with any long link paths they may be using and to work with objects in other HDF5 files. There are two kinds of symbolic links: soft and external. Soft links are used within a single file. External links are used to connect files.

A big difference between symbolic links and hard links is the status of the target when the link is created. The target of a hard link must exist when the hard link is created. The target of a symbolic link may or may not exist when the link is created. If a symbolic link is created and the target does not exist, the link is said to dangle or to be a dangling link. So, symbolic links are more flexible than hard links.

To create a soft link, use the H5Lcreate_soft function call. The function call has five parameters. The last two are property lists. In the example below, the default property list value H5P_DEFAULT is used. The first three parameters are called in the HDF5 Reference Manual target_path, link_loc_id, and link_name.

The value of target_path is a link path to the target of the soft link. This is not the soft link. This is what the soft link resolves to when the soft link is used. The links in this link path may or may not exist when the soft link is created, but the links and any intermediate groups in this link path must exist when the soft link is first used in order for the soft link to work.

The value of link_loc_id is a file identifier or a group identifier. If the value of this parameter is a file identifier, then the values of the target_path and link_name parameters should be absolute link paths. If the value of this parameter is a group identifier, then the values of the target_path and link_name parameters could be either relative or absolute link paths. A relative link path would start from the group identifier's group.

The value of link_name is the name of the new soft link. In the example below, the new soft link is called 2010.

The example below creates a soft link called 2010 with a link_loc_id of file_id and a target_path of /YA/YB/YC/Y3. The example then opens the dataset that is the target of the soft link.


  status = H5Lcreate_soft("/YA/YB/YC/Y3", file_id, "/2010", H5P_DEFAULT, H5P_DEFAULT);

  dataset = H5Dopen(file_id, "/2010", H5P_DEFAULT);
  
Example 7. Create a soft link

The figure below illustrates the new soft link created in the example above.

Creating a soft link
Figure 7. Creating a soft link
Groups are represented by circles, links by arrows, and datasets by rectangles.

To create an external link, use the H5Lcreate_external function call. The parameters used with H5Lcreate_external are the same as those used with H5Lcreate_soft except that an HDF5 file is also specified. See the HDF5 Reference Manual for more information.

In release 1.8.7, a cache was added to hold the names of files accessed via external links. The size of this cache can be changed to help improve performance. For more information, see the entry in the HDF5 Reference Manual for the H5Pset_elink_file_cache_size function call.

See the “Notes for Advanced Link Users” section for more information.

4.3.8. Discovering Information about Objects

There is often a need to retrieve information about a particular object. The H5Lget_info and H5Oget_info functions fill this niche by returning a description of the object or link in an H5L_info_t or H5O_info_t structure.

4.3.9. Discovering Objects in a Group

To examine all the objects or links in a group, use the H5Literate or H5Ovisit functions to examine the objects, and use the H5Lvisit function to examine the links. The H5Literate function is useful both with a single group and in an iterative process that examines an entire file or section of a file (such as the contents of a group or the contents of all the groups that are members of that group) and acts on objects as they are encountered. The H5Ovisit function recursively visits all objects accessible from a specified object. The H5Lvisit function recursively visits all the links starting from a specified group.

4.3.10. Discovering all of the Objects in the File

The structure of an HDF5 file is self-describing, meaning that an application can navigate an HDF5 file to discover and understand all the objects it contains. This is an iterative process wherein the structure is traversed as a graph, starting at one node and recursively visiting linked nodes. To explore the entire file, the traversal should start at the root group.

4.3.11. Using h5dump

The h5dump application program is a command-line utility that is distributed with HDF5. It can be used to inspect the contents of an HDF5 file. It can show the structure of a file so that you can determine where to create an object or so that you can verify that your application program actually created an object.

In the case of the new group created in the “Creating a group” section, the following h5dump command will display the contents of FileA.h5:

h5dump FileA.h5 

Assuming that the discussed objects, GroupA and GroupB are the only objects that exist in FileA.h5, the output will look something like the following:

HDF5 "FileA.h5" {
GROUP "/" {
GROUP GroupA {
GROUP GroupB {
}
}
}
}

The h5dump program is described on the Tools page of the HDF5 Reference Manual.

The HDF5 DDL grammar is described in the document DDL in BNF for HDF5, an element of this HDF5 User’s Guide.



4.4. Examples of Group Structures

This section presents several samples of possible HDF5 group structures.

  
a) The file contains three groups: the root group, /group1, and /group2.    b) The dataset dset1 (or /group1/dset1) is created in /group1.
  
c) A link named dset2 is created in /group2.    d) The dset1 link is removed. The dataset is still in the file, but can be accessed only as /group2/dset2.
Figure 8. Some group structures

The figure above shows examples of the structure of a file with three groups and one dataset. The file in Figure 8a contains three groups: the root group and two member groups. In Figure 8b, a dataset has been created and linked to /group1 with the link named dset1. In Figure 8c, a link named dset2 from /group2 to the dataset has been added. Note that there is only one copy of the dataset; there are two links to it, and it can be accessed either as /group1/dset1 or as /group2/dset2. Figure 8d above illustrates that one of the two links to the dataset can be deleted. In this case, the link from /group1 has been removed. The dataset itself has not been deleted; it is still in the file, but it can only be accessed as /group1/dset2.

  
a) dset1 has two names: /group2/dset1 and /group1/GXX/dset1.    b) dset1 again has two names: /group1/dset1 and /group1/dset2.
  
c) dset1 has three names: /group1/dset1, /group2/dset2, and /group1/GXX/dset2.    d) dset1 has many available path names.
Figure 9. More sample group structures

The figure above illustrates loops in an HDF5 group structure. The file in Figure 9a contains three groups and a dataset. The group that is the target of the group2 link is a member of the root group and is also a member of the group that is the target of the group1 link. The group that is the target of the group2 link can be accessed by either of two link paths: /group2 or /group1/GXX. Similarly, the dataset can be accessed by these link paths: /group2/dset1 or /group1/GXX/dset1.

Figure 9b illustrates a different case: the dataset is the target of two links that are both members of the same group. In this case, the dataset again has two names: /group1/dset1 and /group1/dset2.

In Figure 9c, the dataset that is the target of the dset1 link is a member of two groups. The dataset has three absolute link paths: /group1/dset1, /group2/dset2, and /group1/GXX/dset2.

In Figure 9d, two of the groups are members of each other, and the dataset is a member of both groups. In this case, there are an infinite number of paths to the dataset because GXX and GYY can be traversed any number of times on the way from the root group, /, to the dataset. This can yield a link path such as /group1/GXX/GYY/GXX/GYY/GXX/dset2.

  
a) The file contains only hard links.    b) The dset2 soft link is added.
  
c) A soft link named dset3 is added with a target that does not yet exist.    d) The target of the soft link is created or linked.
Figure 10. Hard and soft links

The figure above takes us into the realm of soft links. The original file, in Figure 10a, contains only three hard links. In Figure 10b, a soft link named dset2 has been created. The source of the new link is the group that is the target of the group2 link. The target of the new link is also the target of the /group1/dset1 link path.

In Figure 10c, another soft link, dset3, has been created in the group that is the target of the group2 link. The target dset3 does not yet exist. That target object has been added in Figure 10d along with the hard link dset. The target dataset is now accessible as either /group2/dset or /group2/dset3.


4.5. Group and Link Function Summaries

Function calls that can be used with groups (H5G functions) and property list functions that can used with groups (H5P functions) are listed below. A number of group functions have been deprecated. Most of these have been replaced by link (H5L) or object (H5O) functions. These replacement functions are also listed below. For more information on any of these interfaces or functions, see the HDF5 Reference Manual.


Function Listing 1. Group functions (H5G)
C Function
Fortran Function
Purpose
H5Gcreate
h5gcreate_f
Creates and opens a new group. The C function is a macro: see “API Compatibility Macros in HDF5.”
H5Gcreate_anon
h5gcreate_anon_f
Creates and opens a new group without linking it into the file structure.
H5Gopen
h5gopen_f
Opens an existing group. The C function is a macro: see “API Compatibility Macros in HDF5.”
H5Gclose
h5gclose_f
Closes the specified group.
H5Gget_create_plist
h5gget_create_plist_f
Gets a group creation property list identifier.
H5Gget_info
h5gget_info_f
Retrieves information about a group. Use instead of H5Gget_num_objs.
H5Gget_info_by_idx
h5gget_info_by_idx_f
Retrieves information about a group according to the groupís position within an index.
H5Gget_info_by_name
h5gget_info_by_name_f
Retrieves information about a group.
(none)
h5gget_obj_info_idx_f
Returns name and type of the group member identified by its index. Use with the h5gn_members_f function. h5gget_obj_info_idx_f and h5gn_members_f are the Fortran equivalent of the C function H5Literate.
(none)
h5gn_members_f
Returns the number of group members. Use with the h5gget_obj_info_idx_f function.

Function Listing 2. Link (H5L) and object (H5O) functions
C Function
Fortran Function
Purpose
H5Lcreate_hard
h5lcreate_hard_f
Creates a hard link to an object. Replaces H5Glink and H5Glink2.
H5Lcreate_soft
h5lcreate_soft_f
Creates a symbolic link to an object in the same file. Replaces H5Glink and H5Glink2.
H5Lcreate_external
h5lcreate_external_f
Creates a symbolic link to an object in a different file. Replaces H5Glink and H5Glink2.
H5Lcreate_ud
(none)
Creates a user-defined link.
H5Lget_val
(none)
Returns the value of a symbolic link. Replaces H5Gget_linkval.
H5Literate
(none)
Iterates through links in a group. Replaces H5Giterate. See also H5Ovisit and H5Lvisit.
H5Lget_info
h5lget_info_f
Returns information about a link. Replaces H5Gget_objinfo.
H5Oget_info
(none)
Retrieves the metadata for an object. Replaces H5Gget_objinfo.
H5Lget_name_by_idx
h5lget_name_by_idx_f
Retrieves name of the nth link in a group according to the order within a specified field or index. Replaces H5Gget_objname_by_idx.
H5Oget_info_by_idx
(none)
Retrieves the metadata for an object which is identified by an index position. Replaces H5Gget_objtype_by_idx.
H5Oset_comment
(none)
Sets the comment for specified object. Replaces H5Gset_comment.
H5Oget_comment
(none)
Gets the comment for specified object. Replaces H5Gget_comment.
H5Ldelete
h5ldelete_f
Removes a link from a group. Replaces H5Gunlink.
H5Lmove
h5lmove_f
Renames a link within an HDF5 file. Replaces H5Gmove and H5Gmove2.

Function Listing 3. Group creation property list functions (H5P)
C Function
Fortran Function
Purpose
H5Pall_filters_avail
(none)
Verifies that all required filters are available.
H5Pget_filter
h5pget_filter_f
Returns information about a filter in a pipeline. The C function is a macro: see “API Compatibility Macros in HDF5.”
H5Pget_filter_by_id
h5pget_filter_by_id_f
Returns information about the specified filter. The C function is a macro: see “API Compatibility Macros in HDF5.”
H5Pget_nfilters
h5pget_nfilters_f
Returns the number of filters in the pipeline.
H5Pmodify_filter
h5pmodify_filter_f
Modifies a filter in the filter pipeline.
H5Premove_filter
h5premove_filter_f
Deletes one or more filters in the filter pipeline.
H5Pset_deflate
h5pset_deflate_f
Sets the deflate (GNU gzip) compression method and compression level.
H5Pset_filter
h5pset_filter_f
Adds a filter to the filter pipeline.
H5Pset_fletcher32
h5pset_fletcher32_f
Sets up use of the Fletcher32 checksum filter.
H5Pset_fletcher32
h5pset_fletcher32_f
Sets up use of the Fletcher32 checksum filter.
H5Pset_link_phase_change
h5pset_link_phase_change_f
Sets the parameters for conversion between compact and dense groups.
H5Pget_link_phase_change
h5pget_link_phase_change_f
Queries the settings for conversion between compact and dense groups.
H5Pset_est_link_info
h5pset_est_link_info_f
Sets estimated number of links and length of link names in a group.
H5Pget_est_link_info
h5pget_est_link_info_f
Queries data required to estimate required local heap or object header size.
H5Pset_nlinks
h5pset_nlinks_f
Sets maximum number of soft or user-defined link traversals.
H5Pget_nlinks
h5pget_nlinks_f
Retrieves the maximum number of link traversals.
H5Pset_link_creation_order
h5pset_link_creation_order_f
Sets creation order tracking and indexing for links in a group.
H5Pget_link_creation_order
h5pget_link_creation_order_f
Queries whether link creation order is tracked and/or indexed in a group.
H5Pset_create_intermediate_group
h5pset_create_inter_group_f
Specifies in the property list whether to create missing intermediate groups.
H5Pget_create_intermediate_group
(none)
Determines whether the property is set to enable creating missing intermediate groups.
H5Pset_char_encoding
h5pset_char_encoding_f
Sets the character encoding used to encode a string. Use to set ASCII or UTF-8 character encoding for object names.
H5Pget_char_encoding
h5pget_char_encoding_f
Retrieves the character encoding used to create a string.


Function Listing 4. Other external link functions
C Function
Fortran Function
Purpose
H5Pset/get_elink_file_cache_size
(none)
Sets/retrieves the size of the external link open file cache from the specified file access property list.
H5Fclear_elink_file_cache
(none)
Clears the external link open file cache for a file.


4.6. Notes for Advanced Link Users

The purpose of this section is to provide extra information about links.

4.6.1. Link Indexing and Compact Group Storage

In HDF5 Release 1.8.0, a second link indexing and group storage format was added. The new format enables more efficient compact storage for very small groups, improved link indexing for large groups, and other advanced features. The original link indexing format - links are stored in a B-tree in the group’s local heap - remains the default. The new implementation is required for external and user-defined links and also enables the use of link names consisting of non-ASCII character sets. For more information, see the “Group Implementations in HDF5” section in the “H5G: Group Interface” section in the HDF5 Reference Manual.

4.6.2. Reference Count

The library maintains for each object a count of the number of hard links that have the object as their target. This is the reference count. When the object is created, a hard link is also created, and the reference count for the object is set to one. The reference count for an object is incremented or decremented each time a hard link with the object as the target is created or deleted. If an object becomes the target of a symbolic link, the reference count will not be changed. Objects that have a reference count of zero are eligible for deletion. If the reference count goes to zero, the library does not immediately remove the object. The object will be removed during the next running of the h5repack tool. For more information on the reference count, see the H5Oincr_refcount function call in the HDF5 Reference Manual.

4.6.3. Identifiers and Link Paths

Identifiers are generated and returned to an application when a group or file is created or opened. Identifiers are then used in the loc_id parameter along with link paths in the name parameter of function calls to create or open other groups and links. Link paths can be either absolute or relative. The purpose of this section is to describe the possible kinds of identifiers and the appropriate link path type for each kind of identifier.

File identifier and absolute link path. When a file is created or opened by an application, a file identifier is returned. When the file identifier is used in a function call, the name parameter should specify an absolute link path. With the file identifier and an absolute link path, the function call will be able to identify the file to work on and the location of the object from the root group. To operate on the root group, use a file identifier and a slash, /.

Group identifer and relative link path. When a group is created or opened, a group identifier is returned. When the group identifier is used in a function call, the name parameter can specify either a relative link path or an absolute link path. With the group identifier and a relative link path, the function call will be able to identify the group and the location of the object from the group. With the group identifier and an absolute link path, the function call will be able to identify the file to work on and the location of the object from the root group.

Any identifier and absolute link path. With any identifier and an absolute link path, a function call can create or open a group or link that is not connected to the identifier. The function call uses the identifier to specify the file to work in and uses the absolute link path to specify the link to the created or opened group or dataset from the root group.

Programming reminder

An application should track every identifier that has been returned to it. When the application is finished using the resource that is associated with the identifier, the identifier should be released by closing the resource. For example, use H5Gclose to close a group, or use H5Oclose to close an object. See “Closing a Group” for more information.

4.6.4. Moving or Renaming an Object

When we talk about renaming or moving an object, we do not actually rename or move the object. An object does not have a name: the name comes from a link. An object cannot be moved. When the object is created, it is put in a permanent location in the file. What changes is the link path to the object.

One way to rename or move an object is to use the H5Lmove function call. This function call will delete the existing link and create a new link in one operation.

Another way to rename or move an object is to use the H5Ldelete function call and one of the H5Lcreate_* function calls. These function calls will delete the existing link and create a new link.

Exercise caution in the use of H5Lmove and H5Ldelete as these functions each include a step that deletes a link to an object. If the link that is removed is the only hard link to the object, that object will become permanently inaccessible in the file.

Scenario 1: Removing the last link

To avoid removing the last link to an object or otherwise making an object inaccessible, use the H5Oget_info function. Confirm that the value of the reference count field (rc) is greater than 1.

Scenario 2: Moving a link that isolates an object

Consider the following example. Assume that the group that is the target of the group2 link can only be accessed via the following absolute link path: /top_group/group1/group2/.

Suppose H5Lmove is used to move top_group to the group that is the target of the group2 link. Since top_group was the only route from the root group to group1 (the group that is the target of the group1 link), there is no longer a path by which we can access group1, group2, or any member datasets. And since top_group is now a member of group2, top_group itself and any member datasets have thereby also become inaccessible.

For more information on any of these functions, see the HDF5 Reference Manual.

4.6.5. Strong and Weak Links

Hard links have a physical address in a file and are kept track of through the reference count. Symbolic links are known by name and do not effect the reference count for an object. User-defined links blur this neat division of links into hard and symbolic types. A user-defined link might be built so that it changes the reference count like a hard link and so that it can dangle like a symbolic link.

In addition to hard and symbolic links, it might be also be useful to think about links as being strong or weak. A strong link effects the reference count of an object. Deleting the last strong link would make the object inaccessible. A hard link would be a strong link as would any user-defined link that effected the reference count. A weak link does not effect the reference count of an object. A weak link would be more flexible and ambiguous like symbolic links.





1It could be said that HDF5 extends the organizing concepts of a file system to the internal structure of a single file.