diff options
Diffstat (limited to 'src/H5Ppublic.h')
| -rw-r--r-- | src/H5Ppublic.h | 374 |
1 files changed, 236 insertions, 138 deletions
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index a5c5c37..d0bc2b8 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -116,21 +116,70 @@ extern "C" { /* Define property list class callback function pointer types */ //! <!-- [H5P_cls_create_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] create_data User pointer to any class creation data required + * \return \herr_t + * + * \details This function is called when a new property list of the class + * with which this function was registered is being created. The + * function is called after any registered parent create function is + * called for each property value. + * + * If the create function returns a negative value, the new list is not + * returned to the user and the property list creation routine returns + * an error value. + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data); //! <!-- [H5P_cls_create_func_t_snip] --> //! <!-- [H5P_cls_copy_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] new_prop_id The identifier of the property list copy + * \param[in] old_prop_id The identifier of the property list being copied + * \param[in] copy_data User pointer to any copy data required + * \return \herr_t + * + * \details This function is called when an existing property list of this + * class is copied. The copy callback function is called after any + * registered parent copy callback function is called for each property + * value. + * + * If the copy routine returns a negative value, the new list is not + * returned to the user and the property list copy function returns an + * error value. + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data); //! <!-- [H5P_cls_copy_func_t_snip] --> //! <!-- [H5P_cls_close_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] close_data User pointer to any close data required + * \return \herr_t + * + * \details This function is called when a property list of the class + * with which this function was registered is being closed. The + * function is called after any registered parent close function is + * called for each property value. + * + * If the close function returns a negative value, the new list is not + * returned to the user and the property list close routine returns + * an error value. + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! <!-- [H5P_cls_close_func_t_snip] --> @@ -145,8 +194,8 @@ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); * \param[in,out] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb1_t() describes the parameters used by the - * property create,copy and close callback functions. + * \details The H5P_prp_cb1_t() function describes the parameters used by the + * property create, copy and close callback functions. */ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); //! <!-- [H5P_prp_cb1_t_snip] --> @@ -161,8 +210,8 @@ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); * \param[in] value The value for the property * \return \herr_t * - * \details The H5P_prp_cb2_t() describes the parameters used by the - * property set ,copy and delete callback functions. + * \details The H5P_prp_cb2_t() function describes the parameters used by the + * property set, copy and delete callback functions. */ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value); //! <!-- [H5P_prp_cb2_t_snip] --> @@ -172,13 +221,28 @@ typedef H5P_prp_cb2_t H5P_prp_set_func_t; typedef H5P_prp_cb2_t H5P_prp_get_func_t; //! <!-- [H5P_prp_encode_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for encoding property values + * + * \param[in] value The property value to be encoded + * \param[out] buf The encoded property value + * \param[out] size The size of \p buf + * \return \herr_t + * + * \note There is currently no public API which exposes a callback of this type. + * */ typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *size); //! <!-- [H5P_prp_encode_func_t_snip] --> //! <!-- [H5P_prp_decode_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for decoding property values + * + * \param[in] buf A buffer containing an encoded property value + * \param[out] value The decoded property value + * \return \herr_t + * + * \note There is currently no public API which exposes a callback of this type. + * */ typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value); //! <!-- [H5P_prp_decode_func_t_snip] --> @@ -187,7 +251,16 @@ typedef H5P_prp_cb1_t H5P_prp_copy_func_t; //! <!-- [H5P_prp_compare_func_t_snip] --> /** - * \todo Document me! + * \brief Callback function for comparing property values + * + * \param[in] value1 A property value + * \param[in] value2 A property value + * \param[in] size The size of the \p value1 and \p value2 buffers + * \return Returns a positive value if \c value1 is greater than \c value2, a + * negative value if \c value2 is greater than \c value1 and zero if + * \c value1 and \c value2 are equal. + * + * \see H5Pregister(), H5Pinsert() */ typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! <!-- [H5P_prp_compare_func_t_snip] --> @@ -197,7 +270,19 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! <!-- [H5P_iterate_t_snip] --> /** - * \todo Document me! + * \brief Callback function for H5Piterate() + * + * \param[in] id The identifier of a property list or property list class + * \param[in] name The name of the current property + * \param[in,out] iter_data The user context passed to H5Piterate() + * \return \herr_t_iter + * + * \details This function is called for each property encountered when + * iterating over a property list or property list class + * via H5Piterate(). + * + * \since 1.4.0 + * */ typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! <!-- [H5P_iterate_t_snip] --> @@ -264,15 +349,15 @@ typedef enum H5D_mpio_no_collective_cause_t { H5D_MPIO_DATA_TRANSFORMS = 0x04, /**< Collective I/O was not performed because data transforms needed to be applied */ H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, - /**< \todo FIXME! */ + /**< Collective I/O was disabled by environment variable (\Code{HDF5_MPI_OPT_TYPES}) */ H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, /**< Collective I/O was not performed because one of the dataspaces was neither simple nor scalar */ H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, /**< Collective I/O was not performed because the dataset was neither contiguous nor chunked */ H5D_MPIO_PARALLEL_FILTERED_WRITES_DISABLED = 0x40, - /**< \todo FIXME! */ + /**< Collective I/O was not performed because parallel filtered writes are disabled */ H5D_MPIO_ERROR_WHILE_CHECKING_COLLECTIVE_POSSIBLE = 0x80, - /**< \todo FIXME! */ + /**< Error */ H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x100 /**< Sentinel */ } H5D_mpio_no_collective_cause_t; @@ -577,77 +662,12 @@ H5_DLL hid_t H5Pcreate(hid_t cls_id); * those existing properties, only add or remove their own class * properties. Property list classes defined and supported in the * HDF5 library distribution are listed and briefly described in - * H5Pcreate(). The \p create routine is called when a new property - * list of this class is being created. The #H5P_cls_create_func_t - * callback function is defined as follows: - * - * \snippet this H5P_cls_create_func_t_snip - * - * The parameters to this callback function are defined as follows: - * <table> - * <tr> - * <td>\ref hid_t \c prop_id</td> - * <td>IN: The identifier of the property list being created</td> - * </tr> - * <tr> - * <td>\Code{void * create_data}</td> - * <td>IN: User pointer to any class creation data required</td> - * </tr> - * </table> - * - * The \p create routine is called after any registered - * \p create function is called for each property value. If the - * \p create routine returns a negative value, the new list is not - * returned to the user and the property list creation routine returns - * an error value. - * - * The \p copy routine is called when an existing property - * list of this class is copied. The #H5P_cls_copy_func_t callback - * function is defined as follows: - * \snippet this H5P_cls_copy_func_t_snip + * H5Pcreate(). The \p create, \p copy, \p close functions are called + * when a property list of the new class is created, copied, or closed, + * respectively. * - * The parameters to this callback function are defined as follows: - * <table> - * <tr> - * <td>\ref hid_t \c prop_id</td> - * <td>IN: The identifier of the property list created by copying</td> - * </tr> - * <tr> - * <td>\Code{void * copy_data}</td> - * <td>IN: User pointer to any class copy data required</td> - * </tr> - * </table> - * - * The \p copy routine is called after any registered \p copy function - * is called for each property value. If the \p copy routine returns a - * negative value, the new list is not returned to the user and the - * property list \p copy routine returns an error value. - * - * The \p close routine is called when a property list of this class - * is being closed. The #H5P_cls_close_func_t callback function is - * defined as follows: - * \snippet this H5P_cls_close_func_t_snip - * - * The parameters to this callback function are defined as follows: - * <table> - * <tr> - * <td>\ref hid_t \c prop_id</td> - * <td>IN: The identifier of the property list being closed</td> - * </tr> - * <tr> - * <td>\Code{void * close_data}</td> - * <td>IN: User pointer to any class close data required</td> - * </tr> - * </table> - * - * The \p close routine is called before any registered \p close - * function is called for each property value. If the \p close routine - * returns a negative value, the property list close routine returns - * an error value but the property list is still closed. - * - * H5Pclose_class() can be used to release the property list class - * identifier returned by this function so that resources leaks will - * not develop. + * H5Pclose_class() must be used to release the property list class + * identifier returned by this function. * * \since 1.4.0 * @@ -1376,35 +1396,12 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); * returned in this case, the iterator cannot be restarted if * one of the calls to its operator returns non-zero. * - * The prototype for the #H5P_iterate_t operator is as follows: - * \snippet this H5P_iterate_t_snip - * - * The operation receives the property list or class + * The operation \p iter_func receives the property list or class * identifier for the object being iterated over, \p id, the * name of the current property within the object, \p name, * and the pointer to the operator data passed in to H5Piterate(), - * \p iter_data. The valid return values from an operator are - * as follows: + * \p iter_data. * - * <table> - * <tr> - * <td>Zero</td> - * <td>Causes the iterator to continue, returning zero when all - * properties have been processed</td> - * </tr> - * <tr> - * <td>Positive</td> - * <td>Causes the iterator to immediately return that positive - * value, indicating short-circuit success. The iterator - * can be restarted at the index of the next property</td> - * </tr> - * <tr> - * <td>Negative</td> - * <td>Causes the iterator to immediately return that value, - * indicating failure. The iterator can be restarted at the - * index of the next property</td> - * </tr> - * </table> * H5Piterate() assumes that the properties in the object * identified by \p id remain unchanged through the iteration. * If the membership changes during the iteration, the function's @@ -1877,9 +1874,6 @@ H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, un * * \brief Returns information about a filter in a pipeline * - * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in - * H5Ppublic.h - * * \ocpl_id{plist_id} * \param[in] idx Sequence number within the filter pipeline of the filter * for which information is sought @@ -3448,6 +3442,34 @@ H5_DLL const void *H5Pget_driver_info(hid_t plist_id); /** * \ingroup FAPL * + * \brief Retrieves a string representation of the configuration for + * the driver set on the given FAPL. The returned string can + * be used to configure the same driver in an identical way. + * + * \fapl_id + * \param[out] config_buf Driver configuration string output buffer + * \param[in] buf_size Size of driver configuration string output buffer + * + * \return Returns the length of the driver configuration string on + * success (not including the NUL terminator). Returns negative + * on failure. + * + * \details H5Pget_driver_config_str() retrieves a string representation + * of the configuration for the driver set on the given FAPL. The + * returned string can be used to configure the same driver in + * an identical way. + * + * If \p config_buf is NULL, the length of the driver configuration + * string is simply returned. The caller can then allocate a buffer + * of the appropriate size and call this routine again. + * + * \version 1.12.1 Function publicized in this release. + * + */ +H5_DLL ssize_t H5Pget_driver_config_str(hid_t fapl_id, char *config_buf, size_t buf_size); +/** + * \ingroup FAPL + * * \brief Retrieves the size of the external link open file cache * * \fapl_id{plist_id} @@ -3884,13 +3906,13 @@ H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size); * * The second example illustrates the two cases for retrieving the * number of read attempts from the file access property list of a file - * opened with SWMR acccess. + * opened with SWMR access. * * \include H5Pget_metadata_read_attempts.2.c * * The third example illustrates the two cases for retrieving the number * of read attempts from the file access property list of a file opened - * with non-SWMR acccess. + * with non-SWMR access. * * \include H5Pget_metadata_read_attempts.3.c * @@ -4177,17 +4199,14 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme * * \note Note: Raw dataset chunk caching is not currently * supported when using the MPI I/O and MPI POSIX file drivers - * in read/write mode; see H5Pset_fapl_mpio() and - * H5Pset_fapl_mpiposix(), respectively. When using one of these - * file drivers, all calls to H5Dread() and H5Dwrite() will access + * in read/write mode; see H5Pset_fapl_mpio(). When using this + * file driver, all calls to H5Dread() and H5Dwrite() will access * the disk directly, and H5Pset_cache() will have no effect on * performance. * * \note Raw dataset chunk caching is supported when these drivers are * used in read-only mode. * - * \todo Check on H5Pset_fapl_mpio() and H5Pset_fapl_mpiposix(). - * * \version 1.8.0 The use of the \p mdc_nelmts parameter was discontinued. * Metadata cache configuration is managed with * H5Pset_mdc_config() and H5Pget_mdc_config(). @@ -4287,6 +4306,57 @@ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_ /** * \ingroup FAPL * + * \brief Sets a file driver according to a given driver name + * + * \plist_id + * \param[in] driver_name The new driver name + * \param[in] driver_config Optional string containing driver properties + * + * \return \herr_t + * + * \details H5Pset_driver_by_name() sets the file driver, by the name + * driver_name, for a file access or data transfer property list, + * \p plist_id, and supplies an optional string containing the + * driver-specific properties, \p driver_config. The driver + * properties string will be copied into the property list. + * + * If the driver specified by \p driver_name is not currently + * registered, an attempt will be made to load the driver as a + * plugin. + * + * \version 1.12.1 Function publicized in this release. + * + */ +H5_DLL herr_t H5Pset_driver_by_name(hid_t plist_id, const char *driver_name, const char *driver_config); +/** + * \ingroup FAPL + * + * \brief Sets a file driver according to a given driver value (ID). + * + * \plist_id + * \param[in] driver_value The new driver value (ID) + * \param[in] driver_config Optional string containing driver properties + * + * \return \herr_t + * + * \details H5Pset_driver_by_value() sets the file driver, by the value + * driver_value, for a file access or data transfer property list, + * \p plist_id, and supplies an optional string containing the + * driver-specific properties, \p driver_config. The driver + * properties string will be copied into the property list. + * + * If the driver specified by \p driver_value is not currently + * registered, an attempt will be made to load the driver as a + * plugin. + * + * \version 1.12.1 Function publicized in this release. + * + */ +H5_DLL herr_t H5Pset_driver_by_value(hid_t plist_id, H5FD_class_value_t driver_value, + const char *driver_config); +/** + * \ingroup FAPL + * * \brief Sets the number of files that can be held open in an external * link open file cache * @@ -4295,7 +4365,7 @@ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_ * The <em>external link open file cache</em> holds files open after * they have been accessed via an external link. This cache reduces * the number of times such files are opened when external links are - * accessed repeatedly and can siginificantly improves performance in + * accessed repeatedly and can significantly improves performance in * certain heavy-use situations and when low-level file opens or closes * are expensive. * @@ -5404,12 +5474,38 @@ H5_DLL herr_t H5Pset_coll_metadata_write(hid_t plist_id, hbool_t is_collective); H5_DLL herr_t H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective); /** - * \todo Add missing documentation + * \ingroup FAPL + * + * \brief Get the MPI communicator and info + * + * \fapl_id + * \param[out] comm MPI communicator + * \param[out] info MPI info object + * \return \herr_t + * + * \details H5Pget_mpi_params() gets the MPI communicator and info stored in + * the file access property list \p fapl_id. + * + * \todo When was this introduced? + * */ H5_DLL herr_t H5Pget_mpi_params(hid_t fapl_id, MPI_Comm *comm, MPI_Info *info); /** - * \todo Add missing documentation + * \ingroup FAPL + * + * \brief Set the MPI communicator and info + * + * \fapl_id + * \param[in] comm MPI communicator + * \param[in] info MPI info object + * \return \herr_t + * + * \details H5Pset_mpi_params() sets the MPI communicator and info stored in + * the file access property list \p fapl_id. + * + * \todo When was this introduced? + * */ H5_DLL herr_t H5Pset_mpi_params(hid_t fapl_id, MPI_Comm comm, MPI_Info info); #endif /* H5_HAVE_PARALLEL */ @@ -6392,10 +6488,10 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * <td>byte 0</td> * </tr> * <tr> - * <td>????????</td> - * <td>????SPPP</td> - * <td>PPPPPPPP</td> - * <td>PPPP????</td> + * <td> ???????? </td> + * <td> ????SPPP </td> + * <td> PPPPPPPP </td> + * <td> PPPP???? </td> * </tr> * </table> * Note: S - sign bit, P - significant bit, ? - padding bit; For @@ -7021,9 +7117,6 @@ H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t dapl_id, hsize_t *gap_size); * * \dapl_id * \param[out] view The flag specifying the view of the virtual dataset. - * Valid values are: - * \li #H5D_VDS_FIRST_MISSING - * \li #H5D_VDS_LAST_AVAILABLE * * \return \herr_t * @@ -7377,11 +7470,7 @@ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); * * \dapl_id * \param[in] view Flag specifying the extent of the data to be included - * in the view. Valid values are: - * \li #H5D_VDS_FIRST_MISSING: View includes all data - * before the first missing mapped data - * \li #H5D_VDS_LAST_AVAILABLE View includes all - * available mapped data + * in the view. * * \return \herr_t * @@ -7549,8 +7638,11 @@ H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); * \details H5Pget_preserve() checks the status of the dataset transfer * property list. * + * \since 1.0.0 + * * \version 1.6.0 The flag parameter was changed from INTEGER to LOGICAL to * better match the C API. (Fortran 90) + * \version 1.8.2 Deprecated. * */ H5_DLL int H5Pget_preserve(hid_t plist_id); @@ -7578,6 +7670,8 @@ H5_DLL int H5Pget_preserve(hid_t plist_id); * * Please refer to the function H5Pset_type_conv_cb() for more details. * + * \since 1.8.0 + * */ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); /** @@ -7601,6 +7695,8 @@ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, voi * H5Pset_vlen_mem_manager(), returning the parameters set by * that function. * + * \since 1.0.0 + * */ H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, H5MM_free_t *free_func, void **free_info); @@ -7844,8 +7940,9 @@ H5_DLL herr_t H5Pset_hyper_vector_size(hid_t plist_id, size_t size); * I/O pipeline treats the destination datapoints as completely * uninitialized. * - * \todo Add missing version information: introduction, deprecation, etc. - * Why is the declaration not in the deprecated section? + * \since 1.0.0 + * + * \version 1.8.2 Deprecated. * */ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); @@ -7873,7 +7970,7 @@ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); * function prototype is as follows: * \snippet H5Tpublic.h H5T_conv_except_func_t_snip * - * \todo Add version information. + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); @@ -7923,7 +8020,8 @@ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void * set to \c NULL and the \p alloc_info and \p free_info parameters are * ignored. * - * \todo Add version information. + * \since 1.0.0 + * */ H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, H5MM_free_t free_func, void *free_info); |