summaryrefslogtreecommitdiffstats
path: root/src/H5Gpublic.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/H5Gpublic.h')
-rw-r--r--src/H5Gpublic.h337
1 files changed, 335 insertions, 2 deletions
diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h
index f209c3d..e46bef6 100644
--- a/src/H5Gpublic.h
+++ b/src/H5Gpublic.h
@@ -51,12 +51,15 @@ typedef enum H5G_storage_type_t {
} H5G_storage_type_t;
/* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */
+//! [H5G_info_t_snip]
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_info_t;
+//! [H5G_info_t_snip]
+
/********************/
/* Public Variables */
@@ -69,29 +72,355 @@ typedef struct H5G_info_t {
extern "C" {
#endif
+/**
+ *-------------------------------------------------------------------------
+ * \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
+ * \lcpl_id
+ * \gcpl_id
+ * \gapl_id
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gcreate2() creates a new group in a file. After a
+ * group has been created, links to datasets and to other groups
+ * can be added.
+ *
+ * The \p loc_id and \p name parameters specify where the group
+ * is located. \p loc_id may be a file, group, dataset, named
+ * datatype or attribute in the file. 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. \p name is the link to the group;
+ * \p name may be either an absolute path in the file (the links
+ * from the root group to the new group) or a relative path from
+ * \p loc_id (the link(s) from the group specified by \p loc_id
+ * to the new group).
+ *
+ * \p lcpl_id, \p gcpl_id, and \p gapl_id are property list
+ * identifiers. These property lists govern how the link to the
+ * group is created, how the group is created, and how the group
+ * can be accessed in the future, respectively. #H5P_DEFAULT can
+ * be passed in if the default properties are appropriate for
+ * these property lists. Currently, there are no APIs for the
+ * group access property list; use #H5P_DEFAULT.
+ *
+ * The group identifier should be closed by H5Gclose() when access
+ * is no longer required to prevent resource leaks.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gopen2(), H5Gclose()
+ *
+ */
H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id);
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);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Creates a new empty group without linking it into the file structure
+ *
+ * \fgdta_loc_id
+ * \gcpl_id
+ * \gapl_id
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gcreate_anon() creates a new empty group in the file
+ * specified by \p loc_id. With default settings, H5Gcreate_anon()
+ * provides similar functionality to that provided by
+ * H5Gcreate1(), with the differences described in the list below.
+ *
+ * The new group’s creation and access properties are specified
+ * in \p gcpl_id and \p gapl_id, respectively.
+ *
+ * H5Gcreate_anon() returns a new group identifier. This identifier
+ * must be linked into the HDF5 file structure with H5Olink()
+ * or it will be deleted from the file when the file is closed.
+ *
+ * The differences between this function and H5Gcreate1() are
+ * as follows:
+ *
+ * \li H5Gcreate1() does not provide for the use of custom property
+ * lists; H5Gcreate1() always uses default properties.
+ * \li H5Gcreate_anon() neither provides the new group’s name
+ * nor links it into the HDF5 file structure; those actions
+ * must be performed separately through a call to H5Olink(),
+ * which offers greater control over linking.
+ * \li H5Gcreate_anon() does not directly provide a hint mechanism
+ * for the group’s heap size. Comparable information can be
+ * included in the group creation property list \p gcpl_id through
+ * a H5Pset_local_heap_size_hint() call.
+ *
+ * A group created with this function should be closed with
+ * H5Gclose() when the group is no longer needed so that resource
+ * leaks will not develop.
+ *
+ * \see H5Olink(), H5Dcreate(), Using Identifiers
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Opens an existing group in a file
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the group to open
+ * \gapl_id
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gopen2() opens an existing group, \p name, at the location
+ * specified by \p loc_id.
+ *
+ * With default settings, H5Gopen2() provides similar functionality
+ * to that provided by H5Gopen(). The only difference is that
+ * H5Gopen2() can provide a group access property list, \p gapl_id.
+ *
+ * H5Gopen2() returns a group identifier for the group that was
+ * opened. This group identifier should be released by H5Gclose()
+ * when it is no longer needed to prevent resource leaks.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id);
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);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Gets a group creation property list identifier
+ *
+ * \group_id
+ *
+ * \return \hid_t{creation property list}
+ *
+ * \details H5Gget_create_plist() returns an identifier for the group creation
+ * property list associated with the group specified by \p group_id.
+ *
+ * The creation property list identifier should be released with
+ * H5Gclose() to prevent resource leaks.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
H5_DLL hid_t H5Gget_create_plist(hid_t group_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Retrieves information about a group
+ *
+ * \fgdta_loc_id
+ * \param[out] ginfo Struct in which group information is returned
+ *
+ * \return \hid_t{group}
+ *
+ * \details H5Gget_info() retrieves information about the group at location
+ * specified by \p loc_id. The information is returned in the \p ginfo.
+ *
+ * \p ginfo is an H5G_info_t struct and is defined (in H5Gpublic.h)
+ * as follows:
+ *
+ * \snippet this H5G_info_t_snip
+ * Possible values of \p storage_type are:
+ * \storage_type
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo);
+
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 *group_info /*out*/, hid_t es_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Retrieves information about a group by its name
+ *
+ * \fgdta_loc_id
+ * \param[in] name Name of the group to query
+ * \param[out] ginfo Struct in which group information is returned
+ * \lapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Gget_info_by_name() retrieves information about the group \p name
+ * at location specified by \p loc_id. The information is returned in
+ * the \p ginfo struct.
+ *
+ * If \p loc_id specifies the group for which information is queried,
+ * then the group's \p name can be a dot (.).
+ *
+ * \p ginfo is an H5G_info_t struct and is defined (in H5Gpublic.h)
+ * as follows:
+ *
+ * \snippet this H5G_info_t_snip
+ * Possible values of \p storage_type are:
+ * \storage_type
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo, hid_t lapl_id);
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 *group_info /*out*/,
hid_t lapl_id, hid_t es_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Retrieves information about a group, according to the group’s
+ * position within an index
+ *
+ * \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
+ *
+ * \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
+ *
+ * \details H5Gget_info_by_idx() retrieves the same information
+ * about a group as retrieved by the function H5Gget_info(),
+ * but the means of identifying the group differs; the group is
+ * identified by position in an index rather than by name.
+ *
+ * \p loc_id and \p group_name specify the group containing
+ * the group for which information is sought. The groups in \p
+ * group_name are indexed by \p idx_type; the group for which
+ * information is retrieved is identified in that index by index
+ * order, \p order, and index position, \p n.
+ *
+ * If \p loc_id specifies the group containing the group for
+ * which information is queried, \p group_name can be a dot (.).
+ *
+ * Valid values for \p index_type are as follows:
+ * \indexes
+ * The order in which the index is to be examined, as specified
+ * by \p order, can be one of the following:
+ * \orders
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type,
H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo, hid_t lapl_id);
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,
H5_iter_order_t order, hsize_t n, H5G_info_t *group_info /*out*/,
hid_t lapl_id, hid_t es_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Flushes all buffers associated with a group to disk
+ *
+ * \group_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Gflush() causes all buffers associated with a group to be
+ * immediately flushed to disk without removing the data from
+ * the cache.
+ *
+ * \attention
+ * HDF5 does not possess full control over buffering. H5G_FLUSH
+ * flushes the internal HDF5 buffers and then asks the operating
+ * system (the OS) to flush the system buffers for the open
+ * files. After that, the OS is responsible for ensuring that
+ * the data is actually flushed to disk.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
H5_DLL herr_t H5Gflush(hid_t group_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Refreshes all buffers associated with a group
+ *
+ * \group_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Grefresh() causes all buffers associated with a group to be
+ * cleared and immediately re-loaded with updated contents from disk.
+ *
+ * This function essentially closes the group, evicts all
+ * metadata associated with it from the cache, and then re-opens
+ * the group. The reopened group is automatically re-registered
+ * with the same identifier.
+ *
+ * \since 1.8.0
+ *
+ * \see H5Gcreate2(), H5Gclose()
+ *
+ */
H5_DLL herr_t H5Grefresh(hid_t group_id);
+
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5G
+ *
+ * \brief Closes the specified group
+ *
+ * \group_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Gclose() releases resources used by a group which was
+ * opened by H5Gcreate() or H5Gopen(). After closing a group,
+ * \p group_id cannot be used again until another H5Gcreate()
+ * or H5Gopen() is called on it.
+ *
+ * Failure to release a group with this call will result in
+ * resource leaks.
+ *
+ * \since 1.0.0
+ *
+ * \version 1.4.0 Fortran function introduced in this release
+ *
+ */
H5_DLL herr_t H5Gclose(hid_t group_id);
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);
@@ -160,10 +489,13 @@ typedef enum H5G_obj_t {
H5G_RESERVED_7 /* Reserved for future use */
} H5G_obj_t;
-/* Prototype for H5Giterate() operator */
+/** Define the operator function pointer for for H5Giterate() */
+//! [H5G_iterate_t_snip]
typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data);
+//! [H5G_iterate_t_snip]
-/* Information about an object */
+/** Information about an object */
+//! [H5G_stat_t_snip]
typedef struct H5G_stat_t {
unsigned long fileno[2]; /*file number */
unsigned long objno[2]; /*object number */
@@ -173,6 +505,7 @@ typedef struct H5G_stat_t {
size_t linklen; /*symbolic link value length */
H5O_stat_t ohdr; /* Object header information */
} H5G_stat_t;
+//! [H5G_stat_t_snip]
/* Function prototypes */
H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint);