diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/H5Apublic.h | 13 | ||||
| -rw-r--r-- | src/H5Dpublic.h | 81 | ||||
| -rw-r--r-- | src/H5Epublic.h | 30 | ||||
| -rw-r--r-- | src/H5Fpublic.h | 30 | ||||
| -rw-r--r-- | src/H5Gpublic.h | 93 | ||||
| -rw-r--r-- | src/H5Ipublic.h | 42 | ||||
| -rw-r--r-- | src/H5Lpublic.h | 15 | ||||
| -rw-r--r-- | src/H5Opublic.h | 24 | ||||
| -rw-r--r-- | src/H5PLpublic.h | 11 | ||||
| -rw-r--r-- | src/H5Ppublic.h | 111 | ||||
| -rw-r--r-- | src/H5Rpublic.h | 13 | ||||
| -rw-r--r-- | src/H5Spublic.h | 14 | ||||
| -rw-r--r-- | src/H5Tpublic.h | 80 | ||||
| -rw-r--r-- | src/H5Zpublic.h | 67 | ||||
| -rw-r--r-- | src/H5public.h | 7 |
15 files changed, 604 insertions, 27 deletions
diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 0198668..2bd2686 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -11,6 +11,19 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5A H5A + * + * Use the functions in this module to manage HDF5 attributes. + * + * Like HDF5 datasets, HDF5 attributes are array variables which have an element + * datatype and a shape (dataspace). However, they perform a different function: + * Attributes decorate other HDF5 objects, and are typically used to + * represent application metadata. Unlike datasets, the HDF5 library does not + * support partial I/O operations for attributes and they cannot be compressed + * or extended. + * + */ + /* * This file contains public declarations for the H5A module. */ diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index 1cfff22..5170f67 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -11,6 +11,16 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5D H5D + * + * Use the functions in this module to manage HDF5 datasets, including the + * transfer of data between memory and disk and the description of dataset + * properties. Datasets are used by other HDF5 APIs and referenced either by + * name or by a handle. Such handles can be obtained by either creating or + * opening the dataset. + * + */ + /* * This file contains public declarations for the H5D module. */ @@ -130,16 +140,81 @@ typedef enum H5D_fill_value_t { extern "C" { #endif -/* Define the operator function pointer for H5Diterate() */ +//! <!-- [H5D_operator_t_snip] --> +/** + * \brief Callback for H5Diterate() + * + * \param[in,out] elem Pointer to the memory buffer containing the current dataset + * element + * \param[in] type_id Datatype identifier of the elements stored in \p elem + * \param[in] ndim Number of dimensions for the \p point array + * \param[in] point Array containing the location of the element within + * the original dataspace + * \param[in,out] operator_data Pointer to any user-defined data associated with + * the operation + * \return \herr_t_iter + * + */ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point, void *operator_data); +//! <!-- [H5D_operator_t_snip] --> -/* Define the operator function pointer for H5Dscatter() */ +//! <!-- [H5D_scatter_func_t_snip] --> +/** + * \brief Callback for H5Dscatter() + * + * \param[out] src_buf Pointer to the buffer holding the next set of elements to + * scatter. On entry, the value of where \p src_buf points to + * is undefined. The callback function should set \p src_buf + * to point to the next set of elements. + * \param[out] src_buf_bytes_used Pointer to the number of valid bytes in \p src_buf. + * On entry, the value where \p src_buf_bytes_used points + * to is undefined. The callback function should set + * \p src_buf_bytes_used to the of valid bytes in \p src_buf. + * This number must be a multiple of the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function. A pass-through of the \p op_data pointer provided + * with the H5Dscatter() function call. + * \return herr_t + * + * \details The callback function should always return at least one + * element in \p src_buf, and must not return more elements + * than are remaining to be scattered. This function will be + * repeatedly called until all elements to be scattered have + * been returned. The callback function should return zero (0) + * to indicate success, and a negative value to indicate failure. + * + */ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/, void *op_data); +//! <!-- [H5D_scatter_func_t_snip] --> -/* Define the operator function pointer for H5Dgather() */ +//! <!-- [H5D_gather_func_t_snip] --> +/** + * \brief Callback for H5Dgather() + * + * \param[in] dst_buf Pointer to the destination buffer which has been filled + * with the next set of elements gathered. This will always + * be identical to the \p dst_buf passed to H5Dgather() + * \param[in] dst_buf_bytes_used Pointer to the number of valid bytes in + * \p dst_buf. This number must be a multiple of + * the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function; a pass-through of the \p op_data pointer + * provided with the H5Dgather() function call. + * \returns \herr_t + * + * \details The callback function should process, store, or otherwise make use + * of the data returned in dst_buf before it returns, because the + * buffer will be overwritten unless it is the last call to the + * callback. This function will be repeatedly called until all gathered + * elements have been passed to the callback in dst_buf. The callback + * function should return zero (0) to indicate success, and a negative + * value to indicate failure. + * + */ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data); +//! <!-- [H5D_gather_func_t_snip] --> /** * -------------------------------------------------------------------------- diff --git a/src/H5Epublic.h b/src/H5Epublic.h index 3fd6cce..f95261a 100644 --- a/src/H5Epublic.h +++ b/src/H5Epublic.h @@ -11,6 +11,36 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5E H5E + * + * Use the functions in this module to manage HDF5 error stacks and error + * messages. + * + * \internal The \c FUNC_ENTER macro clears the error stack whenever an + * interface function is entered. When an error is detected, an entry + * is pushed onto the stack. As the functions unwind, additional + * entries are pushed onto the stack. The API function will return + * some indication that an error occurred and the application can + * print the error stack. + * + * \internal Certain API functions in the \ref H5E package, such as H5Eprint(), + * do not clear the error stack. Otherwise, any function which does + * not have an underscore immediately after the package name will + * clear the error stack. For instance, H5Fopen() clears the error + * stack while \Code{H5F_open} does not. + * + * \internal An error stack has a fixed maximum size. If this size is exceeded + * then the stack will be truncated and only the inner-most functions + * will have entries on the stack. This is expected to be a rare + * condition. + * + * \internal Each thread has its own error stack, but since multi-threading has + * not been added to the library yet, this package maintains a single + * error stack. The error stack is statically allocated to reduce the + * complexity of handling errors within the \ref H5E package. + * + */ + /* * This file contains public declarations for the H5E module. */ diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index 806320b..c44e729 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -11,6 +11,28 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5F H5F + * + * Use the functions in this module to manage HDF5 files. + * + * In the code snippets below, we show the skeletal life cycle of an HDF5 file, + * when creating a new file (left) or when opening an existing file (right). + * File creation is essentially controlled through \ref FCPL, and file access to + * new and existing files is controlled through \ref FAPL. The file \c name and + * creation or access \c mode control the interaction with the underlying + * storage such as file systems. + * + * In addition to general file management functions, there are three categories + * of functions that deal with advanced file management tasks and use cases: + * 1. The control of the HDF5 \ref MDC + * 2. The use of (MPI-) \ref PH5F HDF5 + * + * \defgroup MDC Metadata Cache + * \ingroup H5F + * \defgroup PH5F Parallel + * \ingroup H5F + */ + /* * This file contains public declarations for the H5F module. */ @@ -266,12 +288,6 @@ H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_ * \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 @@ -344,8 +360,6 @@ H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_ * 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() * */ diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index 7f1faf8..b8b0421 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -11,6 +11,99 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/** \defgroup H5G H5G + * + * Use the functions in this module to manage HDF5 groups. + * + * \details \Bold{Groups in HDF5:} A group associates names with objects and + * provides a mechanism for mapping a name to an object. Since all + * objects appear in at least one group (with the possible exception of + * the root object) and since objects can have names in more than one + * group, the set of all objects in an HDF5 file is a directed + * graph. The internal nodes (nodes with out-degree greater than zero) + * must be groups while the leaf nodes (nodes with out-degree zero) are + * either empty groups or objects of some other type. Exactly one + * object in every non-empty file is the root object. The root object + * always has a positive in-degree because it is pointed to by the file + * super block. + * + * \Bold{Locating objects in the HDF5 file hierarchy:} An object name + * consists of one or more components separated from one another by + * slashes. An absolute name begins with a slash and the object is + * located by looking for the first component in the root object, then + * looking for the second component in the first object, etc., until + * the entire name is traversed. A relative name does not begin with a + * slash and the traversal begins at the location specified by the + * create or access function. + * + * \Bold{Group implementations in HDF5:} The original HDF5 group + * implementation provided a single indexed structure for link + * storage. A new group implementation, in HDF5 Release 1.8.0, enables + * more efficient compact storage for very small groups, improved link + * indexing for large groups, and other advanced features. + * + * \li The \Emph{original indexed} format remains the default. Links + * are stored in a B-tree in the group’s local heap. + * \li Groups created in the new \Emph{compact-or-indexed} format, the + * implementation introduced with Release 1.8.0, can be tuned for + * performance, switching between the compact and indexed formats + * at thresholds set in the user application. + * - The \Emph{compact} format will conserve file space and processing + * overhead when working with small groups and is particularly + * valuable when a group contains no links. Links are stored + * as a list of messages in the group’s header. + * - The \Emph{indexed} format will yield improved + * performance when working with large groups, e.g., groups + * containing thousands to millions of members. Links are stored in + * a fractal heap and indexed with an improved B-tree. + * \li The new implementation also enables the use of link names consisting of + * non-ASCII character sets (see H5Pset_char_encoding()) and is + * required for all link types other than hard or soft links, e.g., + * external and user-defined links (see the \ref H5L APIs). + * + * The original group structure and the newer structures are not + * directly interoperable. By default, a group will be created in the + * original indexed format. An existing group can be changed to a + * compact-or-indexed format if the need arises; there is no capability + * to change back. As stated above, once in the compact-or-indexed + * format, a group can switch between compact and indexed as needed. + * + * Groups will be initially created in the compact-or-indexed format + * only when one or more of the following conditions is met: + * \li The low version bound value of the library version bounds property + * has been set to Release 1.8.0 or later in the file access property + * list (see H5Pset_libver_bounds()). Currently, that would require an + * H5Pset_libver_bounds() call with the low parameter set to + * #H5F_LIBVER_LATEST.\n When this property is set for an HDF5 file, + * all objects in the file will be created using the latest available + * format; no effort will be made to create a file that can be read by + * older libraries. + * \li The creation order tracking property, #H5P_CRT_ORDER_TRACKED, has been + * set in the group creation property list (see H5Pset_link_creation_order()). + * + * An existing group, currently in the original indexed format, will be + * converted to the compact-or-indexed format upon the occurrence of + * any of the following events: + * \li An external or user-defined link is inserted into the group. + * \li A link named with a string composed of non-ASCII characters is + * inserted into the group. + * + * The compact-or-indexed format offers performance improvements that + * will be most notable at the extremes, i.e., in groups with zero + * members and in groups with tens of thousands of members. But + * measurable differences may sometimes appear at a threshold as low as + * eight group members. Since these performance thresholds and criteria + * differ from application to application, tunable settings are + * provided to govern the switch between the compact and indexed + * formats (see H5Pset_link_phase_change()). Optimal thresholds will + * depend on the application and the operating environment. + * + * Future versions of HDF5 will retain the ability to create, read, + * write, and manipulate all groups stored in either the original + * indexed format or the compact-or-indexed format. + * + */ + /*------------------------------------------------------------------------- * * Created: H5Gpublic.h diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index 7e1ce75..2e66b36 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -11,6 +11,48 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5I H5I + * + * Use the functions in this module to manage identifiers defined by the HDF5 + * library. See \ref H5IUD for user-defined identifiers and identifier + * types. + * + * HDF5 identifiers are usually created as a side-effect of creating HDF5 + * entities such as groups, datasets, attributes, or property lists. + * + * Identifiers defined by the HDF5 library can be used to retrieve information + * such as path names and reference counts, and their validity can be checked. + * + * Identifiers can be updated by manipulating their reference counts. + * + * Unused identifiers should be reclaimed by closing the associated item, e.g., + * HDF5 object, or decrementing the reference count to 0. + * + * \note Identifiers (of type \ref hid_t) are run-time auxiliaries and + * not persisted in the file. + * + * \defgroup H5IUD User-defined ID Types + * \ingroup H5I + * + * The \ref H5I module contains functions to define new identifier types. + * For convenience, handles of type \ref hid_t can then be associated with the + * new identifier types and user objects. + * + * New identifier types can be created by registering a new identifier type + * with the HDF5 library. Once a new identifier type has bee registered, + * it can be used to generate identifiers for user objects. + * + * User-defined identifier types can be searched and iterated. + * + * Like library-defined identifiers, user-defined identifiers \Emph{and} + * identifier types are reference counted, and the reference counts can be + * manipulated accordingly. + * + * User-defined identifiers no longer in use should be deleted or reclaimed, + * and identifier types should be destroyed if they are no longer required. + * + */ + /* * This file contains function prototypes for each exported function in * the H5I module. diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index d78efda..2896ba4 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -11,6 +11,16 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5L H5L + * + * Use the functions in this module to manage HDF5 links and link types. + * + * \defgroup TRAV Link Traversal + * \ingroup H5L + * \defgroup H5LA Advanced Link Functions + * \ingroup H5L + */ + /*------------------------------------------------------------------------- * * Created: H5Lpublic.h @@ -1238,7 +1248,7 @@ H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t * Remaining \c struct members are optional and may be passed as NULL. * * The link class passed in \c class_id must be in the user-definable - * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX + * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_MAX * (see the table below) and will override * any existing link class with that identifier. * @@ -1284,7 +1294,7 @@ H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t * <tr> * <td>255</td> * <td>Maximum user-defined value</td> - * <td>#H5L_TYPE_UD_MAX</td> + * <td>#H5L_TYPE_MAX</td> * </tr> * <tr> * <td>255</td> @@ -1339,7 +1349,6 @@ H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t * \li #H5L_TYPE_MAX is the maximum allowed value for a link type * identifier. * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL. - * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX. * \li #H5L_TYPE_ERROR indicates that an error has occurred. * * \note \Bold{Registration with The HDF Group:}\n diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 0931f9b..24bf397 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -11,6 +11,30 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5O H5O + * + * Use the functions in this module to manage HDF5 objects. + * + * HDF5 objects (groups, datasets, datatype objects) are usually created + * using functions in the object-specific modules (\ref H5G, \ref H5D, + * \ref H5T). However, new objects can also be created by copying existing + * objects. + * + * Many functions in this module are variations on object introspection, + * that is, the retrieval of detailed information about HDF5 objects in a file. + * Objects in an HDF5 file can be "visited" in an iterative fashion. + * + * HDF5 objects are usually updated using functions in the object-specific + * modules. However, there are certain generic object properties, such as + * reference counts, that can be manipulated using functions in this module. + * + * HDF5 objects are deleted as a side effect of rendering them unreachable + * from the root group. The net effect is the diminution of the object's + * reference count to zero, which can (but should not usually) be effected + * by a function in this module. + * + */ + /*------------------------------------------------------------------------- * * Created: H5Opublic.h diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h index 6bf46bf..7bcd817 100644 --- a/src/H5PLpublic.h +++ b/src/H5PLpublic.h @@ -10,6 +10,17 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5PL H5PL + * + * Use the functions in this module to manage the loading behavior of HDF5 + * plugins. + * + * \attention The loading behavior of HDF5 plugins can be controlled via the + * functions described below and certain environment variables, such + * as \c HDF5_PLUGIN_PRELOAD and \c HDF5_PLUGIN_PATH. + * + */ + /* * This file contains public declarations for the H5PL module. */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 2cac8b8..962552f 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -11,6 +11,103 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5P H5P + * + * Use the functions in this module to manage HDF5 property lists and property + * list classes. HDF5 property lists are the main vehicle to configure the + * behavior of HDF5 API functions. + * + * Typically, property lists are created by instantiating one of the built-in + * or user-defined property list classes. After adding suitable properties, + * property lists are used when opening or creating HDF5 items, or when reading + * or writing data. Property lists can be modified by adding or changing + * properties. Property lists are deleted by closing the associated handles. + * + * \defgroup ALCAPL Attribute and Link Creation Properties + * \ingroup H5P + * Currently, there are only two creation properties that you can use to control + * the creation of HDF5 attributes and links. The first creation property, the + * choice of a character encoding, applies to both attributes and links. + * The second creation property applies to links only, and advises the library + * to automatically create missing intermediate groups when creating new objects. + * + * \defgroup DAPL Dataset Access Properties + * \ingroup H5P + * Use dataset access properties to modify the default behavior of the HDF5 + * library when accessing datasets. The properties include adjusting the size + * of the chunk cache, providing prefixes for external content and virtual + * dataset file paths, and controlling flush behavior, etc. These properties + * are \Emph{not} persisted with datasets, and can be adjusted at runtime before + * a dataset is created or opened. + * + * \defgroup DCPL Dataset Creation Properties + * \ingroup H5P + * Use dataset creation properties to control aspects of dataset creation such + * as fill time, storage layout, compression methods, etc. + * Unlike dataset access and transfer properties, creation properties \Emph{are} + * stored with the dataset, and cannot be changed once a dataset has been + * created. + * + * \defgroup DXPL Dataset Transfer Properties + * \ingroup H5P + * Use dataset transfer properties to customize certain aspects of reading + * and writing datasets such as transformations, MPI-IO I/O mode, error + * detection, etc. These properties are \Emph{not} persisted with datasets, + * and can be adjusted at runtime before a dataset is read or written. + * + * \defgroup FAPL File Access Properties + * \ingroup H5P + * Use file access properties to modify the default behavior of the HDF5 + * library when accessing files. The properties include selecting a virtual + * file driver (VFD), configuring the metadata cache (MDC), control + * file locking, etc. These properties are \Emph{not} persisted with files, and + * can be adjusted at runtime before a file is created or opened. + * + * \defgroup FCPL File Creation Properties + * \ingroup H5P + * Use file creation properties to control aspects of file creation such + * as setting a file space management strategy or creating a user block. + * Unlike file access properties, creation properties \Emph{are} + * stored with the file, and cannot be changed once a file has been + * created. + * + * \defgroup GAPL General Access Properties + * \ingroup H5P + * \todo Should this be as standalone page? + * + * \defgroup GCPL Group Creation Properties + * \ingroup H5P + * Use group creation properties to control aspects of group creation such + * as storage layout, compression, and link creation order tracking. + * Unlike file access properties, creation properties \Emph{are} + * stored with the group, and cannot be changed once a group has been + * created. + * + * \defgroup GPLO General Property List Operations + * \ingroup H5P + * + * Use the functions in this module to manage HDF5 property lists. + * + * \defgroup GPLOA General Property List Operations (Advanced) + * \ingroup H5P + * + * You can create and customize user-defined property list classes using the + * functions described below. Arbitrary user-defined properties can also + * be inserted into existing property lists as so-called temporary properties. + * + * \defgroup LAPL Link Access Properties + * \ingroup H5P + * + * \defgroup MAPL Map Access Properties + * \ingroup H5P + * \defgroup OCPL Object Creation Properties + * \ingroup H5P + * + * \defgroup OCPPL Object Copy Properties + * \ingroup H5P + * + */ + /* * This file contains function prototypes for each exported function in the * H5P module. @@ -3572,10 +3669,8 @@ H5_DLL herr_t H5Pget_small_data_block_size(hid_t fapl_id, hsize_t *size /*out*/) * the file. For MPI IO and other parallel systems, choose an * alignment which is a multiple of the disk block size. * - * If the file space handling strategy is set to - * #H5F_FSPACE_STRATEGY_PAGE, then the alignment set via this - * routine is ignored. The file space handling strategy is set - * by H5Pset_file_space_strategy(). + * The file space handling strategy is set by + * H5Pset_file_space_strategy(). * * \since 1.0.0 * @@ -4690,8 +4785,6 @@ H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out * - #H5D_CHUNKED: Raw data is stored separately from the object * header in chunks in separate locations in the * file. - * - #H5D_VIRTUAL: Raw data is drawn from multiple datasets in - * different files. * \return * Otherwise, returns a negative value indicating failure. * @@ -4703,8 +4796,6 @@ H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value /*out * the dataset with parallel applications. See the H5Dwrite() * documentation for details. * - * \version 1.10.0 #H5D_VIRTUAL added in this release. - * * \since 1.0.0 * */ @@ -5007,13 +5098,11 @@ H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); * - #H5D_CHUNKED: Store raw data separately from the object header * as chunks of data in separate locations in * the file. - * - #H5D_VIRTUAL: Draw raw data from multiple datasets in - * different files. * * Note that a compact storage layout may affect writing data to * the dataset with parallel applications. See the note in * H5Dwrite() documentation for details. - * \version 1.10.0 #H5D_VIRTUAL added in this release. + * * \since 1.0.0 * */ diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index 81ae514..4ba7da1 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -11,6 +11,15 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/** + * \defgroup H5R H5R + * + * Use the functions in this module to manage HDF5 references. Referents can + * be HDF5 objects, attributes, and selections on datasets a.k.a. dataset + * regions. + * + */ + /* * This file contains public declarations for the H5R module. */ @@ -127,7 +136,7 @@ H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t re * * \brief Opens the HDF5 object referenced * - * \obj_id + * \dset_id{dataset} * \param[in] ref_type The reference type of \p ref * \param[in] ref Reference to open * @@ -199,7 +208,7 @@ H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); * \param[in] id The dataset containing the reference object or the group * containing that dataset * \param[in] ref_type Type of reference to query - * \param[in] ref Reference to query + * \param[in] _ref Reference to query * \param[out] obj_type Type of referenced object * * \return \herr_t diff --git a/src/H5Spublic.h b/src/H5Spublic.h index 7291c84..dbe0a51 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -11,6 +11,20 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5S H5S + * + * Use the functions in this module to manage HDF5 dataspaces \Emph{and} selections. + * + * HDF5 dataspaces describe the \Emph{shape} of datasets in memory or in HDF5 + * files. Dataspaces can be empty (#H5S_NULL), a singleton (#H5S_SCALAR), or + * a multi-dimensional, regular grid (#H5S_SIMPLE). Dataspaces can be re-shaped. + * + * Subsets of dataspaces can be "book-marked" or used to restrict I/O operations + * using \Emph{selections}. Furthermore, certain set operations are supported + * for selections. + * + */ + /* * This file contains public declarations for the H5S module. */ diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h index b34138b..b5dc566 100644 --- a/src/H5Tpublic.h +++ b/src/H5Tpublic.h @@ -11,6 +11,86 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5T H5T + * + * Use the functions in this module to manage HDF5 datatypes. + * + * HDF5 datatypes describe the element type of HDF5 datasets and attributes. + * There's a large set of predefined datatypes, but users may find it useful + * to define new datatypes through a process called \Emph{derivation}. + * + * The element type is automatically persisted as part of the HDF5 metadata of + * attributes and datasets. Additionally, datatype definitions can be persisted + * to HDF5 files and linked to groups as HDF5 datatype objects or so-called + * \Emph{committed datatypes}. + * + * \defgroup ARRAY Array Datatypes + * \ingroup H5T + * \defgroup ATOM Atomic Datatypes + * \ingroup H5T + * \defgroup COMPOUND Compound Datatypes + * \ingroup H5T + * \defgroup CONV Conversion Function + * \ingroup H5T + * \defgroup ENUM Enumeration Datatypes + * \ingroup H5T + * \defgroup OPAQUE Opaque Datatypes + * \ingroup H5T + * \defgroup VLEN Variable-length Sequence Datatypes + * \ingroup H5T + * + * \defgroup PDT Predefined Datatypes + * \ingroup H5T + * \details What is a predefined HDF5 datatype? + * \todo Fill in the blanks! + * + * \defgroup PDTCPU By CPU + * \ingroup PDT + * \details CPU-specific datatypes + * \defgroup PDTALPHA DEC Alpha + * \ingroup PDTCPU + * \defgroup PDTX86 AMD & INTEL + * \ingroup PDTCPU + * \defgroup PDTMIPS SGI MIPS + * \ingroup PDTCPU + * + * \defgroup PDTIEEE IEEE + * \ingroup PDT + * \details The IEEE floating point types in big- and little-endian byte orders. + * + * \defgroup PDTSTD Standard Datatypes + * \ingroup PDT + * \details These are "standard" types. For instance, signed (2's complement) + * and unsigned integers of various sizes in big- and little-endian + * byte orders. + * + * \defgroup PDTUNIX UNIX-specific Datatypes + * \ingroup PDT + * \details Types which are particular to Unix. + * \todo Fill in the blanks! + * + * \defgroup PDTNAT Native Datatypes + * \ingroup PDT + * \details These are the datatypes detected during library \Emph{compilation} + * by \c H5detect(). Their names differ from other HDF5 datatype names + * as follows: + * \li Instead of a class name, precision and byte order as the last + * component, they have a C-like type name. + * \li If the type begins with \c U then it is the unsigned version of + * the integer type; other integer types are signed. + * \li The datatype \c LLONG corresponds C's \Code{long long} and + * \c LDOUBLE is \Code{long double}. These types might be the same + * as \c LONG and \c DOUBLE, respectively. + * \defgroup PDTC9x C9x Integer Datatypes + * \ingroup PDTNAT + * \details C9x integer types + * \todo Fill in the blanks! + * + * \defgroup PDTS Strings + * \ingroup PDT + * + */ + /* * This file contains public declarations for the H5T module. */ diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index 90277cf..e1b3312 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -11,6 +11,73 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5Z H5Z + * + * Use the functions in this module to manage HDF5 filters. + * + * User-defined filters are created by registering a filter descriptor of + * type #H5Z_class_t with the library. + * + * Available filters can be read or examined at runtime. + * + * It is conceivable that filters are stateful and that that state be + * updated at runtime. + * + * Filters are deleted by unregistering. + * + * HDF5 supports a filter pipeline that provides the capability for standard and + * customized raw data processing during I/O operations. HDF5 is distributed + * with a small set of standard filters such as compression (gzip, SZIP, and a + * shuffling algorithm) and error checking (Fletcher32 checksum). For further + * flexibility, the library allows a user application to extend the pipeline + * through the creation and registration of customized filters. + * + * The flexibility of the filter pipeline implementation enables the definition + * of additional filters by a user application. A filter + * \li is associated with a dataset when the dataset is created, + * \li can be used only with chunked data (i.e., datasets stored in the + * #H5D_CHUNKED storage layout), and + * \li is applied independently to each chunk of the dataset. + * + * The HDF5 library does not support filters for contiguous datasets because of + * the difficulty of implementing random access for partial I/O. Compact dataset + * filters are not supported because it would not produce significant results. + * + * Filter identifiers for the filters distributed with the HDF5 + * Library are as follows: + * <table> + * <tr><td>#H5Z_FILTER_DEFLATE</td><td>The gzip compression, or + * deflation, filter</td></tr> + * <tr><td>#H5Z_FILTER_SZIP</td><td>The SZIP compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_NBIT</td><td>The N-bit compression + * filter</td></tr> + * <tr><td>#H5Z_FILTER_SCALEOFFSET</td><td>The scale-offset + * compression filter</td></tr> + * <tr><td>#H5Z_FILTER_SHUFFLE</td><td>The shuffle algorithm + * filter</td></tr> + * <tr><td>#H5Z_FILTER_FLETCHER32</td><td>The Fletcher32 checksum, + * or error checking, filter</td></tr> + * </table> + * Custom filters that have been registered with the library will have + * additional unique identifiers. + * + * See \ref_dld_filters for more information on how an HDF5 application can + * apply a filter that is not registered with the HDF5 library. + * + * \defgroup H5ZPRE Predefined Filters + * \ingroup H5Z + * \defgroup FLETCHER32 Checksum Filter + * \ingroup H5ZPRE + * \defgroup SCALEOFFSET Scale-Offset Filter + * \ingroup H5ZPRE + * \defgroup SHUFFLE Shuffle Filter + * \ingroup H5ZPRE + * \defgroup SZIP Szip Filter + * \ingroup H5ZPRE + * + */ + /* Programmer: Robb Matzke * Thursday, April 16, 1998 */ diff --git a/src/H5public.h b/src/H5public.h index 730e3de..3c90c2a 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -11,6 +11,13 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ +/**\defgroup H5 H5 + * + * Use the functions in this module to manage the life cycle of HDF5 library + * instances. + * + */ + /* * This file contains public declarations for the HDF5 module. */ |