summaryrefslogtreecommitdiffstats
path: root/src/H5Gpublic.h
diff options
context:
space:
mode:
authorGerd Heber <gheber@hdfgroup.org>2021-04-26 19:07:29 (GMT)
committerGitHub <noreply@github.com>2021-04-26 19:07:29 (GMT)
commit1d680fe04c545d601678d876ad22dea7bfc31edd (patch)
treef84a97c149df9ccf4409c5bfea04a7316c019e8a /src/H5Gpublic.h
parent12082e728de7481144db7ea3cca6f38acf0a7cac (diff)
downloadhdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.zip
hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.gz
hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.bz2
Merge doxygen2 into develop (#553)
* Fixed warnings and started H5Epublic.h. * Include H5FD* headers to correctly resolve references. * Doxygen2 (#330) * H5Eauto_is_v2. * Added a few more calls. * Added a few more H5E calls. * First cut of H5E v2. * Added the deprecated v1 calls. * Updated spacing. * Once more. * Taking some inspiration from Eigen3. * Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352) * Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2. * doxygen work. fixs format by using clang-format. * doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments. For Quincey's comments, since we are not supposed to change the source code. I leave this to future improvements. * added documentation for H5P APIs (#350) * add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios * format corrections * fixed grammer * fixed herr_t * Better name. * A fresh look. * add doxygen to H5Ppublic.h * use attention instead of warning * Add doxygen comments in H5Ppublic.h (#375) * Add doxygen comments in H5Ppublic.h * H5Pset_meta_block_size * H5Pset_metadata_read_attempts * H5Pset_multi_type * H5Pset_object_flush_cb * H5Pset_sieve_buf_size * H5Pset_small_data_block_size * H5Pset_all_coll_metadata_ops * H5Pget_all_coll_metadata_ops * Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt * Fix clang-format errors * Fix filenames in doxygen/examples * add doxygen to H5Ppublic.h (#378) * add doxygen to H5Ppublic.h * use attention instead of warning Co-authored-by: Kimmy Mu <kmu@hdfgroup.org> * Revert "add doxygen to H5Ppublic.h (#378)" This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2. * Updated Doxygen variables. * I forgot to copy two images. * Enable desktop search by default. * Add my assigned Doxygen documentation. * Remove whitespace at EOL. Appease clang-format. * Addressed Chris' comments. * Added an alias for asynchronous functions. * One space is enough for all of us. * Slightly restructured RM page. * address some issues * reformatting * Style external links. * reformatting * reformatting * Added "Metadata Caching in HDF5" as a technical note example. * Revise this soon! * Added specification examples. * Fixed references. * Added H5AC cache image stuff and file format study. * Added older FMT versions. Where did 1.0 go? * Updated C/C++ note and replaced ambiguous labels. * Reformat source with clang v10.0.1. * Added the VFL technical note. * Added what I believe might be called version 1.0 of the format. * Added the remaining specs. * Added H5Z callback documentation and fixed a few mistakes. * Added dox for deprecated H5G calls and fixed a few snippet blockIDs. * clang-format happy? * Ok? * Bonus track: Deprecated H5D functions. * Carry over the more detailed group description. * Added documentation for the missing and deprecated H5R calls. * Life is easier and less repetitive w/ snippets. Use them! * Eliminate the snippet block ID artifacts in the HTML rendering. * Fixed snippet HTML artifacts and added a few missing calls. * Under 20 H5Ps to go! * Almost complete! * "This is a form of pedantry up with which I will not put." (Churchill) * Let's not waste as much space on bulleted lists! * First complete (?) draft of the Doxygen-based RM. * Completeness check and minor fixes along the way. * Pedantry. * Adding missing H5FD calls checkpoint. * Pedantry. * More pedantry. * Added H5Pset_fapl_log. * First draft of H5ES. * Fixed warnings. * Prep. for map module. * First cut of the map module. * Pedantry. * Possible H5F introduction. * Fix the indentation. * Pedantry. * Ditto. * Thanks to the reviewers for their comments. * Added missing images. * Line numbers are a distraction here. * More examples, references, and clean-up. Don't repeat yourself! * Clang pedantry. * Ditto. * More reviewer comments... * Templatized references and cleaned up \todos. * Committing clang-format changes * Fixed MANIFEST. * Addressed Quincey's comments. (OCPLs) * Fixed a few more \todo items. * Fixed more \todo items. * Added attribute life cycle. * Forgot the examples file. * Committing clang-format changes * Pedantry. * Live and learn! * Added a sample H5D life cycle. * Committing clang-format changes * Pedantry. Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com> Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org> Co-authored-by: Kimmy Mu <kmu@hdfgroup.org> Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com> Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com> Co-authored-by: David Young <dyoung@hdfgroup.org> Co-authored-by: Larry Knox <lrknox@hdfgroup.org> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src/H5Gpublic.h')
-rw-r--r--src/H5Gpublic.h826
1 files changed, 666 insertions, 160 deletions
diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h
index 68786dc..416ff2c 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -41,24 +41,31 @@
/* Public Typedefs */
/*******************/
-/* Types of link storage for groups */
+//! <!-- [H5G_storage_t_snip] -->
+/**
+ * Types of link storage for groups
+ */
typedef enum H5G_storage_type_t {
- H5G_STORAGE_TYPE_UNKNOWN = -1, /* Unknown link storage type */
- H5G_STORAGE_TYPE_SYMBOL_TABLE, /* Links in group are stored with a "symbol table" */
- /* (this is sometimes called "old-style" groups) */
- H5G_STORAGE_TYPE_COMPACT, /* Links are stored in object header */
- H5G_STORAGE_TYPE_DENSE /* Links are stored in fractal heap & indexed with v2 B-tree */
+ H5G_STORAGE_TYPE_UNKNOWN = -1, /**< Unknown link storage type */
+ H5G_STORAGE_TYPE_SYMBOL_TABLE, /**< Links in group are stored with a "symbol table" */
+ /**< (this is sometimes called "old-style" groups) */
+ H5G_STORAGE_TYPE_COMPACT, /**< Links are stored in object header */
+ H5G_STORAGE_TYPE_DENSE /**< Links are stored in fractal heap & indexed with v2 B-tree */
} H5G_storage_type_t;
+//! <!-- [H5G_storage_t_snip] -->
-/* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */
-//! [H5G_info_t_snip]
+//! <!-- [H5G_info_t_snip] -->
+/**
+ * Information struct for group for
+ * H5Gget_info(), H5Gget_info_by_name(), and H5Gget_info_by_idx()
+ */
typedef struct H5G_info_t {
- H5G_storage_type_t storage_type; /* Type of storage for links in group */
- hsize_t nlinks; /* Number of links in group */
- int64_t max_corder; /* Current max. creation order value for group */
- hbool_t mounted; /* Whether group has a file mounted on it */
+ H5G_storage_type_t storage_type; /**< Type of storage for links in group */
+ hsize_t nlinks; /**< Number of links in group */
+ int64_t max_corder; /**< Current max. creation order value for group */
+ hbool_t mounted; /**< Whether group has a file mounted on it */
} H5G_info_t;
-//! [H5G_info_t_snip]
+//! <!-- [H5G_info_t_snip] -->
/********************/
/* Public Variables */
@@ -120,24 +127,8 @@ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcp
/**
* --------------------------------------------------------------------------
- * \ingroup H5G
- *
- * \brief Asynchronous version of H5Gcreate2()
- *
- * \app_file
- * \app_func
- * \app_line
- * \fgdta_loc_id
- * \param[in] name Name of the group to create
- * \lcpl_id
- * \gcpl_id
- * \gapl_id
- * \es_id
- *
- * \return \hid_t{group}
- *
- * \see H5Gcreate2()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gcreate}
*/
H5_DLL hid_t H5Gcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t es_id);
@@ -223,22 +214,8 @@ H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id);
/**
* --------------------------------------------------------------------------
- * \ingroup H5G
- *
- * \brief Asynchronous version of H5Gopen2()
- *
- * \app_file
- * \app_func
- * \app_line
- * \fgdta_loc_id
- * \param[in] name Name of the group to open
- * \gapl_id
- * \es_id
- *
- * \return \hid_t{group}
- *
- * \see H5Gopen2()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gopen}
*/
H5_DLL hid_t H5Gopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
const char *name, hid_t gapl_id, hid_t es_id);
@@ -296,21 +273,8 @@ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo);
/**
* --------------------------------------------------------------------------
- * \ingroup H5G
- *
- * \brief Asynchronous version of H5Gget_info()
- *
- * \app_file
- * \app_func
- * \app_line
- * \fgdta_loc_id
- * \param[out] ginfo Struct in which group information is returned
- * \es_id
- *
- * \return \hid_t{group}
- *
- * \see H5Gget_info()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gget_info}
*/
H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id,
H5G_info_t *ginfo /*out*/, hid_t es_id);
@@ -351,23 +315,8 @@ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *gi
/**
* --------------------------------------------------------------------------
- * \ingroup H5G
- *
- * \brief Asynchronous version of H5Gget_info_by_name()
- *
- * \app_file
- * \app_func
- * \app_line
- * \fgdta_loc_id
- * \param[in] name Name of the group to query
- * \param[out] ginfo Struct in which group information is returned
- * \lapl_id
- * \es_id
- *
- * \return \herr_t
- *
- * \see H5Gget_info_by_name()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gget_info_by_name}
*/
H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *name, H5G_info_t *ginfo /*out*/,
@@ -423,29 +372,8 @@ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_
/**
* --------------------------------------------------------------------------
- * \ingroup H5G
- *
- * \brief Asynchronous version of H5Gcreate2()
- *
- * \app_file
- * \app_func
- * \app_line
- * \fgdta_loc_id
- * \param[in] group_name Name of the group to query
- * \param[in] idx_type Transient index identifying object
- * \param[in] order Transient index identifying object
- * \param[in] n Position in the index of the group to query
- * \param[out] ginfo Struct in which group information is returned
- * \lapl_id
- * \es_id
- *
- * \return Returns
- * \li The size of the object name if successful, or
- * \li 0 if no name is associated with the group identifier, or
- * \li negative value, if failure occurred
- *
- * \see H5Gcreate2()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gget_info_by_idx}
*/
H5_DLL herr_t H5Gget_info_by_idx_async(const char *app_file, const char *app_func, unsigned app_line,
hid_t loc_id, const char *group_name, H5_index_t idx_type,
@@ -523,29 +451,18 @@ H5_DLL herr_t H5Grefresh(hid_t group_id);
* Failure to release a group with this call will result in
* resource leaks.
*
- * \since 1.0.0
+ * \par Example
+ * \snippet H5F_examples.c mount
*
- * \version 1.4.0 Fortran function introduced in this release
+ * \since 1.0.0
*
*/
H5_DLL herr_t H5Gclose(hid_t group_id);
/**
* --------------------------------------------------------------------------
- * \ingroup H5G
- *
- * \brief Asynchronous version of H5Gcreate2()
- *
- * \app_file
- * \app_func
- * \app_line
- * \group_id
- * \es_id
- *
- * \return \herr_t
- *
- * \see H5Gcreate2()
- *
+ * \ingroup ASYNC
+ * \async_variant_of{H5Gclose}
*/
H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id,
hid_t es_id);
@@ -595,60 +512,649 @@ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigne
/* Typedefs */
-/*
+//! <!-- [H5G_obj_t_snip] -->
+/**
* An object has a certain type. The first few numbers are reserved for use
* internally by HDF5. Users may add their own types with higher values. The
- * values are never stored in the file -- they only exist while an
- * application is running. An object may satisfy the `isa' function for more
- * than one type.
+ * values are never stored in the file -- they only exist while an application
+ * is running. An object may satisfy the `isa' function for more than one type.
+ *
+ * \deprecated
*/
typedef enum H5G_obj_t {
- H5G_UNKNOWN = -1, /* Unknown object type */
- H5G_GROUP, /* Object is a group */
- H5G_DATASET, /* Object is a dataset */
- H5G_TYPE, /* Object is a named data type */
- H5G_LINK, /* Object is a symbolic link */
- H5G_UDLINK, /* Object is a user-defined link */
- H5G_RESERVED_5, /* Reserved for future use */
- H5G_RESERVED_6, /* Reserved for future use */
- H5G_RESERVED_7 /* Reserved for future use */
+ H5G_UNKNOWN = -1, /**< Unknown object type */
+ H5G_GROUP, /**< Object is a group */
+ H5G_DATASET, /**< Object is a dataset */
+ H5G_TYPE, /**< Object is a named data type */
+ H5G_LINK, /**< Object is a symbolic link */
+ H5G_UDLINK, /**< Object is a user-defined link */
+ H5G_RESERVED_5, /**< Reserved for future use */
+ H5G_RESERVED_6, /**< Reserved for future use */
+ H5G_RESERVED_7 /**< Reserved for future use */
} H5G_obj_t;
+//! <!-- [H5G_obj_t_snip] -->
-/** Define the operator function pointer for for H5Giterate() */
-//! [H5G_iterate_t_snip]
+//! <!-- [H5G_iterate_t_snip] -->
+/**
+ * Callback for H5Giterate()
+ *
+ * \deprecated
+ */
typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data);
-//! [H5G_iterate_t_snip]
+//! <!-- [H5G_iterate_t_snip] -->
-/** Information about an object */
-//! [H5G_stat_t_snip]
+//! <!-- [H5G_stat_t_snip] -->
+/**
+ * Information about an object
+ *
+ * \deprecated
+ */
typedef struct H5G_stat_t {
- unsigned long fileno[2]; /*file number */
- unsigned long objno[2]; /*object number */
- unsigned nlink; /*number of hard links to object*/
- H5G_obj_t type; /*basic object type */
- time_t mtime; /*modification time */
- size_t linklen; /*symbolic link value length */
- H5O_stat_t ohdr; /* Object header information */
+ unsigned long fileno[2]; /**< file number */
+ unsigned long objno[2]; /**< object number */
+ unsigned nlink; /**< number of hard links to object*/
+ H5G_obj_t type; /**< basic object type */
+ time_t mtime; /**< modification time */
+ size_t linklen; /**< symbolic link value length */
+ H5O_stat_t ohdr; /**< Object header information */
} H5G_stat_t;
-//! [H5G_stat_t_snip]
+//! <!-- [H5G_stat_t_snip] -->
/* Function prototypes */
-H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);
-H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name);
-H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name);
-H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id,
- const char *new_name);
-H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name);
-H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name);
-H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name);
-H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/);
-H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment);
-H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf);
-H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data);
-H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);
-H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link,
- H5G_stat_t *statbuf /*out*/);
-H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Creates a new group and links it into the file
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the group to create
+ * \param[in] size_hint Optional parameter indicating the number of bytes
+ * to reserve for the names that will appear in the group
+ *
+ * \return \hid_t{group}
+ *
+ * \deprecated This function is deprecated in favor of H5Gcreate2().
+ *
+ * \details H5Gcreate1() creates a new group with the specified name at the
+ * specified location, \p loc_id. \p loc_id may be a file, group,
+ * dataset, named datatype or attribute. If an attribute, dataset, or
+ * named datatype is specified for \p loc_id then the group will be
+ * created at the location where the attribute, dataset, or named
+ * datatype is attached. The name, name, must not already be taken by
+ * some other object and all parent groups must already exist.
+ *
+ * \p name can be a relative path based at \p loc_id or an absolute
+ * path from the root of the file. Use of this function requires that
+ * any intermediate groups specified in the path already exist.
+ *
+ * The length of a group name, or of the name of any object within a
+ * group, is not limited.
+ *
+ * \p size_hint is a hint for the number of bytes to reserve to store
+ * the names which will be eventually added to the new group. Passing a
+ * value of zero for \p size_hint is usually adequate since the library
+ * is able to dynamically resize the name heap, but a correct hint may
+ * result in better performance. If a non-positive value is supplied
+ * for \p size_hint, then a default size is chosen.
+ *
+ * The return value is a group identifier for the open group. This
+ * group identifier should be closed by calling H5Gclose() when it is
+ * no longer needed.
+ *
+ * See H5Gcreate_anon() for a discussion of the differences between
+ * H5Gcreate1() and H5Gcreate_anon().
+ *
+ * \par Example
+ * \snippet H5F_examples.c mount
+ *
+ * \version 1.8.0 Function H5Gcreate() renamed to H5Gcreate1() and deprecated
+ * in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Opens an existing group for modification and returns a group
+ * identifier for that group
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the group to open
+ *
+ * \return \hid_t{group}
+ *
+ * \deprecated This function is deprecated in favor of H5Gopen2().
+ *
+ * \details H5Gopen1() opens an existing group, \p name, at the location
+ * specified by \p loc_id.
+ *
+ * H5Gopen1() returns a group identifier for the group that was
+ * opened. This group identifier should be released by calling
+ * H5Gclose() when it is no longer needed.
+ *
+ * \version 1.8.0 The function H5Gopen() was renamed to H5Gopen1()
+ * and deprecated in this release.
+ * \since 1.0.0
+ *
+ */
+H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Creates a link of the specified type from \p new_name to \p
+ * cur_name
+ *
+ * \fg_loc_id{cur_loc_id}
+ * \param[in] type Link type
+ * \param[in] cur_name Name of the existing object
+ * \param[in] new_name New name for the object
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Glink() creates a new name for an object that has some current
+ * name, possibly one of many names it currently has.
+ *
+ * If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify
+ * the name of an existing object and both names are interpreted
+ * relative to \p cur_loc_id, which is either a file identifier or a
+ * group identifier.
+ *
+ * If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything
+ * and is interpreted at lookup time relative to the group which
+ * contains the final component of \p new_name. For instance, if \p
+ * cur_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a
+ * request is made for \Code{./x/y/bar}, then the actual object looked
+ * up is \Code{./x/y/./foo}.
+
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Creates a link of the specified type from \p cur_name to \p
+ * new_name
+ *
+ * \fg_loc_id{cur_loc_id}
+ * \param[in] cur_name Name of the existing object
+ * \param[in] type Link type
+ * \fg_loc_id{new_loc_id}
+ * \param[in] new_name New name for the object
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Glink2() creates a new name for an object that has some current
+ * name, possibly one of many names it currently has.
+ *
+ * If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify the
+ * name of an existing object and both names are interpreted relative
+ * to \p cur_loc_id and \p new_loc_id, respectively, which are either
+ * file identifiers or group identifiers.
+ *
+ * If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything
+ * and is interpreted at lookup time relative to the group which
+ * contains the final component of \p new_name. For instance, if \p
+ * current_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a
+ * request is made for \Code{./x/y/bar}, then the actual object looked
+ * up is \Code{./x/y/./foo}.
+
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id,
+ const char *new_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Renames an object within an HDF5 file
+ *
+ * \fg_loc_id{src_loc_id}
+ * \param[in] src_name Object's original name
+ * \param[in] dst_name Object's new name
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Gmove() renames an object within an HDF5 file. The original name,
+ * \p src_name, is unlinked from the group graph and the new name, \p
+ * dst_name, is inserted as an atomic operation. Both names are
+ * interpreted relative to \p loc_id, which is either a file or a group
+ * identifier.
+ *
+ * \attention Exercise care in moving groups as it is possible to render data in
+ * a file inaccessible with H5Gmove(). See The Group Interface in the
+ * HDF5 User's Guide.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Renames an object within an HDF5 file
+ *
+ * \fg_loc_id{src_loc_id}
+ * \param[in] src_name Object's original name
+ * \fg_loc_id{dst_loc_id}
+ * \param[in] dst_name Object's new name
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated.
+ *
+ * \details H5Gmove2() renames an object within an HDF5 file. The original name,
+ * \p src_name, is unlinked from the group graph and the new name, \p
+ * dst_name, is inserted as an atomic operation.
+ *
+ * \p src_name and \p dst_name are interpreted relative to \p
+ * src_loc_id and \p dst_loc_id, respectively, which are either file or
+ * group identifiers.
+ *
+ * \attention Exercise care in moving groups as it is possible to render data in
+ * a file inaccessible with H5Gmove2(). See The Group Interface in the
+ * HDF5 User's Guide.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Removes the link to an object from a group
+ *
+ * \fg_loc_id{loc_id}
+ * \param[in] name Name of the object to unlink
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function H5Ldelete().
+ *
+ * \details H5Gunlink() removes the object specified by \p name from the group
+ * graph and decrements the link count for the object to which \p name
+ * points. This action eliminates any association between name and the
+ * object to which name pointed.
+ *
+ * Object headers keep track of how many hard links refer to an object;
+ * when the link count reaches zero, the object can be removed from the
+ * file. Objects which are open are not removed until all identifiers
+ * to the object are closed.
+ *
+ * If the link count reaches zero, all file space associated with the
+ * object will be released, i.e., identified in memory as freespace. If
+ * any object identifier is open for the object, the space will not be
+ * released until after the object identifier is closed.
+ *
+ * Note that space identified as freespace is available for re-use only
+ * as long as the file remains open; once a file has been closed, the
+ * HDF5 library loses track of freespace. See “Freespace Management” in
+ * the HDF5 User's Guide for further details.
+ *
+ * \attention Exercise care in moving groups as it is possible to render data in
+ * a file inaccessible with H5Gunlink(). See The Group Interface in the
+ * HDF5 User's Guide.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns the name of the object that the symbolic link points to
+ *
+ * \fg_loc_id{loc_id}
+ * \param[in] name Symbolic link to the object whose name is to be returned
+ * \param[in] size Maximum number of characters of value to be returned
+ * \param[out] buf A buffer to hold the name of the object being sought
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function H5Lget_val().
+ *
+ * \details H5Gget_linkval() returns up to size characters of the name of the
+ * object that the symbolic link name points to.
+ *
+ * The parameter \p loc_id is a file or group identifier.
+ *
+ * The parameter \p name must be a symbolic link pointing to the
+ * desired object and must be defined relative to \p loc_id.
+ *
+ * If size is smaller than the size of the returned object name, then
+ * the name stored in the buffer value will not be \c NULL terminated.
+ *
+ * This function fails if \p name is not a symbolic link. The presence
+ * of a symbolic link can be tested by passing zero for \p size and \p
+ * NULL for value.
+ *
+ * This function should be used only after H5Lget_info1() (or the
+ * deprecated function H5Gget_objinfo()) has been called to verify that
+ * name is a symbolic link.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Sets comment for specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of the object whose comment is to be set or reset
+ * name must be \Code{'.'} (dot) if \p loc_id fully specifies
+ * the object for which the comment is to be set.
+ * \param[in] comment The new comment
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function
+ * H5Oset_comment().
+ *
+ * \details H5Gset_comment() sets the comment for the object specified by \p
+ * loc_id and name to comment. Any previously existing comment is
+ * overwritten.
+ *
+ * \p loc_id can specify any object in the file. name can be one of the
+ * following:
+ * \li The name of the object relative to \p loc_id
+ * \li An absolute name of the object, starting from \c /, the file’s
+ * root group
+ * \li A dot (\c .), if \p loc_id fully specifies the object
+ *
+ * If \p comment is the empty string or a null pointer, the comment
+ * message is removed from the object.
+ *
+ * Comments should be relatively short, null-terminated, ASCII strings.
+ *
+ * Comments can be attached to any object that has an object header,
+ * e.g., datasets, groups, and named datatypes, but not symbolic links.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Retrieves comment for specified object
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of the object whose comment is to be set or reset
+ * name must be \Code{'.'} (dot) if \p loc_id fully specifies
+ * the object for which the comment is to be set.
+ * \param[in] bufsize Maximum number of comment characters to be returned in \p buf.
+ * \param[in] buf The comment
+ *
+ * \return Returns the number of characters in the comment, counting the \c NULL
+ * terminator, if successful; the value returned may be larger than
+ * \p bufsize. Otherwise returns a negative value.
+ *
+ * \deprecated This function is deprecated in favor of the function
+ * H5Oget_comment().
+ *
+ * \details H5Gget_comment() retrieves the comment for the the object specified
+ * by \p loc_id and \p name. The comment is returned in the buffer \p
+ * buf.
+ *
+ * \p loc_id can specify any object in the file. name can be one of the
+ * following:
+ * \li The name of the object relative to \p loc_id
+ * \li An absolute name of the object, starting from \c /, the file’s
+ * root group
+ * \li A dot (\c .), if \p loc_id fully specifies the object
+ *
+ * At most bufsize characters, including a null-terminator, are
+ * returned in \p buf. The returned value is not null-terminated if the
+ * comment is longer than the supplied buffer. If the size of the
+ * comment is unknown, a preliminary \p H5Gget_comment() call will
+ * return the size of the comment, including space for the
+ * null-terminator.
+ *
+ * If an object does not have a comment, the empty string is returned
+ * in comment.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Iterates over the entries of a group invoking a callback for each
+ * entry encountered
+ *
+ * \fg_loc_id
+ * \param[in] name Group over which the iteration is performed
+ * \param[in,out] idx Location at which to begin the iteration
+ * \param[in] op Operation to be performed on an object at each step of the
+ * iteration
+ * \param[in,out] op_data Data associated with the operation
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function
+ * H5Literate1().
+ *
+ * \details H5Giterate() iterates over the members of name in the file or group
+ * specified with \p loc_id. For each object in the group, the \p
+ * op_data and some additional information, specified below, are passed
+ * to the operator function. The iteration begins with the \p idx
+ * object in the group and the next element to be processed by the
+ * operator is returned in \p idx. If \p idx is NULL, then the iterator
+ * starts at the first group member; since no stopping point is
+ * returned in this case, the iterator cannot be restarted if one of
+ * the calls to its operator returns non-zero. H5Giterate() does not
+ * recursively follow links into subgroups of the specified group.
+ *
+ * The prototype for \ref H5G_iterate_t is:
+ * \snippet this H5G_iterate_t_snip
+ *
+ * The operation receives the group identifier for the group being
+ * iterated over, \p group, the name of the current object within
+ * the group, \p name, and the pointer to the operator data
+ * passed in to H5Giterate(), \p op_data.
+ *
+ * The return values from an operator are:
+ * \li Zero causes the iterator to continue, returning zero when all
+ * group members have been processed.
+ * \li Positive causes the iterator to immediately return that positive
+ * value, indicating short-circuit success. The iterator can be
+ * restarted at the next group member.
+ * \li Negative causes the iterator to immediately return that value,
+ * indicating failure. The iterator can be restarted at the next
+ * group member.
+ *
+ * H5Giterate() assumes that the membership of the group identified by
+ * \p name remains unchanged through the iteration. If the membership
+ * changes during the iteration, the function's behavior is undefined.
+ *
+ * H5Giterate() is not recursive. In particular, if a member of \p name
+ * is found to be a group, call it \c subgroup_a, H5Giterate() does not
+ * examine the members of \c subgroup_a. When recursive iteration is
+ * required, the application must handle the recursion, explicitly
+ * calling H5Giterate() on discovered subgroups.
+
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns number of objects in the group specified by its identifier
+ *
+ * \fg_loc_id
+ * \param[out] num_objs Number of objects in the group
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the function H5Gget_info().
+ *
+ * \details H5Gget_num_objs() returns number of objects in a group. Group is
+ * specified by its identifier \p loc_id. If a file identifier is
+ * passed in, then the number of objects in the root group is returned.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ *
+ */
+H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns information about an object.
+ *
+ * \fgdt_loc_id
+ * \param[in] name Name of the object for which status is being sought
+ * \param[in] follow_link Link flag
+ * \param[out] statbuf Buffer in which to return information about the object
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function is deprecated in favor of the functions H5Oget_info()
+ * and H5Lget_info1().
+ *
+ * \details H5Gget_objinfo() returns information about the specified object
+ * through the \p statbuf argument.
+ *
+ * A file or group identifier, \p loc_id, and an object name, \p name,
+ * relative to \p loc_id, are commonly used to specify the
+ * object. However, if the object identifier is already known to the
+ * application, an alternative approach is to use that identifier, \c
+ * obj_id, in place of \p loc_id, and a dot (\c .) in place of \p
+ * name. Thus, the alternative versions of the first portion of an
+ * H5Gget_objinfo() call would be as follows:
+ * \code
+ * H5Gget_objinfo (loc_id name ...)
+ * H5Gget_objinfo (obj_id . ...)
+ * \endcode
+ *
+ * If the object is a symbolic link and follow_link is zero (0), then
+ * the information returned describes the link itself; otherwise the
+ * link is followed and the information returned describes the object
+ * to which the link points. If \p follow_link is non-zero but the
+ * final symbolic link is dangling (does not point to anything), then
+ * an error is returned. The \p statbuf fields are undefined for an
+ * error. The existence of an object can be tested by calling this
+ * function with a \c NULL \p statbuf.
+ *
+ * H5Gget_objinfo() fills in the following data structure (defined in
+ * H5Gpublic.h):
+ * \snippet this H5G_stat_t_snip
+ *
+ * where \ref H5O_stat_t (defined in H5Opublic.h) is:
+ * \snippet H5Opublic.h H5O_stat_t_snip
+ *
+ * \attention Some systems will be able to record the time accurately but unable
+ * to retrieve the correct time; such systems (e.g., Irix64) will
+ * report an \c mtime value of 0 (zero).
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ * \version 1.6.1 Two new fields were added to the \ref H5G_stat_t struct in
+ * this release.
+ *
+ */
+H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link,
+ H5G_stat_t *statbuf /*out*/);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns a name of an object specified by an index
+ *
+ * \fg_loc_id
+ * \param[in] idx Transient index identifying object
+ * \param[in,out] name Pointer to user-provided buffer the object name
+ * \param[in] size Name length
+ *
+ * \return Returns the size of the object name if successful, or 0 if no name is
+ * associated with the group identifier. Otherwise returns a negative
+ * value.
+ *
+ * \deprecated This function is deprecated in favor of the function H5Lget_name_by_idx().
+ *
+ * \details H5Gget_objname_by_idx() returns a name of the object specified by
+ * the index \p idx in the group \p loc_id.
+ *
+ * The group is specified by a group identifier \p loc_id. If
+ * preferred, a file identifier may be passed in \p loc_id; that file's
+ * root group will be assumed.
+ *
+ * \p idx is the transient index used to iterate through the objects in
+ * the group. The value of \p idx is any nonnegative number less than
+ * the total number of objects in the group, which is returned by the
+ * function H5Gget_num_objs(). Note that this is a transient index; an
+ * object may have a different index each time a group is opened.
+ *
+ * The object name is returned in the user-specified buffer \p name.
+ *
+ * If the size of the provided buffer \p name is less or equal the
+ * actual object name length, the object name is truncated to
+ * \Code{max_size - 1} characters.
+ *
+ * Note that if the size of the object's name is unkown, a preliminary
+ * call to H5Gget_objname_by_idx() with \p name set to \c NULL will
+ * return the length of the object's name. A second call to
+ * H5Gget_objname_by_idx() can then be used to retrieve the actual
+ * name.
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ * \since 1.6.0
+ *
+ */
+H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Returns the type of an object specified by an index
+ *
+ * \fg_loc_id
+ * \param[in] idx Transient index identifying object
+ *
+ * \return Returns the type of the object if successful. Otherwise returns a
+ * negative value.
+ *
+ * \deprecated This function is deprecated in favor of the function H5Oget_info().
+ *
+ * \details H5Gget_objtype_by_idx() returns the type of the object specified by
+ * the index \p idx in the group \p loc_id.
+ *
+ * The group is specified by a group identifier \p loc_id. If
+ * preferred, a file identifier may be passed in \p loc_id; that file's
+ * root group will be assumed.
+ *
+ * \p idx is the transient index used to iterate through the objects in
+ * the group. This parameter is described in more detail in the
+ * discussion of H5Gget_objname_by_idx().
+ *
+ * \version 1.8.0 Function deprecated in this release.
+ * \version 1.6.0 The function return type changed from \c int to the enumerated
+ * type \ref H5G_obj_t.
+ * \since 1.6.0
+ *
+ */
H5_DLL H5G_obj_t H5Gget_objtype_by_idx(hid_t loc_id, hsize_t idx);
#endif /* H5_NO_DEPRECATED_SYMBOLS */