/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * Purpose: This file contains declarations which define macros for the
 *          H5G package.  Including this header means that the source file
 *          is part of the H5G package.
 */
#ifndef H5Gmodule_H
#define H5Gmodule_H

/* Define the proper control macros for the generic FUNC_ENTER/LEAVE and error
 *      reporting macros.
 */
#define H5G_MODULE
#define H5_MY_PKG     H5G
#define H5_MY_PKG_ERR H5E_SYM

/**  \page H5G_UG HDF5 Groups
 *
 * \section sec_group HDF5 Groups
 * \subsection subsec_group_intro Introduction
 * As suggested by the name Hierarchical Data Format, an HDF5 file is hierarchically structured.
 * The HDF5 group and link objects implement this hierarchy.
 *
 * In the simple and most common case, the file structure is a tree structure; in the general case, the
 * file structure may be a directed graph with a designated entry point. The tree structure is very
 * similar to the file system structures employed on UNIX systems, directories and files, and on
 * Apple and Microsoft Windows systems, folders and files. HDF5 groups are analogous
 * to the directories and folders; HDF5 datasets are analogous to the files.
 *
 * The one very important difference between the HDF5 file structure and the above-mentioned file
 * system analogs is that HDF5 groups are linked as a directed graph, allowing circular references;
 * the file systems are strictly hierarchical, allowing no circular references. The figures below
 * illustrate the range of possibilities.
 *
 * In the first figure below, the group structure is strictly hierarchical, identical to the file system
 * analogs.
 *
 * In the next two figures below, the structure takes advantage of the directed graph’s allowance of
 * circular references. In the second figure, GroupA is not only a member of the root group, /, but a
 * member of GroupC. Since Group C is a member of Group B and Group B is a member of Group
 * A, Dataset1 can be accessed by means of the circular reference /Group A/Group B/Group
 * C/Group A/Dataset1. The third figure below illustrates an extreme case in which GroupB is a
 * member of itself, enabling a reference to a member dataset such as /Group A/Group B/Group
 * B/Group B/Dataset2.
 *
 * <table>
 * <tr>
 * <td>
 * \image html Groups_fig1.gif "A file with a strictly hierarchical group structure"
 * </td>
 * </tr>
 * </table>
 *
 * <table>
 * <tr>
 * <td>
 * \image html Groups_fig2.gif "A file with a circular reference"
 * </td>
 * </tr>
 * </table>
 *
 * <table>
 * <tr>
 * <td>
 * \image html Groups_fig3.gif "A file with one group as a member of itself"
 * </td>
 * </tr>
 * </table>
 *
 * As becomes apparent upon reflection, directed graph structures can become quite complex;
 * caution is advised!
 *
 * The balance of this chapter discusses the following topics:
 * \li The HDF5 group object (or a group) and its structure in more detail
 * \li HDF5 link objects (or links)
 * \li The programming model for working with groups and links
 * \li HDF5 functions provided for working with groups, group members, and links
 * \li Retrieving information about objects in a group
 * \li Discovery of the structure of an HDF5 file and the contained objects
 * \li Examples of file structures
 *
 * \subsection subsec_group_descr Description of the Group Object
 * \subsubsection subsubsec_group_descr_object The Group Object
 * Abstractly, an HDF5 group contains zero or more objects and every object must be a member of
 * at least one group. The root group, the sole exception, may not belong to any group.
 *
 * <table>
 * <tr>
 * <td>
 * \image html Groups_fig4.gif "Abstract model of the HDF5 group object"
 * </td>
 * </tr>
 * </table>
 *
 * Group membership is actually implemented via link objects. See the figure above. A link object
 * is owned by a group and points to a named object. Each link has a name, and each link points to
 * exactly one object. Each named object has at least one and possibly many links to it.
 *
 * There are three classes of named objects: group, dataset, and committed datatype (formerly
 * called named datatype). See the figure below. Each of these objects is the member of at least one
 * group, which means there is at least one link to it.
 *
 * <table>
 * <tr>
 * <td>
 * \image html Groups_fig5.gif "Classes of named objects"
 * </td>
 * </tr>
 * </table>
 *
 * The primary operations on a group are to add and remove members and to discover member
 * objects. These abstract operations, as listed in the figure below, are implemented in the \ref H5G
 * APIs. For more information, @see @ref subsec_group_function.
 *
 * To add and delete members of a group, links from the group to existing objects in the file are
 * created and deleted with the link and unlink operations. When a new named object is created, the
 * HDF5 Library executes the link operation in the background immediately after creating the
 * object (in other words, a new object is added as a member of the group in which it is created
 * without further user intervention).
 *
 * Given the name of an object, the get_object_info method retrieves a description of the object,
 * including the number of references to it. The iterate method iterates through the members of the
 * group, returning the name and type of each object.
 *
 * <table>
 * <tr>
 * <td>
 * \image html Groups_fig6.gif "The group object"
 * </td>
 * </tr>
 * </table>
 *
 * Every HDF5 file has a single root group, with the name /. The root group is identical to any other
 * HDF5 group, except:
 * \li The root group is automatically created when the HDF5 file is created (#H5Fcreate).
 * \li The root group has no parent, but by convention has a reference count of 1.
 * \li The root group cannot be deleted (in other words, unlinked)!
 *
 * \subsubsection subsubsec_group_descr_model The Hierarchy of Data Objects
 * An HDF5 file is organized as a rooted, directed graph using HDF5 group objects. The named
 * data objects are the nodes of the graph, and the links are the directed arcs. Each arc of the graph
 * has a name, with the special name / reserved for the root group. New objects are created and then
 * inserted into the graph with a link operation that is automatically executed by the library;
 * existing objects are inserted into the graph with a link operation explicitly called by the user,
 * which creates a named link from a group to the object.
 *
 * An object can be the target of more than one link.
 *
 * The names on the links must be unique within each group, but there may be many links with the
 * same name in different groups. These are unambiguous, because some ancestor must have a
 * different name, or else they are the same object. The graph is navigated with path names,
 * analogous to Unix file systems. For more information, @see @ref subsubsec_group_descr_path.
 *
 * An object can be opened with a full path starting at the root group, or with a relative path and a
 * starting point. That starting point is always a group, though it may be the current working group,
 * another specified group, or the root group of the file. Note that all paths are relative to a single
 * HDF5 file. In this sense, an HDF5 file is analogous to a single UNIX file system.
 *
 * It is important to note that, just like the UNIX file system, HDF5 objects do not have names, the
 * names are associated with paths. An object has an object identifier that is unique within the file,
 * but a single object may have many names because there may be many paths to the same object.
 * An object can be renamed, or moved to another group, by adding and deleting links. In this case,
 * the object itself never moves. For that matter, membership in a group has no implication for the
 * physical location of the stored object.
 *
 * Deleting a link to an object does not necessarily delete the object. The object remains available
 * as long as there is at least one link to it. After all links to an object are deleted, it can no longer
 * be opened, and the storage may be reclaimed.
 *
 * It is also important to realize that the linking mechanism can be used to construct very complex
 * graphs of objects. For example, it is possible for an object to be shared between several groups
 * and even to have more than one name in the same group. It is also possible for a group to be a
 * member of itself, or to create other cycles in the graph, such as in the case where a child group is
 * linked to one of its ancestors.
 *
 * HDF5 also has soft links similar to UNIX soft links. A soft link is an object that has a name and
 * a path name for the target object. The soft link can be followed to open the target of the link just
 * like a regular or hard link. The differences are that the hard link cannot be created if the target
 * object does not exist and it always points to the same object. A soft link can be created with any
 * path name, whether or not the object exists; it may or may not, therefore, be possible to follow a
 * soft link. Furthermore, a soft link’s target object may be changed.
 *
 * \subsubsection subsubsec_group_descr_path HDF5 Path Names
 * The structure of the HDF5 file constitutes the name space for the objects in the file. A path name
 * is a string of components separated by slashes (/). Each component is the name of a hard or soft
 * link which points to an object in the file. The slash not only separates the components, but
 * indicates their hierarchical relationship; the component indicated by the link name following a
 * slash is a always a member of the component indicated by the link name preceding that slash.
 *
 * The first component in the path name may be any of the following:
 * \li The special character dot (., a period), indicating the current group
 * \li The special character slash (/), indicating the root group
 * \li Any member of the current group
 *
 * Component link names may be any string of ASCII characters not containing a slash or a dot
 * (/ and ., which are reserved as noted above). However, users are advised to avoid the use of
 * punctuation and non-printing characters, as they may create problems for other software. The
 * figure below provides a BNF grammar for HDF5 path names.
 *
 * <em>A BNF grammar for HDF5 path names</em>
 * \code
 *     PathName ::= AbsolutePathName | RelativePathName
 *     Separator ::= "/" ["/"]*
 *     AbsolutePathName ::= Separator [ RelativePathName ]
 *     RelativePathName ::= Component [ Separator RelativePathName ]*
 *     Component ::= "." | Characters
 *     Characters ::= Character+ - { "." }
 *     Character ::= {c: c Î { { legal ASCII characters } - {'/'} }
 * \endcode
 *
 * An object can always be addressed by either a full or an absolute path name, starting at the root
 * group, or by a relative path name, starting in a known location such as the current working
 * group. As noted elsewhere, a given object may have multiple full and relative path names.
 *
 * Consider, for example, the file illustrated in the figure below. Dataset1 can be identified by either
 * of these absolute path names:
 * <em>/GroupA/Dataset1</em>
 *
 * <em>/GroupA/GroupB/GroupC/Dataset1</em>
 *
 * Since an HDF5 file is a directed graph structure, and is therefore not limited to a strict tree
 * structure, and since this illustrated file includes the sort of circular reference that a directed graph
 * enables, Dataset1 can also be identified by this absolute path name:
 * <em>/GroupA/GroupB/GroupC/GroupA/Dataset1</em>
 *
 * Alternatively, if the current working location is GroupB, Dataset1 can be identified by either of
 * these relative path names:
 * <em>GroupC/Dataset1</em>
 *
 * <em>GroupC/GroupA/Dataset1</em>
 *
 * Note that relative path names in HDF5 do not employ the ../ notation, the UNIX notation
 * indicating a parent directory, to indicate a parent group.
 *
 * <table>
 * <tr>
 * <td>
 * \image html Groups_fig2.gif "A file with a circular reference"
 * </td>
 * </tr>
 * </table>
 *
 * \subsubsection subsubsec_group_descr_impl Group Implementations in HDF5
 * The original HDF5 group implementation provided a single indexed structure for link storage. A
 * new group implementation, as of HDF5 Release 1.8.0, enables more efficient compact storage
 * for very small groups, improved link indexing for large groups, and other advanced features.
 * <ul>
 * <li>The original indexed format remains the default. Links are stored in a B-tree in the
 * group’s local heap.</li>
 * <li>Groups created in the new compact-or-indexed format, the implementation introduced
 * with Release 1.8.0, can be tuned for performance, switching between the compact and
 * indexed formats at thresholds set in the user application.
 * <ul>
 * <li>The compact format will conserve file space and processing overhead when
 * working with small groups and is particularly valuable when a group contains
 * no links. Links are stored as a list of messages in the group’s header.</li>
 * <li>The indexed format will yield improved performance when working with large
 * groups. A large group may contain thousands to millions of members. Links
 * are stored in a fractal heap and indexed with an improved B-tree.</li>
 * </ul></li>
 * <li>The new implementation also enables the use of link names consisting of non-ASCII
 * character sets (see #H5Pset_char_encoding) and is required for all link types other than
 * hard or soft links; the link types other than hard or soft links are external links and
 * user-defined links @see @ref H5L APIs.</li>
 * </ul>
 *
 * The original group structure and the newer structures are not directly interoperable. By default, a
 * group will be created in the original indexed format. An existing group can be changed to a
 * compact-or-indexed format if the need arises; there is no capability to change back. As stated
 * above, once in the compact-or-indexed format, a group can switch between compact and indexed
 * as needed.
 *
 * Groups will be initially created in the compact-or-indexed format only when one or more of the
 * following conditions is met:
 * <ul>
 * <li>The low version bound value of the library version bounds property has been set to
 * Release 1.8.0 or later in the file access property list (see #H5Pset_libver_bounds).
 * Currently, that would require an #H5Pset_libver_bounds call with the low parameter
 * set to #H5F_LIBVER_LATEST.
 *
 * When this property is set for an HDF5 file, all objects in the file will be created using
 * the latest available format; no effort will be made to create a file that can be read by
 * older libraries.</li>
 * <li>The creation order tracking property, #H5P_CRT_ORDER_TRACKED, has been set
 * in the group creation property list (see #H5Pset_link_creation_order).</li>
 * </ul>
 *
 * An existing group, currently in the original indexed format, will be converted to the compact-or-
 * indexed format upon the occurrence of any of the following events:
 * <ul>
 * <li>An external or user-defined link is inserted into the group.
 * <li>A link named with a string composed of non-ASCII characters is inserted into the
 * group.
 * </ul>
 *
 * The compact-or-indexed format offers performance improvements that will be most notable at
 * the extremes (for example, in groups with zero members and in groups with tens of thousands of
 * members). But measurable differences may sometimes appear at a threshold as low as eight
 * group members. Since these performance thresholds and criteria differ from application to
 * application, tunable settings are provided to govern the switch between the compact and indexed
 * formats (see #H5Pset_link_phase_change). Optimal thresholds will depend on the application and
 * the operating environment.
 *
 * Future versions of HDF5 will retain the ability to create, read, write, and manipulate all groups
 * stored in either the original indexed format or the compact-or-indexed format.
 *
 * \subsection subsec_group_h5dump Using h5dump
 * You can use h5dump, the command-line utility distributed with HDF5, to examine a file for
 * purposes either of determining where to create an object within an HDF5 file or to verify that
 * you have created an object in the intended place.
 *
 * In the case of the new group created later in this chapter, the following h5dump command will
 * display the contents of FileA.h5:
 * \code
 * h5dump FileA.h5
 * \endcode
 *
 * For more information, @see @ref subsubsec_group_program_create.
 *
 * 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:
 * \code
 * HDF5 "FileA.h5" {
 * GROUP "/" {
 * GROUP GroupA {
 * GROUP GroupB {
 * }
 * }
 * }
 * }
 * \endcode
 *
 * h5dump is described on the “HDF5 Tools” page of the \ref RM.
 *
 * The HDF5 DDL grammar is described in the @ref DDLBNF110.
 *
 * \subsection subsec_group_function Group Function Summaries
 * Functions that can be used with groups (\ref H5G functions) and property list functions that can used
 * with groups (\ref H5P functions) are listed below. A number of group functions have been
 * deprecated. Most of these have become link (\ref H5L) or object (\ref H5O) functions. These replacement
 * functions are also listed below.
 *
 * <table>
 * <caption>Group functions</caption>
 * <tr>
 * <th>Function</th>
 * <th>Purpose</th>
 * </tr>
 * <tr>
 * <td>#H5Gcreate</td>
 * <td>Creates a new empty group and gives it a name. The
 * C function is a macro: \see \ref api-compat-macros.</td>
 * </tr>
 * <tr>
 * <td>#H5Gcreate_anon</td>
 * <td>Creates a new empty group without linking it into the file structure.</td>
 * </tr>
 * <tr>
 * <td>#H5Gopen</td>
 * <td>Opens an existing group for modification and returns a group identifier for that group.
 * The C function is a macro: \see \ref api-compat-macros.</td>
 * </tr>
 * <tr>
 * <td>#H5Gclose</td>
 * <td>Closes the specified group.</td>
 * </tr>
 * <tr>
 * <td>#H5Gget_create_plist</td>
 * <td>Gets a group creation property list identifier.</td>
 * </tr>
 * <tr>
 * <td>#H5Gget_info</td>
 * <td>Retrieves information about a group. Use instead of H5Gget_num_objs.</td>
 * </tr>
 * <tr>
 * <td>#H5Gget_info_by_idx</td>
 * <td>Retrieves information about a group according to the group’s position within an index.</td>
 * </tr>
 * <tr>
 * <td>#H5Gget_info_by_name</td>
 * <td>Retrieves information about a group.</td>
 * </tr>
 * </table>
 *
 * <table>
 * <caption>Link and object functions</caption>
 * <tr>
 * <th>Function</th>
 * <th>Purpose</th>
 * </tr>
 * <tr>
 * <td>#H5Lcreate_hard</td>
 * <td>Creates a hard link to an object. Replaces H5Glink and H5Glink2.</td>
 * </tr>
 * <tr>
 * <td>#H5Lcreate_soft</td>
 * <td>Creates a soft link to an object. Replaces H5Glink and H5Glink2.</td>
 * </tr>
 * <tr>
 * <td>#H5Lcreate_external</td>
 * <td>Creates a soft link to an object in a different file. Replaces H5Glink and H5Glink2.</td>
 * </tr>
 * <tr>
 * <td>#H5Lcreate_ud</td>
 * <td>Creates a link of a user-defined type.</td>
 * </tr>
 * </tr>
 * <tr>
 * <td>#H5Lget_val</td>
 * <td>Returns the value of a symbolic link. Replaces H5Gget_linkval.</td>
 * </tr>
 * <tr>
 * <td>#H5Literate</td>
 * <td>Iterates through links in a group. Replaces H5Giterate.
 * See also #H5Ovisit and #H5Lvisit.</td>
 * </tr>
 * <tr>
 * <td>#H5Literate_by_name</td>
 * <td>Iterates through links in a group.</td>
 * </tr>
 * <tr>
 * <td>#H5Lvisit</td>
 * <td>Recursively visits all links starting from a specified group.</td>
 * </tr>
 * <tr>
 * <td>#H5Ovisit</td>
 * <td>Recursively visits all objects accessible from a specified object.</td>
 * </tr>
 * <tr>
 * <td>#H5Lget_info</td>
 * <td>Returns information about a link. Replaces H5Gget_objinfo.</td>
 * </tr>
 * <tr>
 * <td>#H5Oget_info</td>
 * <td>Retrieves the metadata for an object specified by an identifier. Replaces H5Gget_objinfo.</td>
 * </tr>
 * <tr>
 * <td>#H5Lget_name_by_idx</td>
 * <td>Retrieves name of the nth link in a group, according to the order within a specified field
 * or index. Replaces H5Gget_objname_by_idx.</td>
 * </tr>
 * <tr>
 * <td>#H5Oget_info_by_idx</td>
 * <td>Retrieves the metadata for an object, identifying the object by an index position. Replaces
 * H5Gget_objtype_by_idx.</td>
 * </tr>
 * <tr>
 * <td>#H5Oget_info_by_name</td>
 * <td>Retrieves the metadata for an object, identifying the object by location and relative name.</td>
 * </tr>
 * <tr>
 * <td>#H5Oset_comment</td>
 * <td>Sets the comment for specified object. Replaces H5Gset_comment.</td>
 * </tr>
 * <tr>
 * <td>#H5Oget_comment</td>
 * <td>Gets the comment for specified object. Replaces H5Gget_comment.</td>
 * </tr>
 * <tr>
 * <td>#H5Ldelete</td>
 * <td>Removes a link from a group. Replaces H5Gunlink.</td>
 * </tr>
 * <tr>
 * <td>#H5Lmove</td>
 * <td>Renames a link within an HDF5 file. Replaces H5Gmove and H5Gmove2.</td>
 * </tr>
 * </table>
 *
 * \snippet{doc} tables/propertyLists.dox gcpl_table
 *
 * <table>
 * <caption>Other external link functions</caption>
 * <tr>
 * <th>Function</th>
 * <th>Purpose</th>
 * </tr>
 * <tr>
 * <td>#H5Pset_elink_file_cache_size</td>
 * <td>Sets the size of the external link open file cache from the specified
 * file access property list.</td>
 * </tr>
 * <tr>
 * <td>#H5Pget_elink_file_cache_size</td>
 * <td>Retrieves the size of the external link open file cache from the specified
 * file access property list.</td>
 * </tr>
 * <tr>
 * <td>#H5Fclear_elink_file_cache</td>
 * <td>Clears the external link open file cache for a file.</td>
 * </tr>
 * </table>
 *
 * \subsection subsec_group_program Programming Model for Groups
 * The programming model for working with groups is as follows:
 * <ol><li>Create a new group or open an existing one.</li>
 * <li>Perform the desired operations on the group.
 * <ul><li>Create new objects in the group.</li>
 * <li>Insert existing objects as group members.</li>
 * <li>Delete existing members.</li>
 * <li>Open and close member objects.</li>
 * <li>Access information regarding member objects.</li>
 * <li>Iterate across group members.</li>
 * <li>Manipulate links.</li></ul>
 * <li>Terminate access to the group (Close the group).</li></ol>
 *
 * \subsubsection subsubsec_group_program_create Creating a Group
 * To create a group, use #H5Gcreate, specifying the location and the path of the new group. The
 * location is the identifier of the file or the group in a file with respect to which the new group is to
 * be identified. The path is a string that provides either an absolute path or a relative path to the
 * new group. For more information, @see @ref subsubsec_group_descr_path.
 *
 * A path that begins with a slash (/) is
 * an absolute path indicating that it locates the new group from the root group of the HDF5 file. A
 * path that begins with any other character is a relative path. When the location is a file, a relative
 * path is a path from that file’s root group; when the location is a group, a relative path is a path
 * from that group.
 *
 * The sample code in the example below creates three groups. The group Data is created in the
 * root directory; two groups are then created in /Data, one with absolute path, the other with a
 * relative path.
 *
 * <em>Creating three new groups</em>
 * \code
 *   hid_t file;
 *   file = H5Fopen(....);
 *
 *   group = H5Gcreate(file, "/Data", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
 *   group_new1 = H5Gcreate(file, "/Data/Data_new1", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
 *   group_new2 = H5Gcreate(group, "Data_new2", H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
 * \endcode
 * The third #H5Gcreate parameter optionally specifies how much file space to reserve to store the
 * names that will appear in this group. If a non-positive value is supplied, a default size is chosen.
 *
 * \subsubsection subsubsec_group_program_open Opening a Group and Accessing an Object in that Group
 * Though it is not always necessary, it is often useful to explicitly open a group when working
 * with objects in that group. Using the file created in the example above, the example below
 * illustrates the use of a previously-acquired file identifier and a path relative to that file to open
 * the group Data.
 *
 * Any object in a group can be also accessed by its absolute or relative path. To open an object
 * using a relative path, an application must first open the group or file on which that relative path
 * is based. To open an object using an absolute path, the application can use any location identifier
 * in the same file as the target object; the file identifier is commonly used, but object identifier for
 * any object in that file will work. Both of these approaches are illustrated in the example below.
 *
 * Using the file created in the examples above, the example below provides sample code
 * illustrating the use of both relative and absolute paths to access an HDF5 data object. The first
 * sequence (two function calls) uses a previously-acquired file identifier to open the group Data,
 * and then uses the returned group identifier and a relative path to open the dataset CData. The
 * second approach (one function call) uses the same previously-acquired file identifier and an
 * absolute path to open the same dataset.
 *
 * <em>Open a dataset with relative and absolute paths</em>
 * \code
 *   group = H5Gopen(file, "Data", H5P_DEFAULT);
 *
 *   dataset1 = H5Dopen(group, "CData", H5P_DEFAULT);
 *   dataset2 = H5Dopen(file, "/Data/CData", H5P_DEFAULT);
 * \endcode
 *
 * \subsubsection subsubsec_group_program_dataset Creating a Dataset in a Specific Group
 * Any dataset must be created in a particular group. As with groups, a dataset may be created in a
 * particular group by specifying its absolute path or a relative path. The example below illustrates
 * both approaches to creating a dataset in the group /Data.
 *
 * <em> Create a dataset with absolute and relative paths</em>
 * \code
 *   dataspace = H5Screate_simple(RANK, dims, NULL);
 *   dataset1 = H5Dcreate(file, "/Data/CData", H5T_NATIVE_INT, dataspace,
 *                        H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
 *   group = H5Gopen(file, "Data", H5P_DEFAULT);
 *   dataset2 = H5Dcreate(group, "Cdata2", H5T_NATIVE_INT, dataspace,
 *                        H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT);
 * \endcode
 *
 * \subsubsection subsubsec_group_program_close 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 path
 * considerations.
 *
 * <em>Close a group</em>
 * \code
 *   herr_t status;
 *
 *   status = H5Gclose(group);
 * \endcode
 *
 * A non-negative return value indicates that the group was successfully closed and the resources
 * released; a negative return value indicates that the attempt to close the group or release resources
 * failed.
 *
 * \subsubsection subsubsec_group_program_links Creating Links
 * As previously mentioned, every object is created in a specific group. Once created, an object can
 * be made a member of additional groups by means of links created with one of the H5Lcreate_*
 * functions.
 *
 * A link is, in effect, a path by which the target object can be accessed; it therefore has a name
 * which functions as a single path component. A link can be removed with an #H5Ldelete call,
 * effectively removing the target object from the group that contained the link (assuming, of
 * course, that the removed link was the only link to the target object in the group).
 *
 * <h4>Hard Links</h4>
 * There are two kinds of links, hard links and symbolic links. Hard links are reference counted;
 * symbolic links are not. When an object is created, a hard link is automatically created. An object
 * can be deleted from the file by removing all the hard links to it.
 *
 * Working with the file from the previous examples, the code in the example below illustrates the
 * creation of a hard link, named Data_link, in the root group, /, to the group Data. Once that link is
 * created, the dataset Cdata can be accessed via either of two absolute paths, /Data/Cdata or
 * /Data_Link/Cdata.
 *
 * <em>Create a hard link</em>
 * \code
 *   status = H5Lcreate_hard(Data_loc_id, "Data", DataLink_loc_id, "Data_link", H5P_DEFAULT, H5P_DEFAULT);
 *
 *   dataset1 = H5Dopen(file, "/Data_link/CData", H5P_DEFAULT);
 *   dataset2 = H5Dopen(file, "/Data/CData", H5P_DEFAULT);
 * \endcode
 *
 * The example below shows example code to delete a link, deleting the hard link Data from the
 * root group. The group /Data and its members are still in the file, but they can no longer be
 * accessed via a path using the component /Data.
 *
 * <em>Delete a link</em>
 * \code
 *   status = H5Ldelete(Data_loc_id, "Data", H5P_DEFAULT);
 *
 *   dataset1 = H5Dopen(file, "/Data_link/CData", H5P_DEFAULT);
 *   // This call should succeed; all path components still exist
 *   dataset2 = H5Dopen(file, "/Data/CData", H5P_DEFAULT);
 *   // This call will fail; the path component '/Data' has been deleted.
 * \endcode
 *
 * When the last hard link to an object is deleted, the object is no longer accessible. #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 the is greater than 1,
 * then the link can be deleted without making the object inaccessible.
 *
 * The example below shows #H5Oget_info to the group originally called Data.
 *
 * <em>Finding the number of links to an object</em>
 * \code
 *   status = H5Oget_info(Data_loc_id, object_info);
 * \endcode
 *
 * 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. If your application
 * creates a hard link to the dataset before it closes the dataset, then the dataset will still be
 * accessible.
 *
 * <h4>Symbolic Links</h4>
 * Symbolic links are objects that assign a name in a group to a path. Notably, the target object is
 * determined only when the symbolic link is accessed, and may, in fact, not exist. Symbolic links
 * are not reference counted, so there may be zero, one, or more symbolic links to an object.
 *
 * The major types of symbolic links are soft links and external links. Soft links are symbolic links
 * within an HDF5 file and are created with the #H5Lcreate_soft function. Symbolic links to objects
 * located in external files, in other words external links, can be created with the
 * #H5Lcreate_external function. Symbolic links are removed with the #H5Ldelete function.
 *
 * The example below shows the creating two soft links to the group /Data.
 *
 * <em>Create a soft link</em>
 * \code
 *   status = H5Lcreate_soft(path_to_target, link_loc_id, "Soft2", H5P_DEFAULT, H5P_DEFAULT);
 *   status = H5Lcreate_soft(path_to_target, link_loc_id, "Soft3", H5P_DEFAULT, H5P_DEFAULT);
 *   dataset = H5Dopen(file, "/Soft2/CData", H5P_DEFAULT);
 * \endcode
 *
 * With the soft links defined in the example above, the dataset CData in the group /Data can now
 * be opened with any of the names /Data/CData, /Soft2/CData, or /Soft3/CData.
 *
 * 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 \ref RM for the #H5Pset_elink_file_cache_size function call.
 *
 * <h4>Note Regarding Hard Links and Soft Links</h4>
 * Note that an object’s existence in a file is governed by the presence of at least one hard link to
 * that object. If the last hard link to an object is removed, the object is removed from the file and
 * any remaining soft link becomes a dangling link, a link whose target object does not exist.
 *
 * <h4>Moving or Renaming Objects, and a Warning</h4>
 * An object can be renamed by changing the name of a link to it with #H5Lmove. This has the same
 * effect as creating a new link with the new name and deleting the link with the old name.
 *
 * Exercise caution in the use of #H5Lmove and #H5Ldelete as these functions each include a step
 * that unlinks a pointer to an HDF5 object. If the link that is removed is on the only path leading to
 * an HDF5 object, that object will become permanently inaccessible in the file.
 *
 * <h5>Scenario 1: Removing the Last Link</h5>
 * To avoid removing the last link to an object or otherwise making an object inaccessible, use the
 * #H5Oget_info function. Make sure that the value of the reference count field (rc) is greater than 1.
 *
 * <h5>Scenario 2: Moving a Link that Isolates an Object</h5>
 * Consider the following example: assume that the group group2 can only be accessed via the
 * following path, where top_group is a member of the file’s root group:
 * <em>/top_group/group1/group2/</em>
 *
 * Using #H5Lmove, top_group is renamed to be a member ofgroup2. At this point, since
 * top_group was the only route from the root group to group1, there is no longer a path by which
 * one 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.
 *
 * <h4>Mounting a File</h4>
 * An external link is a permanent connection between two files. A temporary connection can be set
 * up with the #H5Fmount function. For more information, @see sec_file.
 * For more information, see the #H5Fmount function in the \ref RM.
 *
 * \subsubsection subsubsec_group_program_info 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.
 *
 * \subsubsection subsubsec_group_program_objs 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. #H5Literate 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. #H5Ovisit recursively visits all objects
 * accessible from a specified object. #H5Lvisit recursively visits all the links starting from a
 * specified group.
 *
 * \subsubsection subsubsec_group_program_all 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.
 *
 * \subsection subsec_group_examples Examples of File Structures
 * This section presents several samples of HDF5 file structures.
 *
 * Figure 9 shows examples of the structure of a file with three groups and one dataset. The file in
 * part a contains three groups: the root group and two member groups. In part b, the dataset
 * dset1 has been created in /group1. In part c, 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.
 *
 * Part d illustrates that one of the two links to the dataset can be deleted. In this case, the link from
 * <em>/group1</em>
 * has been removed. The dataset itself has not been deleted; it is still in the file but can only be
 * accessed as
 * <em>/group2/dset2</em>
 *
 * <table>
 * <caption>Figure 9 - Some file structures</caption>
 * <tr>
 * <td>
 * \image html Groups_fig9_a.gif "a) The file contains three groups: the root group, /group1, and  /group2."
 * </td>
 * <td>
 * \image html Groups_fig9_b.gif "b) The dataset dset1 (or /group1/dset1) is created in /group1."
 * </td>
 * </tr>
 * <tr>
 * <td>
 * \image html Groups_fig9_aa.gif "c) A link named dset2 to the same dataset is created in /group2."
 * </td>
 * <td>
 * \image html Groups_fig9_bb.gif "d) The link from /group1 to dset1 is removed. The dataset is
 * still in the file, but can be accessed only as /group2/dset2."
 * </td>
 * </tr>
 * </table>
 *
 * Figure 10 illustrates loops in an HDF5 file structure. The file in part a contains three groups
 * and a dataset; group2 is a member of the root group and of the root group’s other member group,
 * group1. group2 thus can be accessed by either of two paths: /group2 or /group1/GXX. Similarly,
 * the dataset can be accessed either as /group2/dset1 or as /group1/GXX/dset1.
 *
 * Part b illustrates a different case: the dataset is a member of a single group but with two links, or
 * names, in that group. In this case, the dataset again has two names, /group1/dset1 and
 * /group1/dset2.
 *
 * In part c, the dataset dset1 is a member of two groups, one of which can be accessed by either of
 * two names. The dataset thus has three path names: /group1/dset1, /group2/dset2, and
 * /group1/GXX/dset2.
 *
 * And in part d, 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 path name such as /group1/GXX/GYY/GXX/GYY/GXX/dset2.
 *
 * <table>
 * <caption>Figure 10 - More sample file structures</caption>
 * <tr>
 * <td>
 * \image html Groups_fig10_a.gif "a) dset1 has two names: /group2/dset1 and /group1/GXX/dset1."
 * </td>
 * <td>
 * \image html Groups_fig10_b.gif "b) dset1 again has two names: /group1/dset1 and /group1/dset2."
 * </td>
 * </tr>
 * <tr>
 * <td>
 * \image html Groups_fig10_c.gif "c) dset1 has three names: /group1/dset1, /group2/dset2, and
 * /group1/GXX/dset2."
 * </td>
 * <td>
 * \image html Groups_fig10_d.gif "d) dset1 has an infinite number of available path names."
 * </td>
 * </tr>
 * </table>
 *
 * Figure 11 takes us into the realm of soft links. The original file, in part a, contains only three
 * hard links. In part b, a soft link named dset2 from group2 to /group1/dset1 has been created,
 * making this dataset accessible as /group2/dset2.
 *
 * In part c, another soft link has been created in group2. But this time the soft link, dset3, points
 * to a target object that does not yet exist. That target object, dset, has been added in part d and is
 * now accessible as either /group2/dset or /group2/dset3.
 *
 * It could be said that HDF5 extends the organizing concepts of a file system to the internal
 * structure of a single file.
 *
 * <table>
 * <caption>Figure 11 - Hard and soft links</caption>
 * <tr>
 * <td>
 * \image html Groups_fig11_a.gif "a) The file contains only hard links."
 * </td>
 * <td>
 * \image html Groups_fig11_b.gif "b) A soft link is added from group2 to /group1/dset1."
 * </td>
 * </tr>
 * <tr>
 * <td>
 * \image html Groups_fig11_c.gif "c) A soft link named dset3 is added with a target that does not yet exist."
 * </td>
 * <td>
 * \image html Groups_fig11_d.gif "d) The target of the soft link is created or linked."
 * </td>
 * </tr>
 * </table>
 *
 * Previous Chapter \ref sec_file - Next Chapter \ref sec_dataset
 *
 */

/**
 * \defgroup H5G Groups (H5G)
 *
 * Use the functions in this module to manage HDF5 groups.
 *
 * <table>
 * <tr><th>Create</th><th>Read</th></tr>
 * <tr valign="top">
 *   <td>
 *   \snippet{lineno} H5G_examples.c create
 *   </td>
 *   <td>
 *   \snippet{lineno} H5G_examples.c read
 *   </td>
 * <tr><th>Update</th><th>Delete</th></tr>
 * <tr valign="top">
 *   <td>
 *   \snippet{lineno} H5G_examples.c update
 *   </td>
 *   <td>
 *   \snippet{lineno} H5G_examples.c delete
 *   </td>
 * </tr>
 * </table>
 *
 * \details \Bold{Groups in HDF5:} A group associates names with objects and
 *          provides a mechanism for mapping a name to an object. Since all
 *          objects appear in at least one group (with the possible exception of
 *          the root object) and since objects can have names in more than one
 *          group, the set of all objects in an HDF5 file is a directed
 *          graph. The internal nodes (nodes with an out-degree greater than zero)
 *          must be groups, while the leaf nodes (nodes with an out-degree zero) are
 *          either empty groups or objects of some other type. Exactly one
 *          object in every non-empty file is the root object. The root object
 *          always has a positive in-degree because it is pointed to by the file
 *          superblock.
 *
 *          \Bold{Locating objects in the HDF5 file hierarchy:} An object name
 *          consists of one or more components separated from one another by
 *          slashes. An absolute name begins with a slash, and the object is
 *          located by looking for the first component in the root object, then
 *          looking for the second component in the first object, etc., until
 *          the entire name is traversed. A relative name does not begin with a
 *          slash, and the traversal begins at the location specified by the
 *          create or access function.
 *
 *          \Bold{Group implementations in HDF5:} The original HDF5 group
 *          implementation provided a single-indexed structure for link
 *          storage. A new group implementation, in HDF5 Release 1.8.0, enables
 *          more efficient compact storage for very small groups, improved link
 *          indexing for large groups, and other advanced features.
 *
 *          \li The \Emph{original indexed} format remains the default. Links
 *              are stored in a B-tree in the group’s local heap.
 *          \li Groups created in the new \Emph{compact-or-indexed} format, the
 *              implementation introduced with Release 1.8.0, can be tuned for
 *              performance, switching between the compact and indexed formats
 *              at thresholds set in the user application.
 *              - The \Emph{compact} format will conserve file space and processing
 *                overhead when working with small groups and is particularly
 *                valuable when a group contains no links. Links are stored
 *                as a list of messages in the group’s header.
 *              - The \Emph{indexed} format will yield improved
 *                performance when working with large groups, e.g., groups
 *                containing thousands to millions of members. Links are stored in
 *                a fractal heap and indexed with an improved B-tree.
 *          \li The new implementation also enables the use of link names consisting of
 *              non-ASCII character sets (see #H5Pset_char_encoding) and is
 *              required for all link types other than hard or soft links, e.g.,
 *              external and user-defined links (see the \ref H5L APIs).
 *
 *          The original group structure and the newer structures are not
 *          directly interoperable. By default, a group will be created in the
 *          original indexed format. An existing group can be changed to a
 *          compact-or-indexed format if the need arises; there is no capability
 *          to change back. As stated above, once in the compact-or-indexed
 *          format, a group can switch between compact and indexed as needed.
 *
 *          Groups will be initially created in the compact-or-indexed format
 *          only when one or more of the following conditions is met:
 *          \li The low version bound value of the library version bounds property
 *              has been set to Release 1.8.0 or later in the file access property
 *              list (see H5Pset_libver_bounds()). Currently, that would require an
 *              H5Pset_libver_bounds() call with the low parameter set to
 *              #H5F_LIBVER_LATEST.\n When this property is set for an HDF5 file,
 *              all objects in the file will be created using the latest available
 *              format; no effort will be made to create a file that can be read by
 *              older libraries.
 *          \li The creation order tracking property, #H5P_CRT_ORDER_TRACKED, has been
 *              set in the group creation property list (see H5Pset_link_creation_order()).
 *
 *          An existing group, currently in the original indexed format, will be
 *          converted to the compact-or-indexed format upon the occurrence of
 *          any of the following events:
 *          \li An external or user-defined link is inserted into the group.
 *          \li A link named with a string composed of non-ASCII characters is
 *              inserted into the group.
 *
 *          The compact-or-indexed format offers performance improvements that
 *          will be most notable at the extremes, i.e., in groups with zero
 *          members and in groups with tens of thousands of members. But
 *          measurable differences may sometimes appear at a threshold as low as
 *          eight group members. Since these performance thresholds and criteria
 *          differ from application to application, tunable settings are
 *          provided to govern the switch between the compact and indexed
 *          formats (see H5Pset_link_phase_change()). Optimal thresholds will
 *          depend on the application and the operating environment.
 *
 *          Future versions of HDF5 will retain the ability to create, read,
 *          write, and manipulate all groups stored in either the original
 *          indexed format or the compact-or-indexed format.
 *
 */

#endif /* H5Gmodule_H */