Chapter 6: HDF5 Objects and Identifiers

## Chapter 6
HDF5 Objects and Identifiers

### 6.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:

- Groups and group structure
- Links
- Programming with groups and links
- Retrieving information about objects in a group
- Discovery of the structure of an HDF5 file and the contained objects
- Examples of file structures
- Function calls provided for working with groups and links

### 6.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.

#### 6.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.

#### 6.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.

#### 6.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:

- The special character dot (., a period), the current group
- The special character slash (/), the root group
- The name of a link that is a member of the current group

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`.

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.

#### 6.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:

- A hard link is made with a physical address in the file
- A hard link occurs within a single file
- When a group or dataset is created, a hard link is also created
- At least one hard link exists for every group or dataset
- A hard link and the group or dataset that is the target of the link exist together (hard links cannot dangle)
- A hard link is created using `H5Lcreate_hard`
- A group or dataset may be the target of more than one hard link
- If a group or dataset is not the target of at least one hard link, then the group or dataset cannot be accessed, and the space occupied by the group or dataset will be reclaimed the next time the `h5repack` tool is run
- The target of a hard link will increase its reference count by one when the hard link is created, and the reference count will decline by one when the hard link is deleted

Characteristics of a symbolic link:

- A symbolic link uses a name rather than a physical address
- The target of a symbolic link can be changed
- There are two types of symbolic links: soft and external
- The target of a soft symbolic link (a soft link) will be a group or dataset within a file
- The target of an external symbolic link (an external link) will be a group or dataset in another file
- A symbolic link can exist with or without its target object (symbolic links can dangle)

- Suppose a symbolic link is created. The target object may or may not exist when the symbolic link is created. When an application opens the target object via the symbolic link, then either the target will be opened, or an error message will be generated.

- A symbolic link can be created with `H5Lcreate_soft` or `H5Lcreate_external`
- A group or dataset may be the target of more than one symbolic link
- The target of a symbolic link will not change its reference count when the symbolic link is created or deleted

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.

#### 6.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.

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.

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.

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

#### 6.2.6. Summary of Group and Link Characteristics

Here is a summary of group and link characteristics:

Groups

- Groups do not have names
- Groups hold links
- Groups can be empty
- Groups do not hold objects
- The root group is automatically created when the HDF5 file is created
- The root group cannot be deleted
- H5G function calls are part of the Groups interface

Links

- Each link has a name
- Link names are unique within a group
- The target of each link is only one group or dataset
- Each group or dataset is the target of at least one hard link
- A group or dataset may be the target of many links
- Links may create circular references
- A link path is made of the links that it takes to get to a group or a dataset
- The links in a link path are separated by slashes
- A link path may be absolute or relative
- A link may be hard or symbolic
- H5L function calls are part of the Links interface

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

### 6.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.

#### 6.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.

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.

#### 6.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

#### 6.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

#### 6.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.

#### 6.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

Figure 6. Creating hard links

#### 6.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.

#### 6.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.

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.

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

#### 6.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.

#### 6.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.

#### 6.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.

### 6.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.

### 6.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`.

### 6.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 F90 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 F90 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 F90 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.

### 6.6. Notes for Advanced Link Users

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

#### 6.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.

#### 6.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.

#### 6.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.

#### 6.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.

#### 6.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.