From d0bbd4e8abf64810c7cda15018d8fcce2999f11d Mon Sep 17 00:00:00 2001 From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com> Date: Wed, 6 Jul 2022 15:04:38 -0500 Subject: Port UG groups chapter to doxygen (#1850) * Port UG groups chapter to doxygen. * Committing clang-format changes Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com> --- doxygen/img/Groups_fig1.gif | Bin 0 -> 5404 bytes doxygen/img/Groups_fig10_a.gif | Bin 0 -> 7745 bytes doxygen/img/Groups_fig10_b.gif | Bin 0 -> 6372 bytes doxygen/img/Groups_fig10_c.gif | Bin 0 -> 8308 bytes doxygen/img/Groups_fig10_d.gif | Bin 0 -> 12963 bytes doxygen/img/Groups_fig11_a.gif | Bin 0 -> 7349 bytes doxygen/img/Groups_fig11_b.gif | Bin 0 -> 7912 bytes doxygen/img/Groups_fig11_c.gif | Bin 0 -> 8589 bytes doxygen/img/Groups_fig11_d.gif | Bin 0 -> 9552 bytes doxygen/img/Groups_fig2.gif | Bin 0 -> 6187 bytes doxygen/img/Groups_fig3.gif | Bin 0 -> 5045 bytes doxygen/img/Groups_fig4.gif | Bin 0 -> 12187 bytes doxygen/img/Groups_fig5.gif | Bin 0 -> 10459 bytes doxygen/img/Groups_fig6.gif | Bin 0 -> 13979 bytes doxygen/img/Groups_fig9_a.gif | Bin 0 -> 6313 bytes doxygen/img/Groups_fig9_aa.gif | Bin 0 -> 7923 bytes doxygen/img/Groups_fig9_b.gif | Bin 0 -> 7352 bytes doxygen/img/Groups_fig9_bb.gif | Bin 0 -> 7336 bytes src/H5Amodule.h | 4 +- src/H5Dmodule.h | 4 +- src/H5Gmodule.h | 897 +++++++++++++++++++++++++++++++++++++++++ src/H5Pmodule.h | 2 +- src/H5Tmodule.h | 2 +- 23 files changed, 903 insertions(+), 6 deletions(-) create mode 100644 doxygen/img/Groups_fig1.gif create mode 100644 doxygen/img/Groups_fig10_a.gif create mode 100644 doxygen/img/Groups_fig10_b.gif create mode 100644 doxygen/img/Groups_fig10_c.gif create mode 100644 doxygen/img/Groups_fig10_d.gif create mode 100644 doxygen/img/Groups_fig11_a.gif create mode 100644 doxygen/img/Groups_fig11_b.gif create mode 100644 doxygen/img/Groups_fig11_c.gif create mode 100644 doxygen/img/Groups_fig11_d.gif create mode 100644 doxygen/img/Groups_fig2.gif create mode 100644 doxygen/img/Groups_fig3.gif create mode 100644 doxygen/img/Groups_fig4.gif create mode 100644 doxygen/img/Groups_fig5.gif create mode 100644 doxygen/img/Groups_fig6.gif create mode 100644 doxygen/img/Groups_fig9_a.gif create mode 100644 doxygen/img/Groups_fig9_aa.gif create mode 100644 doxygen/img/Groups_fig9_b.gif create mode 100644 doxygen/img/Groups_fig9_bb.gif diff --git a/doxygen/img/Groups_fig1.gif b/doxygen/img/Groups_fig1.gif new file mode 100644 index 0000000..193fff9 Binary files /dev/null and b/doxygen/img/Groups_fig1.gif differ diff --git a/doxygen/img/Groups_fig10_a.gif b/doxygen/img/Groups_fig10_a.gif new file mode 100644 index 0000000..6595b34 Binary files /dev/null and b/doxygen/img/Groups_fig10_a.gif differ diff --git a/doxygen/img/Groups_fig10_b.gif b/doxygen/img/Groups_fig10_b.gif new file mode 100644 index 0000000..9e7c234 Binary files /dev/null and b/doxygen/img/Groups_fig10_b.gif differ diff --git a/doxygen/img/Groups_fig10_c.gif b/doxygen/img/Groups_fig10_c.gif new file mode 100644 index 0000000..20900ac Binary files /dev/null and b/doxygen/img/Groups_fig10_c.gif differ diff --git a/doxygen/img/Groups_fig10_d.gif b/doxygen/img/Groups_fig10_d.gif new file mode 100644 index 0000000..7251919 Binary files /dev/null and b/doxygen/img/Groups_fig10_d.gif differ diff --git a/doxygen/img/Groups_fig11_a.gif b/doxygen/img/Groups_fig11_a.gif new file mode 100644 index 0000000..1d041d0 Binary files /dev/null and b/doxygen/img/Groups_fig11_a.gif differ diff --git a/doxygen/img/Groups_fig11_b.gif b/doxygen/img/Groups_fig11_b.gif new file mode 100644 index 0000000..732109b Binary files /dev/null and b/doxygen/img/Groups_fig11_b.gif differ diff --git a/doxygen/img/Groups_fig11_c.gif b/doxygen/img/Groups_fig11_c.gif new file mode 100644 index 0000000..f1444eb Binary files /dev/null and b/doxygen/img/Groups_fig11_c.gif differ diff --git a/doxygen/img/Groups_fig11_d.gif b/doxygen/img/Groups_fig11_d.gif new file mode 100644 index 0000000..ee1b740 Binary files /dev/null and b/doxygen/img/Groups_fig11_d.gif differ diff --git a/doxygen/img/Groups_fig2.gif b/doxygen/img/Groups_fig2.gif new file mode 100644 index 0000000..d14b0ff Binary files /dev/null and b/doxygen/img/Groups_fig2.gif differ diff --git a/doxygen/img/Groups_fig3.gif b/doxygen/img/Groups_fig3.gif new file mode 100644 index 0000000..aaa1fe7 Binary files /dev/null and b/doxygen/img/Groups_fig3.gif differ diff --git a/doxygen/img/Groups_fig4.gif b/doxygen/img/Groups_fig4.gif new file mode 100644 index 0000000..a077bf3 Binary files /dev/null and b/doxygen/img/Groups_fig4.gif differ diff --git a/doxygen/img/Groups_fig5.gif b/doxygen/img/Groups_fig5.gif new file mode 100644 index 0000000..55ddc3c Binary files /dev/null and b/doxygen/img/Groups_fig5.gif differ diff --git a/doxygen/img/Groups_fig6.gif b/doxygen/img/Groups_fig6.gif new file mode 100644 index 0000000..53a18d4 Binary files /dev/null and b/doxygen/img/Groups_fig6.gif differ diff --git a/doxygen/img/Groups_fig9_a.gif b/doxygen/img/Groups_fig9_a.gif new file mode 100644 index 0000000..af0ab69 Binary files /dev/null and b/doxygen/img/Groups_fig9_a.gif differ diff --git a/doxygen/img/Groups_fig9_aa.gif b/doxygen/img/Groups_fig9_aa.gif new file mode 100644 index 0000000..43ed356 Binary files /dev/null and b/doxygen/img/Groups_fig9_aa.gif differ diff --git a/doxygen/img/Groups_fig9_b.gif b/doxygen/img/Groups_fig9_b.gif new file mode 100644 index 0000000..b07ec9c Binary files /dev/null and b/doxygen/img/Groups_fig9_b.gif differ diff --git a/doxygen/img/Groups_fig9_bb.gif b/doxygen/img/Groups_fig9_bb.gif new file mode 100644 index 0000000..e13f534 Binary files /dev/null and b/doxygen/img/Groups_fig9_bb.gif differ diff --git a/src/H5Amodule.h b/src/H5Amodule.h index ba5a9df..29e5960 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -240,7 +240,7 @@ * * op_func is a user-defined operation that adheres to the \ref H5A_operator_t prototype. This prototype and * certain requirements imposed on the operator’s behavior are described in the \ref H5Aiterate entry in the - * HDF5 Reference Manual. + * \ref RM. * * op_data is also user-defined to meet the requirements of op_func. Beyond providing a parameter with which * to pass this data, HDF5 provides no tools for its management and imposes no restrictions. @@ -364,7 +364,7 @@ * will be ignored by HDF5. * * The use of ASCII or UTF-8 characters is determined by the character encoding property. See - * H5Pset_char_encoding in the HDF5 Reference Manual. + * #H5Pset_char_encoding in the \ref RM. * *

No Special I/O or Storage

* diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index e3742cb..8cca52e 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -2773,7 +2773,7 @@ allocated if necessary. * * // Set parameters for scale-offset compression. Check the * // description of the H5Pset_scaleoffset function in the - * // HDF5 Reference Manual for more information [3]. + * // HDF5 Reference Manual for more information. * if(H5Pset_scaleoffset (dset_create_props, H5Z_SO_INT, H5Z_SO_INT_MINIMUMBITS_DEFAULT) < 0) { * printf("Error: fail to set scaleoffset filter\n"); * return -1; @@ -2895,7 +2895,7 @@ allocated if necessary. * // Set parameters for scale-offset compression; use variable * // minimum-bits method, set decimal scale factor to 3. Check * // the description of the H5Pset_scaleoffset function in the - * // HDF5 Reference Manual for more information [3]. + * // HDF5 Reference Manual for more information. * if(H5Pset_scaleoffset (dset_create_props, H5Z_SO_FLOAT_DSCALE, 3) < 0) { * printf("Error: fail to set scaleoffset filter\n"); * return -1; diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index dcfb6d7..f15b929 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -33,23 +33,920 @@ * * \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. + * + * + * + * + * + *
+ * \image html Groups_fig1.gif "A file with a strictly hierarchical group structure" + *
+ * + * + * + * + * + *
+ * \image html Groups_fig2.gif "A file with a circular reference" + *
+ * + * + * + * + * + *
+ * \image html Groups_fig3.gif "A file with one group as a member of itself" + *
+ * + * 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. + * + * + * + * + * + *
+ * \image html Groups_fig4.gif "Abstract model of the HDF5 group object" + *
+ * + * 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. + * + * + * + * + * + *
+ * \image html Groups_fig5.gif "Classes of named objects" + *
+ * + * 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. + * + * + * + * + * + *
+ * \image html Groups_fig6.gif "The group object" + *
+ * + * 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. + * + * A BNF grammar for HDF5 path names + * \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: + * /GroupA/Dataset1 + * + * /GroupA/GroupB/GroupC/Dataset1 + * + * 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: + * /GroupA/GroupB/GroupC/GroupA/Dataset1 + * + * Alternatively, if the current working location is GroupB, Dataset1 can be identified by either of + * these relative path names: + * GroupC/Dataset1 + * + * GroupC/GroupA/Dataset1 + * + * Note that relative path names in HDF5 do not employ the ../ notation, the UNIX notation + * indicating a parent directory, to indicate a parent group. + * + * + * + * + * + *
+ * \image html Groups_fig2.gif "A file with a circular reference" + *
+ * * \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. + * + * + * 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: + * + * + * 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: + * + * + * 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. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Group functions
FunctionPurpose
#H5GcreateCreates a new empty group and gives it a name. The + * C function is a macro: \see \ref api-compat-macros.
#H5Gcreate_anonCreates a new empty group without linking it into the file structure.
#H5GopenOpens an existing group for modification and returns a group identifier for that group. + * The C function is a macro: \see \ref api-compat-macros.
#H5GcloseCloses the specified group.
#H5Gget_create_plistGets a group creation property list identifier.
#H5Gget_infoRetrieves information about a group. Use instead of H5Gget_num_objs.
#H5Gget_info_by_idxRetrieves information about a group according to the group’s position within an index.
#H5Gget_info_by_nameRetrieves information about a group.
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Link and object functions
FunctionPurpose
#H5Lcreate_hardCreates a hard link to an object. Replaces H5Glink and H5Glink2.
#H5Lcreate_softCreates a soft link to an object. Replaces H5Glink and H5Glink2.
#H5Lcreate_externalCreates a soft link to an object in a different file. Replaces H5Glink and H5Glink2.
#H5Lcreate_udCreates a link of a user-defined type.
#H5Lget_valReturns the value of a symbolic link. Replaces H5Gget_linkval.
#H5LiterateIterates through links in a group. Replaces H5Giterate. + * See also #H5Ovisit and #H5Lvisit.
#H5Literate_by_nameIterates through links in a group.
#H5LvisitRecursively visits all links starting from a specified group.
#H5OvisitRecursively visits all objects accessible from a specified object.
#H5Lget_infoReturns information about a link. Replaces H5Gget_objinfo.
#H5Oget_infoRetrieves the metadata for an object specified by an identifier. Replaces H5Gget_objinfo.
#H5Lget_name_by_idxRetrieves 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_idxRetrieves the metadata for an object, identifying the object by an index position. Replaces + * H5Gget_objtype_by_idx.
#H5Oget_info_by_nameRetrieves the metadata for an object, identifying the object by location and relative name.
#H5Oset_commentSets the comment for specified object. Replaces H5Gset_comment.
#H5Oget_commentGets the comment for specified object. Replaces H5Gget_comment.
#H5LdeleteRemoves a link from a group. Replaces H5Gunlink.
#H5LmoveRenames a link within an HDF5 file. Replaces H5Gmove and H5Gmove2.
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Group creation property list functions
FunctionPurpose
#H5Pall_filters_availVerifies that all required filters are available.
#H5Pget_filterReturns information about a filter in a pipeline. The + * C function is a macro: \see \ref api-compat-macros.
#H5Pget_filter_by_idReturns information about the specified filter. The + * C function is a macro: \see \ref api-compat-macros.
#H5Pget_nfiltersReturns the number of filters in the pipeline.
#H5Pmodify_filterModifies a filter in the filter pipeline.
#H5Premove_filterDeletes one or more filters in the filter pipeline.
#H5Pset_deflateSets the deflate (GNU gzip) compression method and compression level.
#H5Pset_filterAdds a filter to the filter pipeline.
#H5Pset_fletcher32Sets up use of the Fletcher32 checksum filter.
#H5Pset_link_phase_changeSets the parameters for conversion between compact and dense groups.
#H5Pget_link_phase_changeQueries the settings for conversion between compact and dense groups.
#H5Pset_est_link_infoSets estimated number of links and length of link names in a group.
#H5Pget_est_link_infoQueries data required to estimate required local heap or object header size.
#H5Pset_nlinksSets maximum number of soft or user-defined link traversals.
#H5Pget_nlinksRetrieves the maximum number of link traversals.
#H5Pset_link_creation_orderSets creation order tracking and indexing for links in a group.
#H5Pget_link_creation_orderQueries whether link creation order is tracked and/or indexed in a group.
#H5Pset_create_intermediate_groupSpecifies in the property list whether to create missing intermediate groups.
#H5Pget_create_intermediate_groupDetermines whether the property is set to enable creating missing intermediate groups.
#H5Pset_char_encodingSets the character encoding used to encode a string. Use to set ASCII or UTF-8 character + * encoding for object names.
#H5Pget_char_encodingRetrieves the character encoding used to create a string.
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Other external link functions
FunctionPurpose
#H5Pset_elink_file_cache_sizeSets the size of the external link open file cache from the specified + * file access property list.
#H5Pget_elink_file_cache_sizeRetrieves the size of the external link open file cache from the specified + * file access property list.
#H5Fclear_elink_file_cacheClears the external link open file cache for a file.
+ * * \subsection subsec_group_program Programming Model for Groups + * The programming model for working with groups is as follows: + *
  1. Create a new group or open an existing one.
    2. + *
  2. Perform the desired operations on the group. + * + *
  3. Terminate access to the group (Close the group).
+ * * \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. + * + * Creating three new groups + * \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. + * + * Open a dataset with relative and absolute paths + * \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. + * + * Create a dataset with absolute and relative paths + * \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. + * + * Close a group + * \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). + * + *

Hard Links

+ * 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. + * + * Create a hard link + * \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. + * + * Delete a link + * \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. + * + * Finding the number of links to an object + * \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. + * + *

Symbolic Links

+ * 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. + * + * Create a soft link + * \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. + * + *

Note Regarding Hard Links and Soft Links

+ * 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. + * + *

Moving or Renaming Objects, and a Warning

+ * 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. + * + *
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. Make sure 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 group2 can only be accessed via the + * following path, where top_group is a member of the file’s root group: + * /top_group/group1/group2/ + * + * 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. + * + *

Mounting a File

+ * 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 + * /group1 + * has been removed. The dataset itself has not been deleted; it is still in the file but can only be + * accessed as + * /group2/dset2 + * + * + * + * + * + * + * + * + * + * + * + *
Figure 9 - Some file structures
+ * \image html Groups_fig9_a.gif "a) The file contains three groups: the root group, /group1, and /group2." + * + * \image html Groups_fig9_b.gif "b) The dataset dset1 (or /group1/dset1) is created in /group1." + *
+ * \image html Groups_fig9_aa.gif "c) A link named dset2 to the same dataset is created in /group2." + * + * \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." + *
+ * + * 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. + * + * + * + * + * + * + * + * + * + * + * + *
Figure 10 - More sample file structures
+ * \image html Groups_fig10_a.gif "a) dset1 has two names: /group2/dset1 and /group1/GXX/dset1." + * + * \image html Groups_fig10_b.gif "b) dset1 again has two names: /group1/dset1 and /group1/dset2." + *
+ * \image html Groups_fig10_c.gif "c) dset1 has three names: /group1/dset1, /group2/dset2, and + * /group1/GXX/dset2." + * + * \image html Groups_fig10_d.gif "d) dset1 has an infinite number of available path names." + *
+ * + * 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. + * + * + * + * + * + * + * + * + * + * + * + *
Figure 11 - Hard and soft links
+ * \image html Groups_fig11_a.gif "a) The file contains only hard links." + * + * \image html Groups_fig11_b.gif "b) A soft link is added from group2 to /group1/dset1." + *
+ * \image html Groups_fig11_c.gif "c) A soft link named dset3 is added with a target that does not yet exist." + * + * \image html Groups_fig11_d.gif "d) The target of the soft link is created or linked." + *
+ * + * Previous Chapter \ref sec_file - Next Chapter \ref sec_dataset * */ diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index fc493f9..f5f8d83 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -762,7 +762,7 @@ * makes it possible for an application or a driver to create, modify, and manage custom properties, * property lists, and property list classes. A comprehensive list of functions for this interface * appears under "Generic Property Operations (Advanced)" in the "H5P: Property List Interface" - * section of the HDF5 Reference Manual. + * section of the \ref RM. * * Further discussion of HDF5’s generic property interface and user-defined properties and * property lists is beyond the scope of this document. diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index c9d52bd..e9dafa1 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -366,7 +366,7 @@ * bits, and an indication of the byte order Table 4. * * Table 5 shows examples of predefined datatypes. The full list can be found in the - * \ref PDT section of the HDF5 Reference Manual. + * \ref PDT section of the \ref RM. * * * -- cgit v0.12
Table 2. Architectures used in predefined datatypes