summaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorGerd Heber <gheber@hdfgroup.org>2020-11-10 20:57:54 (GMT)
committerGitHub <noreply@github.com>2020-11-10 20:57:54 (GMT)
commitc0c0b6b47ffaebd158da055d04b9e9f88d8730ef (patch)
tree8d60ea50a86559873d0cdac9b1828ea90779e898 /src
parent9cc9107dfa34b4f28a6ed4d80ebf7e7182fe6809 (diff)
parent29b8231f92fb6b8da5e79e9f702135dec9819d07 (diff)
downloadhdf5-c0c0b6b47ffaebd158da055d04b9e9f88d8730ef.zip
hdf5-c0c0b6b47ffaebd158da055d04b9e9f88d8730ef.tar.gz
hdf5-c0c0b6b47ffaebd158da055d04b9e9f88d8730ef.tar.bz2
Merge pull request #78 from gheber/develop
This is the first installment of Doxygen-based documentation for the H5F module.
Diffstat (limited to 'src')
-rw-r--r--src/H5Fmodule.h13
-rw-r--r--src/H5Fpublic.h1314
-rw-r--r--src/H5public.h6
3 files changed, 1230 insertions, 103 deletions
diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h
index 953b4da..d57926f 100644
--- a/src/H5Fmodule.h
+++ b/src/H5Fmodule.h
@@ -29,4 +29,17 @@
#define H5_MY_PKG_ERR H5E_FILE
#define H5_MY_PKG_INIT YES
+/**
+ * \defgroup H5F H5F
+ * \brief File Interface
+ * \todo Describe concisely what the functions in this module are about.
+ *
+ * \defgroup MDC Metadata Cache
+ * \ingroup H5F
+ * \defgroup PH5F Parallel
+ * \ingroup H5F
+ * \defgroup SWMR Single Writer Multiple Readers
+ * \ingroup H5F
+ */
+
#endif /* _H5Fmodule_H */
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index b84cff6..be8eced 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -47,24 +47,20 @@
* We're assuming that these constants are used rather early in the hdf5
* session.
*/
-#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /*absence of rdwr => rd-only */
-#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /*open for read and write */
-#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /*overwrite existing files */
-#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /*fail if file already exists*/
+#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< absence of rdwr => rd-only */
+#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< open for read and write */
+#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< overwrite existing files */
+#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< fail if file already exists*/
/* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */
-#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /*create non-existing files */
+#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< create non-existing files */
#define H5F_ACC_SWMR_WRITE \
- (H5CHECK 0x0020u) /*indicate that this file is \
- * open for writing in a \
- * single-writer/multi-reader (SWMR) \
- * scenario. Note that the \
- * process(es) opening the file \
- * for reading must open the file \
- * with RDONLY access, and use \
- * the special "SWMR_READ" access \
- * flag. */
+ (H5CHECK 0x0020u) /**< indicate that this file is open for writing in a \
+ single-writer/multi-reader (SWMR) scenario. \
+ Note that the process(es) opening the file for reading must \
+ open the file with RDONLY access, and use the special "SWMR_READ" \
+ access flag. */
#define H5F_ACC_SWMR_READ \
- (H5CHECK 0x0040u) /*indicate that this file is \
+ (H5CHECK 0x0040u) /**< indicate that this file is \
* open for reading in a \
* single-writer/multi-reader (SWMR) \
* scenario. Note that the \
@@ -73,19 +69,23 @@
* open the file with the RDONLY \
* flag. */
-/* Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the
- * parent file. */
-#define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu) /*ignore setting on lapl */
+/**
+ * Default property list identifier
+ *
+ * \internal Value passed to H5Pset_elink_acc_flags to cause flags to be taken from the parent file.
+ * \internal ignore setting on lapl
+ */
+#define H5F_ACC_DEFAULT (H5CHECK H5OPEN 0xffffu)
/* Flags for H5Fget_obj_count() & H5Fget_obj_ids() calls */
-#define H5F_OBJ_FILE (0x0001u) /* File objects */
-#define H5F_OBJ_DATASET (0x0002u) /* Dataset objects */
-#define H5F_OBJ_GROUP (0x0004u) /* Group objects */
-#define H5F_OBJ_DATATYPE (0x0008u) /* Named datatype objects */
-#define H5F_OBJ_ATTR (0x0010u) /* Attribute objects */
+#define H5F_OBJ_FILE (0x0001u) /**< File objects */
+#define H5F_OBJ_DATASET (0x0002u) /**< Dataset objects */
+#define H5F_OBJ_GROUP (0x0004u) /**< Group objects */
+#define H5F_OBJ_DATATYPE (0x0008u) /**< Named datatype objects */
+#define H5F_OBJ_ATTR (0x0010u) /**< Attribute objects */
#define H5F_OBJ_ALL (H5F_OBJ_FILE | H5F_OBJ_DATASET | H5F_OBJ_GROUP | H5F_OBJ_DATATYPE | H5F_OBJ_ATTR)
-#define H5F_OBJ_LOCAL (0x0020u) /* Restrict search to objects opened through current file ID */
-/* (as opposed to objects opened through any file ID accessing this file) */
+#define H5F_OBJ_LOCAL (0x0020u) /**< Restrict search to objects opened through current file ID
+ (as opposed to objects opened through any file ID accessing this file) */
#define H5F_FAMILY_DEFAULT (hsize_t)0
@@ -99,128 +99,147 @@
#define H5F_MPIO_DEBUG_KEY "H5F_mpio_debug_key"
#endif /* H5_HAVE_PARALLEL */
-/* The difference between a single file and a set of mounted files */
+/**
+ * The difference between a single file and a set of mounted files
+ */
typedef enum H5F_scope_t {
- H5F_SCOPE_LOCAL = 0, /*specified file handle only */
- H5F_SCOPE_GLOBAL = 1 /*entire virtual file */
+ H5F_SCOPE_LOCAL = 0, /**< specified file handle only */
+ H5F_SCOPE_GLOBAL = 1 /**< entire virtual file */
} H5F_scope_t;
-/* Unlimited file size for H5Pset_external() */
+/**
+ * Unlimited file size for H5Pset_external()
+ */
#define H5F_UNLIMITED ((hsize_t)(-1L))
-/* How does file close behave?
- * H5F_CLOSE_DEFAULT - Use the degree pre-defined by underlining VFL
- * H5F_CLOSE_WEAK - file closes only after all opened objects are closed
- * H5F_CLOSE_SEMI - if no opened objects, file is close; otherwise, file
- close fails
- * H5F_CLOSE_STRONG - if there are opened objects, close them first, then
- close file
+/**
+ * How does file close behave?
*/
typedef enum H5F_close_degree_t {
- H5F_CLOSE_DEFAULT = 0,
- H5F_CLOSE_WEAK = 1,
- H5F_CLOSE_SEMI = 2,
- H5F_CLOSE_STRONG = 3
+ H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlining VFL */
+ H5F_CLOSE_WEAK = 1, /**< File closes only after all opened objects are closed */
+ H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is close; otherwise, file close fails */
+ H5F_CLOSE_STRONG = 3 /**< If there are opened objects, close them first, then close file */
} H5F_close_degree_t;
-/* Current "global" information about file */
+/**
+ * Current "global" information about file
+ */
+//! [H5F_info2_t_snip]
typedef struct H5F_info2_t {
struct {
- unsigned version; /* Superblock version # */
- hsize_t super_size; /* Superblock size */
- hsize_t super_ext_size; /* Superblock extension size */
+ unsigned version; /**< Superblock version # */
+ hsize_t super_size; /**< Superblock size */
+ hsize_t super_ext_size; /**< Superblock extension size */
} super;
struct {
- unsigned version; /* Version # of file free space management */
- hsize_t meta_size; /* Free space manager metadata size */
- hsize_t tot_space; /* Amount of free space in the file */
+ unsigned version; /**< Version # of file free space management */
+ hsize_t meta_size; /**< Free space manager metadata size */
+ hsize_t tot_space; /**< Amount of free space in the file */
} free;
struct {
- unsigned version; /* Version # of shared object header info */
- hsize_t hdr_size; /* Shared object header message header size */
- H5_ih_info_t msgs_info; /* Shared object header message index & heap size */
+ unsigned version; /**< Version # of shared object header info */
+ hsize_t hdr_size; /**< Shared object header message header size */
+ H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
} sohm;
} H5F_info2_t;
+//! [H5F_info2_t_snip]
-/*
- * Types of allocation requests. The values larger than H5FD_MEM_DEFAULT
+/**
+ * Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT
* should not change other than adding new types to the end. These numbers
* might appear in files.
*
- * Note: please change the log VFD flavors array if you change this
- * enumeration.
+ * \internal Please change the log VFD flavors array if you change this
+ * enumeration.
*/
typedef enum H5F_mem_t {
- H5FD_MEM_NOLIST = -1, /* Data should not appear in the free list.
+ H5FD_MEM_NOLIST = -1, /**< Data should not appear in the free list.
* Must be negative.
*/
- H5FD_MEM_DEFAULT = 0, /* Value not yet set. Can also be the
+ H5FD_MEM_DEFAULT = 0, /**< Value not yet set. Can also be the
* datatype set in a larger allocation
* that will be suballocated by the library.
* Must be zero.
*/
- H5FD_MEM_SUPER = 1, /* Superblock data */
- H5FD_MEM_BTREE = 2, /* B-tree data */
- H5FD_MEM_DRAW = 3, /* Raw data (content of datasets, etc.) */
- H5FD_MEM_GHEAP = 4, /* Global heap data */
- H5FD_MEM_LHEAP = 5, /* Local heap data */
- H5FD_MEM_OHDR = 6, /* Object header data */
-
- H5FD_MEM_NTYPES /* Sentinel value - must be last */
+ H5FD_MEM_SUPER = 1, /**< Superblock data */
+ H5FD_MEM_BTREE = 2, /**< B-tree data */
+ H5FD_MEM_DRAW = 3, /**< Raw data (content of datasets, etc.) */
+ H5FD_MEM_GHEAP = 4, /**< Global heap data */
+ H5FD_MEM_LHEAP = 5, /**< Local heap data */
+ H5FD_MEM_OHDR = 6, /**< Object header data */
+
+ H5FD_MEM_NTYPES /**< Sentinel value - must be last */
} H5F_mem_t;
-/* Free space section information */
+/**
+ * Free space section information
+ */
+//! [H5F_sect_info_t_snip]
typedef struct H5F_sect_info_t {
- haddr_t addr; /* Address of free space section */
- hsize_t size; /* Size of free space section */
+ haddr_t addr; /**< Address of free space section */
+ hsize_t size; /**< Size of free space section */
} H5F_sect_info_t;
+//! [H5F_sect_info_t_snip]
-/* Library's format versions */
+/**
+ * Library's format versions
+ */
typedef enum H5F_libver_t {
H5F_LIBVER_ERROR = -1,
- H5F_LIBVER_EARLIEST = 0, /* Use the earliest possible format for storing objects */
- H5F_LIBVER_V18 = 1, /* Use the latest v18 format for storing objects */
- H5F_LIBVER_V110 = 2, /* Use the latest v110 format for storing objects */
- H5F_LIBVER_V112 = 3, /* Use the latest v112 format for storing objects */
- H5F_LIBVER_V114 = 4, /* Use the latest v114 format for storing objects */
+ H5F_LIBVER_EARLIEST = 0, /**< Use the earliest possible format for storing objects */
+ H5F_LIBVER_V18 = 1, /**< Use the latest v18 format for storing objects */
+ H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */
+ H5F_LIBVER_V112 = 3, /**< Use the latest v112 format for storing objects */
+ H5F_LIBVER_V114 = 4, /**< Use the latest v114 format for storing objects */
H5F_LIBVER_NBOUNDS
} H5F_libver_t;
#define H5F_LIBVER_LATEST H5F_LIBVER_V114
-/* File space handling strategy */
+/**
+ * File space handling strategy
+ */
typedef enum H5F_fspace_strategy_t {
H5F_FSPACE_STRATEGY_FSM_AGGR =
- 0, /* Mechanisms: free-space managers, aggregators, and virtual file drivers */
- /* This is the library default when not set */
+ 0, /**< Mechanisms: free-space managers, aggregators, and virtual file drivers
+ This is the library default when not set */
H5F_FSPACE_STRATEGY_PAGE =
- 1, /* Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */
- H5F_FSPACE_STRATEGY_AGGR = 2, /* Mechanisms: aggregators and virtual file drivers */
- H5F_FSPACE_STRATEGY_NONE = 3, /* Mechanisms: virtual file drivers */
- H5F_FSPACE_STRATEGY_NTYPES /* must be last */
+ 1, /**< Mechanisms: free-space managers with embedded paged aggregation and virtual file drivers */
+ H5F_FSPACE_STRATEGY_AGGR = 2, /**< Mechanisms: aggregators and virtual file drivers */
+ H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */
+ H5F_FSPACE_STRATEGY_NTYPES /**< Sentinel */
} H5F_fspace_strategy_t;
-/* Deprecated: File space handling strategy for release 1.10.0 */
-/* They are mapped to H5F_fspace_strategy_t as defined above from release 1.10.1 onwards */
+/**
+ * File space handling strategy for release 1.10.0
+ *
+ * \deprecated 1.10.1
+ */
typedef enum H5F_file_space_type_t {
- H5F_FILE_SPACE_DEFAULT = 0, /* Default (or current) free space strategy setting */
- H5F_FILE_SPACE_ALL_PERSIST = 1, /* Persistent free space managers, aggregators, virtual file driver */
- H5F_FILE_SPACE_ALL = 2, /* Non-persistent free space managers, aggregators, virtual file driver */
- /* This is the library default */
- H5F_FILE_SPACE_AGGR_VFD = 3, /* Aggregators, Virtual file driver */
- H5F_FILE_SPACE_VFD = 4, /* Virtual file driver */
- H5F_FILE_SPACE_NTYPES /* must be last */
+ H5F_FILE_SPACE_DEFAULT = 0, /**< Default (or current) free space strategy setting */
+ H5F_FILE_SPACE_ALL_PERSIST = 1, /**< Persistent free space managers, aggregators, virtual file driver */
+ H5F_FILE_SPACE_ALL = 2, /**< Non-persistent free space managers, aggregators, virtual file driver
+ This is the library default */
+ H5F_FILE_SPACE_AGGR_VFD = 3, /**< Aggregators, Virtual file driver */
+ H5F_FILE_SPACE_VFD = 4, /**< Virtual file driver */
+ H5F_FILE_SPACE_NTYPES /**< Sentinel */
} H5F_file_space_type_t;
-/* Data structure to report the collection of read retries for metadata items with checksum */
-/* Used by public routine H5Fget_metadata_read_retry_info() */
#define H5F_NUM_METADATA_READ_RETRY_TYPES 21
+
+/**
+ * Data structure to report the collection of read retries for metadata items with checksum as
+ * used by H5Fget_metadata_read_retry_info()
+ */
typedef struct H5F_retry_info_t {
unsigned nbins;
uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
} H5F_retry_info_t;
-/* Callback for H5Pset_object_flush_cb() in a file access property list */
+/**
+ * Callback for H5Pset_object_flush_cb() in a file access property list
+ */
typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata);
/*********************/
@@ -230,56 +249,1073 @@ typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *udata);
extern "C" {
#endif
+/**
+ * \ingroup H5F
+ *
+ * \brief Checks if a file can be opened with a given file access property
+ * list
+ *
+ * \param[in] container_name Name of a file
+ * \fapl_id
+ *
+ * \return \htri_t
+ *
+ * \details H5Fis_accessible() checks if the file specified by \p
+ * container_name can be opened with the file access property list
+ * \p fapl_id.
+ *
+ * \note The H5Fis_accessible() function enables files to be checked with a
+ * given file access property list, unlike H5Fis_hdf5(), which only uses
+ * the default file driver when opening a file.
+ *
+ * \since 1.12.0
+ *
+ */
H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
-H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t create_plist, hid_t access_plist);
-H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t access_plist);
+/**
+ * \example H5Fcreate.c
+ * After creating an HDF5 file with H5Fcreate(), we close it with
+ * H5Fclose().
+ */
+/**
+ * \ingroup H5F
+ *
+ * \brief Creates an HDF5 file
+ *
+ * \param[in] filename Name of the file to create
+ * \param[in] flags File access flags. Allowable values are:
+ * - #H5F_ACC_TRUNC: Truncate file, if it already exists,
+ * erasing all data previously stored in the file
+ * - #H5F_ACC_EXCL: Fail if file already exists
+ * \fcpl_id
+ * \fapl_id
+ * \return \hid_t{file}
+ *
+ * \details H5Fcreate() is the primary function for creating HDF5 files; it
+ * creates a new HDF5 file with the specified name and property lists.
+ *
+ * The \p filename parameter specifies the name of the new file.
+ *
+ * The \p flags parameter specifies whether an existing file is to be
+ * overwritten. It should be set to either #H5F_ACC_TRUNC to overwrite
+ * an existing file or #H5F_ACC_EXCL, instructing the function to fail
+ * if the file already exists.
+ *
+ * New files are always created in read-write mode, so the read-write
+ * and read-only flags, #H5F_ACC_RDWR and #H5F_ACC_RDONLY,
+ * respectively, are not relevant in this function. Further note that
+ * a specification of #H5F_ACC_RDONLY will be ignored; the file will
+ * be created in read-write mode, regardless.
+ *
+ * More complex behaviors of file creation and access are controlled
+ * through the file creation and file access property lists,
+ * \p fcpl_id and \p fapl_id, respectively. The value of #H5P_DEFAULT
+ * for any property list value indicates that the library should use
+ * the default values for that appropriate property list.
+ *
+ * The return value is a file identifier for the newly-created file;
+ * this file identifier should be closed by calling H5Fclose() when
+ * it is no longer needed.
+ *
+ * \include H5Fcreate.c
+ *
+ * \note #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use
+ * exactly one.
+ *
+ * \note An additional flag, #H5F_ACC_DEBUG, prints debug information. This
+ * flag can be combined with one of the above values using the bit-wise
+ * OR operator (\c |), but it is used only by HDF5 library developers;
+ * \Emph{it is neither tested nor supported for use in applications}.
+ *
+ * \attention \Bold{Special case — File creation in the case of an already-open file:}
+ * If a file being created is already opened, by either a previous
+ * H5Fopen() or H5Fcreate() call, the HDF5 library may or may not
+ * detect that the open file and the new file are the same physical
+ * file. (See H5Fopen() regarding the limitations in detecting the
+ * re-opening of an already-open file.)\n
+ * If the library detects that the file is already opened,
+ * H5Fcreate() will return a failure, regardless of the use of
+ * #H5F_ACC_TRUNC.\n
+ * If the library does not detect that the file is already opened
+ * and #H5F_ACC_TRUNC is not used, H5Fcreate() will return a failure
+ * because the file already exists. Note that this is correct
+ * behavior.\n
+ * But if the library does not detect that the file is already
+ * opened and #H5F_ACC_TRUNC is used, H5Fcreate() will truncate the
+ * existing file and return a valid file identifier. Such a
+ * truncation of a currently-opened file will almost certainly
+ * result in errors. While unlikely, the HDF5 library may not be
+ * able to detect, and thus report, such errors.\n
+ * Applications should avoid calling H5Fcreate() with an already
+ * opened file.
+ *
+ * \since 1.0.0
+ *
+ * \see H5Fopen(), H5Fclose()
+ *
+ */
+H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Opens an existing HDF5 file
+ *
+ * \param[in] filename Name of the file to be opened
+ * \param[in] flags File access flags. Allowable values are:
+ * - #H5F_ACC_RDWR: Allows read and write access to file
+ * - #H5F_ACC_RDONLY: Allows read-only access to file
+ * - #H5F_ACC_RDWR \c | #H5F_ACC_SWMR_WRITE: Indicates that
+ * the file is open for writing in a
+ * single-writer/multi-writer (SWMR) scenario.
+ * - #H5F_ACC_RDONLY \c | #H5F_ACC_SWMR_READ: Indicates
+ * that the file is open for reading in a
+ * single-writer/multi-reader (SWMR) scenario.
+ * - An additional flag, #H5F_ACC_DEBUG, prints debug
+ * information. This flag can be combined with one of the
+ * above values using the bit-wise OR operator (\c |), but
+ * it is used only by HDF5 library developers;
+ * \Emph{it is neither tested nor supported} for use in
+ * applications.
+ * \fapl_id
+ * \return \hid_t{file}
+ *
+ * \details H5Fopen() is the primary function for accessing existing HDF5 files.
+ * This function opens the named file in the specified access mode and
+ * with the specified access property list.
+ *
+ * Note that H5Fopen() does not create a file if it does not already
+ * exist; see H5Fcreate().
+ *
+ * The \p filename parameter specifies the name of the file to be
+ * opened.
+ *
+ * The \p fapl_id parameter specifies the file access property list.
+ * Use of #H5P_DEFAULT specifies that default I/O access properties
+ * are to be used.
+ *
+ * The \p flags parameter specifies whether the file will be opened in
+ * read-write or read-only mode, #H5F_ACC_RDWR or #H5F_ACC_RDONLY,
+ * respectively. More complex behaviors of file access are controlled
+ * through the file-access property list.
+ *
+ * The return value is a file identifier for the open file; this file
+ * identifier should be closed by calling H5Fclose() when it is no
+ * longer needed.
+ *
+ * \note #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use
+ * exactly one.
+ *
+ * \attention \Bold{Special cases — Multiple opens:} A file can often be opened
+ * with a new H5Fopen() call without closing an already-open
+ * identifier established in a previous H5Fopen() or H5Fcreate()
+ * call. Each such H5Fopen() call will return a unique identifier
+ * and the file can be accessed through any of these identifiers as
+ * long as the identifier remains valid. In such multiply-opened
+ * cases, the open calls must use the same flags argument and the
+ * file access property lists must use the same file close degree
+ * property setting (see the external link discussion below and
+ * H5Pset_fclose_degree()).\n
+ * In some cases, such as files on a local Unix file system, the
+ * HDF5 library can detect that a file is multiply opened and will
+ * maintain coherent access among the file identifiers.\n
+ * But in many other cases, such as parallel file systems or
+ * networked file systems, it is not always possible to detect
+ * multiple opens of the same physical file. In such cases, HDF5
+ * will treat the file identifiers as though they are accessing
+ * different files and will be unable to maintain coherent access.
+ * Errors are likely to result in these cases. While unlikely, the
+ * HDF5 library may not be able to detect, and thus report,
+ * such errors.\n
+ * It is generally recommended that applications avoid multiple
+ * opens of the same file.
+ *
+ * \attention \Bold{Special restriction on multiple opens of a file first
+ * opened by means of an external link:} When an external link is
+ * followed, the external file is always opened with the weak file
+ * close degree property setting, #H5F_CLOSE_WEAK (see
+ * H5Lcreate_external() and H5Pset_fclose_degree()). If the file is
+ * reopened with H5Fopen while it remains held open from such an
+ * external link call, the file access property list used in the
+ * open call must include the file close degree setting
+ * #H5F_CLOSE_WEAK or the open will fail.
+ *
+ * \version 1.10.0 The #H5F_ACC_SWMR_WRITE and #H5F_ACC_SWMR_READ flags were added.
+ *
+ * \see H5Fclose()
+ *
+ */
+H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Returns a new identifier for a previously-opened HDF5 file
+ *
+ * \param[in] file_id Identifier of a file for which an additional identifier
+ * is required
+ *
+ * \return \hid_t{file}
+ *
+ * \details H5Freopen() returns a new file identifier for an already-open HDF5
+ * file, as specified by \p file_id. Both identifiers share caches and
+ * other information. The only difference between the identifiers is
+ * that the new identifier is not mounted anywhere and no files are
+ * mounted on it.
+ *
+ * The new file identifier should be closed by calling H5Fclose() when
+ * it is no longer needed.
+ *
+ * \note Note that there is no circumstance under which H5Freopen() can
+ * actually open a closed file; the file must already be open and have an
+ * active \p file_id. E.g., one cannot close a file with H5Fclose() on
+ * \p file_id then use H5Freopen() on \p file_id to reopen it.
+ *
+ */
H5_DLL hid_t H5Freopen(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Flushes all buffers associated with a file to storage
+ *
+ * \loc_id{object_id}
+ * \param[in] scope The scope of the flush action
+ *
+ * \return \herr_t
+ *
+ * \details H5Fflush() causes all buffers associated with a file to be
+ * immediately flushed to storage without removing the data from the
+ * cache.
+ *
+ * \p object_id can be any object associated with the file, including
+ * the file itself, a dataset, a group, an attribute, or a named
+ * datatype.
+ *
+ * \p scope specifies whether the scope of the flush action is
+ * global or local. Valid values are as follows:
+ * \scopes
+ *
+ * \attention HDF5 does not possess full control over buffering. H5Fflush()
+ * flushes the internal HDF5 buffers 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.
+ *
+ */
H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope);
+/**
+ * \example H5Fclose.c
+ * After creating an HDF5 file with H5Fcreate(), we close it with
+ * H5Fclose().
+ */
+/**
+ * \ingroup H5F
+ *
+ * \brief Terminates access to an HDF5 file
+ *
+ * \file_id
+ * \return \herr_t
+ *
+ * \details H5Fclose() terminates access to an HDF5 file (specified by
+ * \p file_id) by flushing all data to storage.
+ *
+ * If this is the last file identifier open for the file and no other
+ * access identifier is open (e.g., a dataset identifier, group
+ * identifier, or shared datatype identifier), the file will be fully
+ * closed and access will end.
+ *
+ * Use H5Fclose() as shown in the following example:
+ * \include H5Fclose.c
+ *
+ * \note \Bold{Delayed close:} Note the following deviation from the
+ * above-described behavior. If H5Fclose() is called for a file but one
+ * or more objects within the file remain open, those objects will remain
+ * accessible until they are individually closed. Thus, if the dataset
+ * \c data_sample is open when H5Fclose() is called for the file
+ * containing it, \c data_sample will remain open and accessible
+ * (including writable) until it is explicitly closed. The file will be
+ * automatically closed once all objects in the file have been closed.\n
+ * Be warned, however, that there are circumstances where it is not
+ * possible to delay closing a file. For example, an MPI-IO file close is
+ * a collective call; all of the processes that opened the file must
+ * close it collectively. The file cannot be closed at some time in the
+ * future by each process in an independent fashion. Another example is
+ * that an application using an AFS token-based file access privilege may
+ * destroy its AFS token after H5Fclose() has returned successfully. This
+ * would make any future access to the file, or any object within it,
+ * illegal.\n
+ * In such situations, applications must close all open objects in a file
+ * before calling H5Fclose. It is generally recommended to do so in all
+ * cases.
+ *
+ * \see H5Fopen()
+ *
+ */
H5_DLL herr_t H5Fclose(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Deletes an HDF5 file
+ *
+ * \param[in] filename Name of the file to delete
+ * \fapl_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Fdelete() deletes an HDF5 file \p filename with a file access
+ * property list \p fapl_id. The \p fapl_id should be configured with
+ * the same VOL connector or VFD that was used to open the file.
+ *
+ * This API was introduced for use with the Virtual Object Layer
+ * (VOL). With the VOL, HDF5 "files" can map to arbitrary storage
+ * schemes such as object stores and relational database tables. The
+ * data created by these implementations may be inconvenient for a
+ * user to remove without a detailed knowledge of the storage scheme.
+ * H5Fdelete() gives VOL connector authors the ability to add
+ * connector-specific delete code to their connectors so that users
+ * can remove these "files" without detailed knowledge of the storage
+ * scheme.
+ *
+ * For a VOL connector, H5Fdelete() deletes the file in a way that
+ * makes sense for the specified VOL connector.
+ *
+ * For the native HDF5 connector, HDF5 files will be deleted via the
+ * VFDs, each of which will have to be modified to delete the files it
+ * creates.
+ *
+ * For all implementations, H5Fdelete() will first check if the file
+ * is an HDF5 file via H5Fis_accessible(). This is done to ensure that
+ * H5Fdelete() cannot be used as an arbitrary file deletion call.
+ *
+ * \since 1.12.0
+ *
+ */
H5_DLL herr_t H5Fdelete(const char *filename, hid_t fapl_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Returns a file creation property list identifier
+ *
+ * \file_id
+ * \return \hid_t{file creation property list}
+ *
+ * \details H5Fget_create_plist() returns the file creation property list
+ * identifier identifying the creation properties used to create this
+ * file. This function is useful for duplicating properties when
+ * creating another file.
+ *
+ * The creation property list identifier should be released with
+ * H5Pclose().
+ *
+ */
H5_DLL hid_t H5Fget_create_plist(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Returns a file access property list identifier
+ *
+ * \file_id
+ * \return \hid_t{file access property list}
+ *
+ * \details H5Fget_access_plist() returns the file access property list
+ * identifier of the specified file.
+ *
+ */
H5_DLL hid_t H5Fget_access_plist(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Determines the read/write or read-only status of a file
+ *
+ * \file_id
+ * \param[out] intent Access mode flag as originally passed with H5Fopen()
+ *
+ * \return \herr_t
+ *
+ * \details Given the identifier of an open file, \p file_id, H5Fget_intent()
+ * retrieves the intended access mode" flag passed with H5Fopen() when
+ * the file was opened.
+ *
+ * The value of the flag is returned in \p intent. Valid values are as
+ * follows:
+ * \file_access
+ *
+ * \note The function will not return an error if intent is NULL; it will
+ * simply do nothing.
+ *
+ * \version 1.10.0 C function enhanced to work with SWMR functionality.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL herr_t H5Fget_intent(hid_t file_id, unsigned *intent);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves a file's file number that uniquely identifies an open file
+ *
+ * \file_id
+ * \param[out] fileno A buffer to hold the file number
+ *
+ * \return \herr_t
+ *
+ * \details H5Fget_fileno() retrieves a file number for a file specified by the
+ * file identifier \p file_id and the pointer \p fnumber to the file
+ * number.
+ *
+ * \since 1.12.0
+ *
+ */
H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno);
+/**
+ * \ingroup H5F
+ *
+ * \brief Returns the number of open object identifiers for an open file
+ *
+ * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files
+ * \param[in] types Type of object for which identifiers are to be returned
+ *
+ * \return Returns the number of open objects if successful; otherwise returns
+ * a negative value.
+ *
+ * \details Given the identifier of an open file, file_id, and the desired
+ * object types, types, H5Fget_obj_count() returns the number of open
+ * object identifiers for the file.
+ *
+ * To retrieve a count of open identifiers for open objects in all
+ * HDF5 application files that are currently open, pass the value
+ * #H5F_OBJ_ALL in \p file_id.
+ *
+ * The types of objects to be counted are specified in types as
+ * follows:
+ * \obj_types
+ *
+ * Multiple object types can be combined with the
+ * logical \c OR operator (|). For example, the expression
+ * \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and
+ * groups.
+ *
+ * \version 1.6.8, 1.8.2 C function return type changed to \c ssize_t.
+ * \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types
+ * of objects to be counted. #H5F_OBJ_LOCAL restricts the
+ * search to objects opened through current file identifier.
+ *
+ */
H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types);
+/**
+ *-------------------------------------------------------------------------
+ * \ingroup H5F
+ *
+ * \brief Returns a list of open object identifiers
+ *
+ * \file_id or #H5F_OBJ_ALL for all currently-open HDF5 files
+ * \param[in] types Type of object for which identifiers are to be returned
+ * \param[in] max_objs Maximum number of object identifiers to place into
+ * \p obj_id_list
+ * \param[out] obj_id_list Pointer to the returned buffer of open object
+ * identifiers
+ *
+ * \return Returns number of objects placed into \p obj_id_list if successful;
+ * otherwise returns a negative value.
+ *
+ * \details Given the file identifier \p file_id and the type of objects to be
+ * identified, types, H5Fget_obj_ids() returns the list of identifiers
+ * for all open HDF5 objects fitting the specified criteria.
+ *
+ * To retrieve identifiers for open objects in all HDF5 application
+ * files that are currently open, pass the value #H5F_OBJ_ALL in
+ * \p file_id.
+ *
+ * The types of object identifiers to be retrieved are specified in
+ * types using the codes listed for the same parameter in
+ * H5Fget_obj_count().
+ *
+ * To retrieve a count of open objects, use the H5Fget_obj_count()
+ * function. This count can be used to set the \p max_objs parameter.
+ *
+ * \version 1.8.2 C function return type changed to \c ssize_t and \p
+ * max_objs parameter datatype changed to \c size_t.
+ * \version 1.6.8 C function return type changed to \c ssize_t and \p
+ * max_objs parameter datatype changed to \c size_t.
+ * \since 1.6.0
+ *
+ */
H5_DLL ssize_t H5Fget_obj_ids(hid_t file_id, unsigned types, size_t max_objs, hid_t *obj_id_list);
+/**
+ * \ingroup H5F
+ *
+ * \brief Returns pointer to the file handle from the virtual file driver
+ *
+ * \file_id
+ * \fapl_id{fapl}
+ * \param[out] file_handle Pointer to the file handle being used by the
+ * low-level virtual file driver
+ *
+ * \return \herr_t
+ *
+ * \details Given the file identifier \p file_id and the file access property
+ * list \p fapl_id, H5Fget_vfd_handle() returns a pointer to the file
+ * handle from the low-level file driver currently being used by the
+ * HDF5 library for file I/O.
+ *
+ * \note For most drivers, the value of \p fapl_id will be #H5P_DEFAULT. For
+ * the \c FAMILY or \c MULTI drivers, this value should be defined
+ * through the property list functions: H5Pset_family_offset() for the
+ * \c FAMILY driver and H5Pset_multi_type() for the \c MULTI driver
+ *
+ * \since 1.6.0
+ *
+ */
H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle);
+/**
+ * \ingroup H5F
+ *
+ * \brief Mounts an HDF5 file
+ *
+ * \loc_id{loc}
+ * \param[in] name Name of the group onto which the file specified by \p child
+ * is to be mounted
+ * \file_id{child}
+ * \param[in] plist File mount property list identifier. Pass #H5P_DEFAULT!
+ *
+ * \return \herr_t
+ *
+ * \details H5Fmount() mounts the file specified by \p child onto the object
+ * specified by \p loc and \p name using the mount properties \p plist
+ * If the object specified by \p loc is a dataset, named datatype or
+ * attribute, then the file will be mounted at the location where the
+ * attribute, dataset, or named datatype is attached.
+ *
+ * \note To date, no file mount properties have been defined in HDF5. The
+ * proper value to pass for \p plist is #H5P_DEFAULT, indicating the
+ * default file mount property list.
+ *
+ */
H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist);
+/**
+ * \ingroup H5F
+ *
+ * \brief Unounts an HDF5 file
+ *
+ * \loc_id{loc}
+ * \param[in] name Name of the mount point
+ *
+ * \return \herr_t
+ *
+ * \details Given a mount point, H5Funmount() dissociates the mount point's
+ * file from the file mounted there. This function does not close
+ * either file.
+ *
+ * The mount point can be either the group in the parent or the root
+ * group of the mounted file (both groups have the same name). If the
+ * mount point was opened before the mount then it is the group in the
+ * parent; if it was opened after the mount then it is the root group
+ * of the child.
+ *
+ */
H5_DLL herr_t H5Funmount(hid_t loc, const char *name);
+/**
+ * \ingroup H5F
+ *
+ * \brief Returns the amount of free space in a file (in bytes)
+ *
+ * \file_id
+ *
+ * \return Returns the amount of free space in the file if successful;
+ * otherwise returns a negative value.
+ *
+ * \details Given the identifier of an open file, \p file_id,
+ * H5Fget_freespace() returns the amount of space that is unused by
+ * any objects in the file.
+ *
+ * The interpretation of this number depends on the configured free space
+ * management strategy. For example, if the HDF5 library only tracks free
+ * space in a file from a file open or create until that file is closed,
+ * then this routine will report the free space that has been created
+ * during that interval.
+ *
+ * \since 1.6.1
+ *
+ */
H5_DLL hssize_t H5Fget_freespace(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Returns the size of an HDF5 file (in bytes)
+ *
+ * \file_id
+ * \param[out] size Size of the file, in bytes
+ *
+ * \return \herr_t
+ *
+ * \details H5Fget_filesize() returns the size of the HDF5 file specified by
+ * \p file_id.
+ *
+ * The returned size is that of the entire file, as opposed to only
+ * the HDF5 portion of the file. I.e., size includes the user block,
+ * if any, the HDF5 portion of the file, and any data that may have
+ * been appended beyond the data written through the HDF5 library.
+ *
+ * \version 1.6.3 Fortran subroutine introduced in this release.
+ *
+ * \since 1.6.3
+ *
+ */
H5_DLL herr_t H5Fget_filesize(hid_t file_id, hsize_t *size);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves the file's end-of-allocation (EOA)
+ *
+ * \file_id
+ * \param[out] eoa The file's EOA
+ *
+ * \return \herr_t
+ *
+ * \details H5Fget_eoa() retrieves the file's EOA and returns it in the
+ * parameter eoa.
+ *
+ * \since 1.10.2
+ *
+ */
H5_DLL herr_t H5Fget_eoa(hid_t file_id, haddr_t *eoa);
+/**
+ * \ingroup H5F
+ *
+ * \brief Sets the file' EOA to the maximum of (EOA, EOF) + increment
+ *
+ * \file_id
+ * \param[in] increment The number of bytes to be added to the maximum of
+ * (EOA, EOF)
+ *
+ * \return \herr_t
+ *
+ * \details H5Fincrement_filesize() sets the file's EOA to the maximum of (EOA,
+ * EOF) + \p increment. The EOA is the end-of-file address stored in
+ * the file's superblock while EOF is the file's actual end-of-file.
+ *
+ * \since 1.10.2
+ *
+ */
H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves a copy of the image of an existing, open file
+ *
+ * \file_id
+ * \param[out] buf_ptr Pointer to the buffer into which the image of the
+ * HDF5 file is to be copied. If \p buf_ptr is NULL,
+ * no data will be copied but the function’s return value
+ * will still indicate the buffer size required (or a
+ * negative value on error).
+ * \param[out] buf_len Size of the supplied buffer
+ *
+ * \return ssize_t
+ *
+ * \details H5Fget_file_image() retrieves a copy of the image of an existing,
+ * open file. This routine can be used with files opened using the
+ * SEC2 (or POSIX), STDIO, and Core (or Memory) virtual file drivers
+ * (VFDs).
+ *
+ * If the return value of H5Fget_file_image() is a positive value, it
+ * will be the length in bytes of the buffer required to store the
+ * file image. So if the file size is unknown, it can be safely
+ * determined with an initial H5Fget_file_image() call with buf_ptr
+ * set to NULL. The file image can then be retrieved with a second
+ * H5Fget_file_image() call with \p buf_len set to the initial call’s
+ * return value.
+ *
+ * While the current file size can also be retrieved with
+ * H5Fget_filesize(), that call may produce a larger value than is
+ * needed. The value returned by H5Fget_filesize() includes the user
+ * block, if it exists, and any unallocated space at the end of the
+ * file. It is safe in all situations to get the file size with
+ * H5Fget_file_image() and it often produces a value that is more
+ * appropriate for the size of a file image buffer.
+ *
+ * \note \Bold{Recommended Reading:} This function is part of the file image
+ * operations feature set. It is highly recommended to study the guide
+ * "HDF5 File Image Operations" before using this feature set.\n See the
+ * "See Also" section below for links to other elements of HDF5 file
+ * image operations. \todo Fix the references.
+ *
+ * \attention H5Pget_file_image() will fail, returning a negative value, if the
+ * file is too large for the supplied buffer.
+ *
+ * \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(),
+ * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks()
+ *
+ * \version 1.8.13 Fortran subroutine added in this release.
+ *
+ * \since 1.8.0
+ *
+ */
H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fget_mdc_hit_rate(hid_t file_id, double *hit_rate_ptr);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_clean_size_ptr,
size_t *cur_size_ptr, int *cur_num_entries_ptr);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves name of file to which object belongs
+ *
+ * \obj_id
+ * \param[out] name Buffer for the file name
+ * \param[in] size Size, in bytes, of the \p name buffer
+ *
+ * \return Returns the length of the file name if successful; otherwise returns
+ * a negative value.
+ *
+ * \details H5Fget_name() retrieves the name of the file to which the object \p
+ * obj_id belongs. The object can be a file, group, dataset,
+ * attribute, or named datatype.
+ *
+ * Up to \p size characters of the file name are returned in \p name;
+ * additional characters, if any, are not returned to the user
+ * application.
+ *
+ * If the length of the name, which determines the required value of
+ * size, is unknown, a preliminary H5Fget_name() call can be made by
+ * setting \p name to NULL. The return value of this call will be the
+ * size of the file name; that value plus one (1) can then be assigned
+ * to size for a second H5Fget_name() call, which will retrieve the
+ * actual name. (The value passed in with the parameter \p size must
+ * be one greater than size in bytes of the actual name in order to
+ * accommodate the null terminator; if \p size is set to the exact
+ * size of the name, the last byte passed back will contain the null
+ * terminator and the last character will be missing from the name
+ * passed back to the calling application.)
+ *
+ * If an error occurs, the buffer pointed to by \p name is unchanged
+ * and the function returns a negative value.
+ *
+ * \since 1.6.3
+ *
+ */
H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size);
-H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *finfo);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves name of file to which object belongs
+ *
+ * \fgdta_obj_id
+ * \param[out] file_info Buffer for global file information
+ *
+ * \return \herr_t
+ *
+ * \details H5Fget_info2() returns global information for the file associated
+ * with the object identifier \p obj_id in the H5F_info2_t \c struct
+ * named \p file_info.
+ *
+ * \p obj_id is an identifier for any object in the file of interest.
+ *
+ * H5F_info2_t struct is defined in H5Fpublic.h as follows:
+ * \snippet this H5F_info2_t_snip
+ *
+ * The \c super sub-struct contains the following information:
+ * \li \c vers is the version number of the superblock.
+ * \li \c super_size is the size of the superblock.
+ * \li \c super_ext_size is the size of the superblock extension.
+ *
+ * The \c free sub-struct contains the following information:
+ * \li vers is the version number of the free-space manager.
+ * \li \c hdr_size is the size of the free-space manager header.
+ * \li \c tot_space is the total amount of free space in the file.
+ *
+ * The \c sohm sub-struct contains shared object header message
+ * information as follows:
+ * \li \c vers is the version number of the shared object header information.
+ * \li \c hdr_size is the size of the shared object header message.
+ * \li \c msgs_info is an H5_ih_info_t struct defined in H5public.h as
+ * follows: \snippet H5public.h H5_ih_info_t_snip
+ * \li \p index_size is the summed size of all the shared object
+ * header indexes. Each index might be either a B-tree or
+ * a list.
+ * \li \p heap_size is the size of the heap.
+ *
+ *
+ * \since 1.10.0
+ *
+ */
+H5_DLL herr_t H5Fget_info2(hid_t obj_id, H5F_info2_t *file_info);
+/**
+ * \ingroup SWMR
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *info);
+/**
+ * \ingroup SWMR
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fstart_swmr_write(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves free-space section information for a file
+ *
+ * \file_id
+ * \param[in] type The file memory allocation type
+ * \param[in] nsects The number of free-space sections
+ * \param[out] sect_info Array of instances of H5F_sect_info_t in which
+ * the free-space section information is to be returned
+ *
+ * \return Returns the number of free-space sections for the specified
+ * free-space manager in the file; otherwise returns a negative value.
+ *
+ * \details H5Fget_free_sections() retrieves free-space section information for
+ * the free-space manager with type that is associated with file
+ * \p file_id. If type is #H5FD_MEM_DEFAULT, this routine retrieves
+ * free-space section information for all the free-space managers in
+ * the file.
+ *
+ * Valid values for \p type are the following:
+ * \mem_types
+ *
+ * H5F_sect_info_t is defined as follows (in H5Fpublic.h):
+ * \snippet this H5F_sect_info_t_snip
+ *
+ * This routine retrieves free-space section information for \p nsects
+ * sections or at most the maximum number of sections in the specified
+ * free-space manager. If the number of sections is not known, a
+ * preliminary H5Fget_free_sections() call can be made by setting \p
+ * sect_info to NULL and the total number of free-space sections for
+ * the specified free-space manager will be returned. Users can then
+ * allocate space for entries in \p sect_info, each of which is
+ * defined as an H5F_sect_info_t \c struct.
+ *
+ * \attention \Bold{Failure Modes:} This routine will fail when the following
+ * is true:
+ * \li The library fails to retrieve the file creation property list
+ * associated with \p file_id.
+ * \li If the parameter \p sect_info is non-null, but the parameter
+ * \p nsects is equal to 0.
+ * \li The library fails to retrieve free-space section information
+ * for the file.
+ *
+ * \since 1.10.0
+ *
+ */
H5_DLL ssize_t H5Fget_free_sections(hid_t file_id, H5F_mem_t type, size_t nsects,
H5F_sect_info_t *sect_info /*out*/);
+/**
+ * \ingroup H5F
+ *
+ * \brief Clears the external link open file cache
+ *
+ * \file_id
+ * \return \herr_t
+ *
+ * \details H5Fclear_elink_file_cache() evicts all the cached child files in
+ * the specified file’s external file cache, causing them to be closed
+ * if there is nothing else holding them open.
+ *
+ * H5Fclear_elink_file_cache() does not close the cache itself;
+ * subsequent external link traversals from the parent file will again
+ * cache the target file. See H5Pset_elink_file_cache_size() for
+ * information on closing the file cache.
+ *
+ * \see H5Pset_elink_file_cache_size(), H5Pget_elink_file_cache_size()
+ *
+ * \since 1.8.7
+ *
+ */
H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Enables the switch of version bounds setting for a file
+ *
+ * \file_id
+ * \param[in] low The earliest version of the library that will be used for
+ * writing objects
+ * \param[in] high The latest version of the library that will be used for
+ * writing objects
+ *
+ * \return \herr_t
+ *
+ * \details H5Fset_libver_bounds() enables the switch of version bounds setting
+ * for an open file associated with \p file_id.
+ *
+ * For the parameters \p low and \p high, see the description for
+ * H5Pset_libver_bounds().
+ *
+ * \since 1.10.2
+ *
+ */
H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t high);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id,
/*OUT*/ hbool_t *is_enabled,
/*OUT*/ hbool_t *is_currently_logging);
+/**
+ * \ingroup SWMR
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fformat_convert(hid_t fid);
+/**
+ * \ingroup H5F
+ *
+ * \brief Resets the page buffer statistics
+ *
+ * \file_id
+ *
+ * \return \herr_t
+ *
+ * \details H5Freset_page_buffering_stats() resets the page buffer statistics
+ * for a specified file identifier \p file_id.
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5Freset_page_buffering_stats(hid_t file_id);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves statistics about page access when it is enabled
+ *
+ * \file_id
+ * \param[out] accesses Two integer array for the number of metadata and raw
+ * data accesses to the page buffer
+ * \param[out] hits Two integer array for the number of metadata and raw data
+ * hits in the page buffer
+ * \param[out] misses Two integer array for the number of metadata and raw data
+ * misses in the page buffer
+ * \param[out] evictions Two integer array for the number of metadata and raw
+ * data evictions from the page buffer
+ * \param[out] bypasses Two integer array for the number of metadata and raw
+ * data accesses that bypass the page buffer
+ *
+ * \return \herr_t
+ *
+ * \details H5Fget_page_buffering_stats() retrieves page buffering statistics
+ * such as the number of metadata and raw data accesses (\p accesses),
+ * hits (\p hits), misses (\p misses), evictions (\p evictions), and
+ * accesses that bypass the page buffer (\p bypasses).
+ *
+ * \since 1.10.1
+ *
+ */
H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], unsigned hits[2],
unsigned misses[2], unsigned evictions[2], unsigned bypasses[2]);
+/**
+ * \ingroup MDC
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t *image_size);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves the setting for whether or not a file will create minimized
+ * dataset object headers
+ *
+ * \file_id
+ * \param[out] minimize Flag indicating whether the library will or will not
+ * create minimized dataset object headers
+ *
+ * \return \herr_t
+ *
+ * \details H5Fget_dset_no_attrs_hint() retrieves the no dataset attributes
+ * hint setting for the file specified by the file identifier \p
+ * file_id. This setting is used to inform the library to create
+ * minimized dataset object headers when \c TRUE.
+ *
+ * The setting's value is returned in the boolean pointer minimize.
+ *
+ * \since 1.10.5
+ *
+ */
H5_DLL herr_t H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize);
+/**
+ * \ingroup H5F
+ *
+ * \brief Sets the flag to create minimized dataset object headers
+ *
+ * \file_id
+ * \param[in] minimize Flag indicating whether the library will or will not
+ * create minimized dataset object headers
+ *
+ * \return \herr_t
+ *
+ * \details H5Fset_dset_no_attrs_hint() sets the no dataset attributes hint
+ * setting for the file specified by the file identifier \p file_id.
+ * If the boolean flag \p minimize is set to \c TRUE, then the library
+ * will create minimized dataset object headers in the file.
+ * \Bold{All} files that refer to the same file-on-disk will be
+ * affected by the most recent setting, regardless of the file
+ * identifier/handle (e.g., as returned by H5Fopen()). By setting the
+ * \p minimize flag to \c TRUE, the library expects that no attributes
+ * will be added to the dataset - attributes can be added, but they
+ * are appended with a continuation message, which can reduce
+ * performance.
+ *
+ * \attention This setting interacts with H5Pset_dset_no_attrs_hint(): if
+ * either is set to \c TRUE, then the created dataset's object header
+ * will be minimized.
+ *
+ * \since 1.10.5
+ *
+ */
H5_DLL herr_t H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize);
#ifdef H5_HAVE_PARALLEL
+/**
+ * \ingroup PH5F
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
+/**
+ * \ingroup PH5F
+ *
+ * \todo Finish this!
+ */
H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#endif /* H5_HAVE_PARALLEL */
@@ -294,19 +1330,95 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
/* Typedefs */
-/* Current "global" information about file */
+/**
+ * Current "global" information about file
+ */
+//! [H5F_info1_t_snip]
typedef struct H5F_info1_t {
- hsize_t super_ext_size; /* Superblock extension size */
+ hsize_t super_ext_size; /**< Superblock extension size */
struct {
- hsize_t hdr_size; /* Shared object header message header size */
- H5_ih_info_t msgs_info; /* Shared object header message index & heap size */
+ hsize_t hdr_size; /**< Shared object header message header size */
+ H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
} sohm;
} H5F_info1_t;
+//! [H5F_info1_t_snip]
/* Function prototypes */
-H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *finfo);
+/**
+ * \ingroup H5F
+ *
+ * \brief Retrieves name of file to which object belongs
+ *
+ * \fgdta_obj_id
+ * \param[out] file_info Buffer for global file information
+ *
+ * \return \herr_t
+ *
+ * \deprecated This function has been renamed from H5Fget_info() and is
+ * deprecated in favor of the macro #H5Fget_info or the function
+ * H5Fget_info2().
+ *
+ * \details H5Fget_info1() returns global information for the file associated
+ * with the object identifier \p obj_id in the H5F_info1_t \c struct
+ * named \p file_info.
+ *
+ * \p obj_id is an identifier for any object in the file of interest.
+ *
+ * H5F_info1_t struct is defined in H5Fpublic.h as follows:
+ * \snippet this H5F_info1_t_snip
+ *
+ * \c super_ext_size is the size of the superblock extension.
+ *
+ * The \c sohm sub-struct contains shared object header message
+ * information as follows:
+ * \li \c hdr_size is the size of the shared object header message.
+ * \li \c msgs_info is an H5_ih_info_t struct defined in H5public.h as
+ * follows: \snippet H5public.h H5_ih_info_t_snip
+ *
+ * \li \p index_size is the summed size of all the shared object
+ * header indexes. Each index might be either a B-tree or
+ * a list.
+ *
+ * \version 1.10.0 C function H5Fget_info() renamed to H5Fget_info1() and
+ * deprecated in this release.
+ *
+ * \since 1.8.0
+ *
+ */
+H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *file_info);
+/**
+ * \ingroup H5F
+ *
+ * \brief Sets thelatest version of the library to be used for writing objects
+ *
+ * \file_id
+ * \param[in] latest_format Latest format flag
+ *
+ * \return \herr_t
+ *
+ * \deprecated When?
+ *
+ * \todo In which version was this function deprecated?
+ *
+ */
H5_DLL herr_t H5Fset_latest_format(hid_t file_id, hbool_t latest_format);
-H5_DLL htri_t H5Fis_hdf5(const char *filename);
+/**
+ * \ingroup H5F
+ *
+ * \brief Determines whether a file is in the HDF5 format
+ *
+ * \param[in] file_name File name
+ *
+ * \return \htri_t
+ *
+ * \deprecated When?
+ *
+ * \details H5Fis_hdf5() determines whether a file is in the HDF5 format.
+ *
+ * \todo In which version was this function deprecated?
+ *
+ */
+H5_DLL htri_t H5Fis_hdf5(const char *file_name);
#endif /* H5_NO_DEPRECATED_SYMBOLS */
diff --git a/src/H5public.h b/src/H5public.h
index 5b9a5fe..1784a11 100644
--- a/src/H5public.h
+++ b/src/H5public.h
@@ -333,13 +333,15 @@ typedef enum H5_index_t {
H5_INDEX_N /* Number of indices defined */
} H5_index_t;
-/*
+/**
* Storage info struct used by H5O_info_t and H5F_info_t
*/
+//! [H5_ih_info_t_snip]
typedef struct H5_ih_info_t {
- hsize_t index_size; /* btree and/or list */
+ hsize_t index_size; /**< btree and/or list */
hsize_t heap_size;
} H5_ih_info_t;
+//! [H5_ih_info_t_snip]
/* Tokens are unique and permanent identifiers that are
* used to reference HDF5 objects in a container. */