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

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.

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.

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.

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.

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.

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

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.

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.

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.

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);

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

Figure 5. Creating groups

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);

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);

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);

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.

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)

Figure 6. Creating hard links

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);

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);
  

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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