/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://support.hdfgroup.org/ftp/HDF5/releases. * * If you do not have access to either file, you may request a copy from * * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* * This file contains function prototypes for each exported function in the * H5P module. */ #ifndef _H5Ppublic_H #define _H5Ppublic_H /* System headers needed by this file */ /* Public headers needed by this file */ #include "H5public.h" #include "H5ACpublic.h" #include "H5Dpublic.h" #include "H5Fpublic.h" #include "H5FDpublic.h" #include "H5Ipublic.h" #include "H5Lpublic.h" #include "H5Opublic.h" #include "H5MMpublic.h" #include "H5Tpublic.h" #include "H5Zpublic.h" /*****************/ /* Public Macros */ /*****************/ /* When this header is included from a private HDF5 header, don't make calls to H5open() */ #undef H5OPEN #ifndef _H5private_H #define H5OPEN H5open(), #else /* _H5private_H */ #define H5OPEN #endif /* _H5private_H */ /* * The library's property list classes */ #define H5P_ROOT (H5OPEN H5P_CLS_ROOT_ID_g) #define H5P_OBJECT_CREATE (H5OPEN H5P_CLS_OBJECT_CREATE_ID_g) #define H5P_FILE_CREATE (H5OPEN H5P_CLS_FILE_CREATE_ID_g) #define H5P_FILE_ACCESS (H5OPEN H5P_CLS_FILE_ACCESS_ID_g) #define H5P_DATASET_CREATE (H5OPEN H5P_CLS_DATASET_CREATE_ID_g) #define H5P_DATASET_ACCESS (H5OPEN H5P_CLS_DATASET_ACCESS_ID_g) #define H5P_DATASET_XFER (H5OPEN H5P_CLS_DATASET_XFER_ID_g) #define H5P_FILE_MOUNT (H5OPEN H5P_CLS_FILE_MOUNT_ID_g) #define H5P_GROUP_CREATE (H5OPEN H5P_CLS_GROUP_CREATE_ID_g) #define H5P_GROUP_ACCESS (H5OPEN H5P_CLS_GROUP_ACCESS_ID_g) #define H5P_DATATYPE_CREATE (H5OPEN H5P_CLS_DATATYPE_CREATE_ID_g) #define H5P_DATATYPE_ACCESS (H5OPEN H5P_CLS_DATATYPE_ACCESS_ID_g) #define H5P_MAP_CREATE (H5OPEN H5P_CLS_MAP_CREATE_ID_g) #define H5P_MAP_ACCESS (H5OPEN H5P_CLS_MAP_ACCESS_ID_g) #define H5P_STRING_CREATE (H5OPEN H5P_CLS_STRING_CREATE_ID_g) #define H5P_ATTRIBUTE_CREATE (H5OPEN H5P_CLS_ATTRIBUTE_CREATE_ID_g) #define H5P_ATTRIBUTE_ACCESS (H5OPEN H5P_CLS_ATTRIBUTE_ACCESS_ID_g) #define H5P_OBJECT_COPY (H5OPEN H5P_CLS_OBJECT_COPY_ID_g) #define H5P_LINK_CREATE (H5OPEN H5P_CLS_LINK_CREATE_ID_g) #define H5P_LINK_ACCESS (H5OPEN H5P_CLS_LINK_ACCESS_ID_g) #define H5P_VOL_INITIALIZE (H5OPEN H5P_CLS_VOL_INITIALIZE_ID_g) #define H5P_REFERENCE_ACCESS (H5OPEN H5P_CLS_REFERENCE_ACCESS_ID_g) /* * The library's default property lists */ #define H5P_FILE_CREATE_DEFAULT (H5OPEN H5P_LST_FILE_CREATE_ID_g) #define H5P_FILE_ACCESS_DEFAULT (H5OPEN H5P_LST_FILE_ACCESS_ID_g) #define H5P_DATASET_CREATE_DEFAULT (H5OPEN H5P_LST_DATASET_CREATE_ID_g) #define H5P_DATASET_ACCESS_DEFAULT (H5OPEN H5P_LST_DATASET_ACCESS_ID_g) #define H5P_DATASET_XFER_DEFAULT (H5OPEN H5P_LST_DATASET_XFER_ID_g) #define H5P_FILE_MOUNT_DEFAULT (H5OPEN H5P_LST_FILE_MOUNT_ID_g) #define H5P_GROUP_CREATE_DEFAULT (H5OPEN H5P_LST_GROUP_CREATE_ID_g) #define H5P_GROUP_ACCESS_DEFAULT (H5OPEN H5P_LST_GROUP_ACCESS_ID_g) #define H5P_DATATYPE_CREATE_DEFAULT (H5OPEN H5P_LST_DATATYPE_CREATE_ID_g) #define H5P_DATATYPE_ACCESS_DEFAULT (H5OPEN H5P_LST_DATATYPE_ACCESS_ID_g) #define H5P_MAP_CREATE_DEFAULT (H5OPEN H5P_LST_MAP_CREATE_ID_g) #define H5P_MAP_ACCESS_DEFAULT (H5OPEN H5P_LST_MAP_ACCESS_ID_g) #define H5P_ATTRIBUTE_CREATE_DEFAULT (H5OPEN H5P_LST_ATTRIBUTE_CREATE_ID_g) #define H5P_ATTRIBUTE_ACCESS_DEFAULT (H5OPEN H5P_LST_ATTRIBUTE_ACCESS_ID_g) #define H5P_OBJECT_COPY_DEFAULT (H5OPEN H5P_LST_OBJECT_COPY_ID_g) #define H5P_LINK_CREATE_DEFAULT (H5OPEN H5P_LST_LINK_CREATE_ID_g) #define H5P_LINK_ACCESS_DEFAULT (H5OPEN H5P_LST_LINK_ACCESS_ID_g) #define H5P_VOL_INITIALIZE_DEFAULT (H5OPEN H5P_LST_VOL_INITIALIZE_ID_g) #define H5P_REFERENCE_ACCESS_DEFAULT (H5OPEN H5P_LST_REFERENCE_ACCESS_ID_g) /* Common creation order flags (for links in groups and attributes on objects) */ #define H5P_CRT_ORDER_TRACKED 0x0001 #define H5P_CRT_ORDER_INDEXED 0x0002 /* Default value for all property list classes */ #define H5P_DEFAULT (hid_t)0 #ifdef __cplusplus extern "C" { #endif /*******************/ /* Public Typedefs */ /*******************/ /* Define property list class callback function pointer types */ //! [H5P_cls_create_func_t_snip] 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] 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] typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! [H5P_cls_close_func_t_snip] /* Define property list callback function pointer types */ //! [H5P_prp_cb1_t_snip] typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); //! [H5P_prp_cb1_t_snip] //! [H5P_prp_cb2_t_snip] typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value); //! [H5P_prp_cb2_t_snip] typedef H5P_prp_cb1_t H5P_prp_create_func_t; typedef H5P_prp_cb2_t H5P_prp_set_func_t; typedef H5P_prp_cb2_t H5P_prp_get_func_t; typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *size); typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value); typedef H5P_prp_cb2_t H5P_prp_delete_func_t; typedef H5P_prp_cb1_t H5P_prp_copy_func_t; //! [H5P_prp_compare_func_t_snip] typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! [H5P_prp_compare_func_t_snip] typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! [H5P_iterate_t_snip] typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! [H5P_iterate_t_snip] /* Actual IO mode property */ typedef enum H5D_mpio_actual_chunk_opt_mode_t { /* The default value, H5D_MPIO_NO_CHUNK_OPTIMIZATION, is used for all I/O * operations that do not use chunk optimizations, including non-collective * I/O and contiguous collective I/O. */ H5D_MPIO_NO_CHUNK_OPTIMIZATION = 0, H5D_MPIO_LINK_CHUNK, H5D_MPIO_MULTI_CHUNK } H5D_mpio_actual_chunk_opt_mode_t; typedef enum H5D_mpio_actual_io_mode_t { /* The following four values are conveniently defined as a bit field so that * we can switch from the default to independent or collective and then to * mixed without having to check the original value. * * NO_COLLECTIVE means that either collective I/O wasn't requested or that * no I/O took place. * * CHUNK_INDEPENDENT means that collective I/O was requested, but the * chunk optimization scheme chose independent I/O for each chunk. */ H5D_MPIO_NO_COLLECTIVE = 0x0, H5D_MPIO_CHUNK_INDEPENDENT = 0x1, H5D_MPIO_CHUNK_COLLECTIVE = 0x2, H5D_MPIO_CHUNK_MIXED = 0x1 | 0x2, /* The contiguous case is separate from the bit field. */ H5D_MPIO_CONTIGUOUS_COLLECTIVE = 0x4 } H5D_mpio_actual_io_mode_t; /* Broken collective IO property */ typedef enum H5D_mpio_no_collective_cause_t { H5D_MPIO_COLLECTIVE = 0x00, H5D_MPIO_SET_INDEPENDENT = 0x01, H5D_MPIO_DATATYPE_CONVERSION = 0x02, H5D_MPIO_DATA_TRANSFORMS = 0x04, H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, H5D_MPIO_PARALLEL_FILTERED_WRITES_DISABLED = 0x40, H5D_MPIO_ERROR_WHILE_CHECKING_COLLECTIVE_POSSIBLE = 0x80, H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x100 } H5D_mpio_no_collective_cause_t; /********************/ /* Public Variables */ /********************/ /* Property list class IDs */ /* (Internal to library, do not use! Use macros above) */ H5_DLLVAR hid_t H5P_CLS_ROOT_ID_g; H5_DLLVAR hid_t H5P_CLS_OBJECT_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_FILE_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_FILE_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_DATASET_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_DATASET_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_DATASET_XFER_ID_g; H5_DLLVAR hid_t H5P_CLS_FILE_MOUNT_ID_g; H5_DLLVAR hid_t H5P_CLS_GROUP_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_GROUP_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_DATATYPE_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_DATATYPE_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_MAP_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_MAP_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_STRING_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_ATTRIBUTE_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_ATTRIBUTE_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_OBJECT_COPY_ID_g; H5_DLLVAR hid_t H5P_CLS_LINK_CREATE_ID_g; H5_DLLVAR hid_t H5P_CLS_LINK_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_VOL_INITIALIZE_ID_g; H5_DLLVAR hid_t H5P_CLS_REFERENCE_ACCESS_ID_g; /* Default roperty list IDs */ /* (Internal to library, do not use! Use macros above) */ H5_DLLVAR hid_t H5P_LST_FILE_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_FILE_ACCESS_ID_g; H5_DLLVAR hid_t H5P_LST_DATASET_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_DATASET_ACCESS_ID_g; H5_DLLVAR hid_t H5P_LST_DATASET_XFER_ID_g; H5_DLLVAR hid_t H5P_LST_FILE_MOUNT_ID_g; H5_DLLVAR hid_t H5P_LST_GROUP_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_GROUP_ACCESS_ID_g; H5_DLLVAR hid_t H5P_LST_DATATYPE_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_DATATYPE_ACCESS_ID_g; H5_DLLVAR hid_t H5P_LST_MAP_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_MAP_ACCESS_ID_g; H5_DLLVAR hid_t H5P_LST_ATTRIBUTE_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_ATTRIBUTE_ACCESS_ID_g; H5_DLLVAR hid_t H5P_LST_OBJECT_COPY_ID_g; H5_DLLVAR hid_t H5P_LST_LINK_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_LINK_ACCESS_ID_g; H5_DLLVAR hid_t H5P_LST_VOL_INITIALIZE_ID_g; H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g; /*********************/ /* Public Prototypes */ /*********************/ /* Generic property list routines */ /** * \ingroup GPLO * * \brief Terminates access to a property list * * \plist_id * * \return \herr_t * * \details H5Pclose() terminates access to a property list. All property * lists should be closed when the application is finished * accessing them. This frees resources used by the property * list. * * \since 1.0.0 * */ H5_DLL herr_t H5Pclose(hid_t plist_id); /** * \ingroup GPLOA * * \brief Closes an existing property list class * * \plistcls_id{plist_id} * * \return \herr_t * * \details H5Pclose_class() removes a property list class from the library. * Existing property lists of this class will continue to exist, * but new ones are not able to be created. * * \since 1.4.0 * */ H5_DLL herr_t H5Pclose_class(hid_t plist_id); /** * \ingroup GPLO * * \brief Copies an existing property list to create a new property list * * \plist_id * * \return \hid_t{property list} * * \details H5Pcopy() copies an existing property list to create a new * property list. The new property list has the same properties * and values as the original property list. * * \since 1.0.0 * */ H5_DLL hid_t H5Pcopy(hid_t plist_id); /** * \ingroup GPLOA * * \brief Copies a property from one list or class to another * * \param[in] dst_id Identifier of the destination property list or class * \param[in] src_id Identifier of the source property list or class * \param[in] name Name of the property to copy * * \return \herr_t * * \details H5Pcopy_prop() copies a property from one property list or * class to another. * * If a property is copied from one class to another, all the * property information will be first deleted from the destination * class and then the property information will be copied from the * source class into the destination class. * * If a property is copied from one list to another, the property * will be first deleted from the destination list (generating a * call to the close callback for the property, if one exists) * and then the property is copied from the source list to the * destination list (generating a call to the copy callback for * the property, if one exists). * * If the property does not exist in the class or list, this * call is equivalent to calling H5Pregister() or H5Pinsert() (for * a class or list, as appropriate) and the create callback will * be called in the case of the property being copied into a list * (if such a callback exists for the property). * * \since 1.6.0 * */ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); /** * \ingroup GPLO * * \brief Creates a new property list as an instance of a property list class * * \plistcls_id{cls_id} * * \return \hid_t{property list} * * \details H5Pcreate() creates a new property list as an instance of * some property list class. The new property list is initialized * with default values for the specified class. The classes are as * follows: * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Class IdentifierClass NameComments
#H5P_ATTRIBUTE_CREATEattribute createProperties for attribute creation
#H5P_DATASET_ACCESSdataset accessProperties for dataset access
#H5P_DATASET_CREATEdataset createProperties for dataset creation
#H5P_DATASET_XFERdata transferProperties for raw data transfer
#H5P_DATATYPE_ACCESSdatatype accessProperties for datatype access
#H5P_DATATYPE_CREATEdatatype createProperties for datatype creation
#H5P_FILE_ACCESSfile accessProperties for file access
#H5P_FILE_CREATEfile createProperties for file creation
#H5P_FILE_MOUNTfile mountProperties for file mounting
#H5P_GROUP_ACCESSgroup accessProperties for group access
#H5P_GROUP_CREATEgroup createProperties for group creation
#H5P_LINK_ACCESSlink accessProperties governing link traversal when accessing objects
#H5P_LINK_CREATElink createProperties governing link creation
#H5P_OBJECT_COPYobject copyProperties governing the object copying process
#H5P_OBJECT_CREATEobject createProperties for object creation
#H5P_STRING_CREATEstring createProperties for character encoding when encoding strings or * object names
#H5P_VOL_INITIALIZEvol initializeProperties for VOL initialization
* * This property list must eventually be closed with H5Pclose(); * otherwise, errors are likely to occur. * * \version 1.12.0 The #H5P_VOL_INITIALIZE property list class was added * \version 1.8.15 For each class, the class name returned by * H5Pget_class_name() was added. * The list of possible Fortran values was updated. * \version 1.8.0 The following property list classes were added at this * release: #H5P_DATASET_ACCESS, #H5P_GROUP_CREATE, * #H5P_GROUP_ACCESS, #H5P_DATATYPE_CREATE, * #H5P_DATATYPE_ACCESS, #H5P_ATTRIBUTE_CREATE * * \since 1.0.0 * */ H5_DLL hid_t H5Pcreate(hid_t cls_id); /** * \ingroup GPLOA * * \brief Creates a new property list class * * \plistcls_id{parent} * \param[in] name Name of property list class to register * \param[in] create Callback routine called when a property list is * created * \param[in] create_data Pointer to user-defined class create data, to be * passed along to class create callback * \param[in] copy Callback routine called when a property list is * copied * \param[in] copy_data Pointer to user-defined class copy data, to be * passed along to class copy callback * \param[in] close Callback routine called when a property list is * being closed * \param[in] close_data Pointer to user-defined class close data, to be * passed along to class close callback * * \return \hid_t{property list class} * * \details H5Pcreate_class() registers a new property list class with the * library. The new property list class can inherit from an * existing property list class, \p parent, or may be derived * from the default “empty” class, NULL. New classes with * inherited properties from existing classes may not remove * 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: * * \todo fix snippets to work, when you click on them. * * \snippet this H5P_cls_create_func_t_snip * * The parameters to this callback function are defined as follows: * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list being created
\Code{void * create_data}IN: User pointer to any class creation data required
* * 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 * * The parameters to this callback function are defined as follows: * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list created by copying
\Code{void * copy_data}IN: User pointer to any class copy data required
* * 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: * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list being closed
\Code{void * close_data}IN: User pointer to any class close data required
* * 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. * * \since 1.4.0 * */ H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func_t create, void *create_data, H5P_cls_copy_func_t copy, void *copy_data, H5P_cls_close_func_t close, void *close_data); /** * \ingroup GPLO * * \brief Decodes property list received in a binary object buffer and * returns a new property list identifier * * \param[in] buf Buffer holding the encoded property list * * \return \hid_tv{object} * * \details Given a binary property list description in a buffer, H5Pdecode() * reconstructs the HDF5 property list and returns an identifier * for the new property list. The binary description of the property * list is encoded by H5Pencode(). * * The user is responsible for passing in the correct buffer. * * The property list identifier returned by this function should be * released with H5Pclose() when the identifier is no longer needed * so that resource leaks will not develop. * * \note Some properties cannot be encoded and therefore will not be available * in the decoded property list. These properties are discussed in * H5Pencode(). * * \since 1.10.0 * */ H5_DLL hid_t H5Pdecode(const void *buf); /** * \ingroup GPLO * * \brief Encodes the property values in a property list into a binary * buffer * * \plist_id * \param[out] buf Buffer into which the property list will be encoded. * If the provided buffer is NULL, the size of the * buffer required is returned through \p nalloc; the * function does nothing more. * \param[out] nalloc The size of the required buffer * \fapl_id * * \return \herr_t * * \details H5Pencode2() encodes the property list \p plist_id into the * binary buffer \p buf, according to the file format setting * specified by the file access property list \p fapl_id. * * If the required buffer size is unknown, \p buf can be passed * in as NULL and the function will set the required buffer size * in \p nalloc. The buffer can then be created and the property * list encoded with a subsequent H5Pencode2() call. * * If the buffer passed in is not big enough to hold the encoded * properties, the H5Pencode2() call can be expected to fail with * a segmentation fault. * * The file access property list \p fapl_id is used to * control the encoding via the \a libver_bounds property * (see H5Pset_libver_bounds()). If the \a libver_bounds * property is missing, H5Pencode2() proceeds as if the \a * libver_bounds property were set to (#H5F_LIBVER_EARLIEST, * #H5F_LIBVER_LATEST). (Functionally, H5Pencode1() is identical to * H5Pencode2() with \a libver_bounds set to (#H5F_LIBVER_EARLIEST, * #H5F_LIBVER_LATEST).) * Properties that do not have encode callbacks will be skipped. * There is currently no mechanism to register an encode callback for * a user-defined property, so user-defined properties cannot currently * be encoded. * * Some properties cannot be encoded, particularly properties that are * reliant on local context. * * \note \a Motivation: * This function was introduced in HDF5-1.12 as part of the \a H5Sencode * format change to enable 64-bit selection encodings and a dataspace * selection that is tied to a file. * * \since 1.12.0 * */ H5_DLL herr_t H5Pencode2(hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_id); /** * \ingroup GPLOA * * \brief Compares two property lists or classes for equality * * \param[in] id1 First property object to be compared * \param[in] id2 Second property object to be compared * * \return \htri_t * * \details H5Pequal() compares two property lists or classes to determine * whether they are equal to one another. * * Either both \p id1 and \p id2 must be property lists or both * must be classes; comparing a list to a class is an error. * * \since 1.4.0 * */ H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2); /** * \ingroup GPLOA * * \brief Queries whether a property name exists in a property list or * class * * \param[in] plist_id Identifier for the property list or class to query * \param[in] name Name of property to check for * * \return \htri_t * * \details H5Pexist() determines whether a property exists within a * property list or class. * * \since 1.4.0 * */ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name); /** * \ingroup GPLOA * * \brief Queries the value of a property * * \plist_id * \param[in] name Name of property to query * \param[out] value Pointer to a location to which to copy the value of * the property * * \return \herr_t * * \details H5Pget() retrieves a copy of the value for a property in a * property list. If there is a \p get callback routine registered * for this property, the copy of the value of the property will * first be passed to that routine and any changes to the copy of * the value will be used when returning the property value from * this routine. * * This routine may be called for zero-sized properties with the * \p value set to NULL. The \p get routine will be called with * a NULL value if the callback exists. * * The property name must exist or this routine will fail. * * If the \p get callback routine returns an error, \ value will * not be modified. * * \since 1.4.0 * */ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void * value); /** *\ingroup GPLO * * \brief Returns the property list class identifier for a property list * * \plist_id * * \return \hid_t{property list class} * * \details H5Pget_class() returns the property list class identifier for * the property list identified by the \p plist_id parameter. * * Note that H5Pget_class() returns a value of #hid_t type, an * internal HDF5 identifier, rather than directly returning a * property list class. That identifier can then be used with * either H5Pequal() or H5Pget_class_name() to determine which * predefined HDF5 property list class H5Pget_class() has returned. * * A full list of valid predefined property list classes appears * in the description of H5Pcreate(). * * Determining the HDF5 property list class name with H5Pequal() * requires a series of H5Pequal() calls in an if-else sequence. * An iterative sequence of H5Pequal() calls can compare the * identifier returned by H5Pget_class() to members of the list of * valid property list class names. A pseudo-code snippet might * read as follows: * * \code * plist_class_id = H5Pget_class (dsetA_plist); * * if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = TRUE; * [ H5P_OBJECT_CREATE is the property list class ] * [ returned by H5Pget_class. ] * * else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = TRUE; * [ H5P_DATASET_CREATE is the property list class. ] * * else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = TRUE; * [ H5P_DATASET_XFER is the property list class. ] * * . * . [ Continuing the iteration until a match is found. ] * . * \endcode * * H5Pget_class_name() returns the property list class name directly * as a string: * * \code * plist_class_id = H5Pget_class (dsetA_plist); * plist_class_name = H5Pget_class_name (plist_class_id) * \endcode * * Note that frequent use of H5Pget_class_name() can become a * performance problem in a high-performance environment. The * H5Pequal() approach is generally much faster. * * \version 1.6.0 Return type changed in this release. * \since 1.0.0 * */ H5_DLL hid_t H5Pget_class(hid_t plist_id); /** * \ingroup GPLOA * * \brief Retrieves the name of a class * * \plistcls_id{pclass_id} * * \return Returns a pointer to an allocated string containing the class * name if successful, and NULL if not successful. * * \details H5Pget_class_name() retrieves the name of a generic property * list class. The pointer to the name must be freed by the user * with a call to H5free_memory() after each successful call. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Class Name (class identifier) ReturnedProperty List ClassExpanded Name of the Property List ClassThe Class Identifier Used with H5PcreateComments
attribute createacplAttribute Creation Property ListH5P_ATTRIBUTE_CREATE
dataset accessdaplDataset Access Property ListH5P_DATASET_ACCESS
dataset createdcplDataset Creation Property ListH5P_DATASET_CREATE
data transferdxplData Transfer Property ListH5P_DATASET_XFER
datatype access H5P_DATATYPE_ACCESSThis class can be created, but there are no properties * in the class currently. *
datatype create H5P_DATATYPE_CREATEThis class can be created, but there * are no properties in the class currently.
file accessfaplFile Access Property ListH5P_FILE_ACCESS
file createfcplFile Creation Property ListH5P_FILE_CREATE
file mountfmplFile Mount Property ListH5P_FILE_MOUNT
group access H5P_GROUP_ACCESSThis class can be created, but there * are no properties in the class currently.
group creategcplGroup Creation Property ListH5P_GROUP_CREATE
link accesslaplLink Access Property ListH5P_LINK_ACCESS
link createlcplLink Creation Property ListH5P_LINK_CREATE
object copyocpyplObject Copy Property ListH5P_OBJECT_COPY
object createocplObject Creation Property ListH5P_OBJECT_CREATE
string createstrcplString Creation Property ListH5P_STRING_CREATE
* * \since 1.4.0 * */ H5_DLL char *H5Pget_class_name(hid_t pclass_id); /** * \ingroup GPLOA * * \brief Retrieves the parent class of a property class * * \plistcls_id{pclass_id} * * \return \hid_t{parent class object} * * \details H5Pget_class_parent() retrieves an identifier for the parent * class of a property class. * * \since 1.4.0 * */ H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id); /** * \ingroup GPLOA * * \brief Queries the number of properties in a property list or class * * \param[in] id Identifier for property object to query * \param[out] nprops Number of properties in object * * \return \herr_t * * \details H5Pget_nprops() retrieves the number of properties in a * property list or property list class. * * If \p id is a property list identifier, the current number of * properties in the list is returned in \p nprops. * * If \p id is a property list class identifier, the number of * registered properties in the class is returned in \p nprops. * * \since 1.4.0 * */ H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops); /** * \ingroup GPLOA * * \brief Queries the size of a property value in bytes * * \param[in] id Identifier of property object to query * \param[in] name Name of property to query * \param[out] size Size of property in bytes * * \return \herr_t * * \details H5Pget_size() retrieves the size of a property's value in * bytes. This function operates on both property lists and * property classes. * * Zero-sized properties are allowed and return 0. * * \since 1.4.0 * */ H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size); /** * \ingroup GPLOA * * \brief Registers a temporary property with a property list * * \plist_id * \param[in] name Name of property to create * \param[in] size Size of property in bytes * \param[in] value Initial value for the property * \param[in] set Callback routine called before a new value is copied * into the property's value * \param[in] get Callback routine called when a property value is * retrieved from the property * \param[in] prp_del Callback routine called when a property is deleted * from a property list * \param[in] copy Callback routine called when a property is copied * from an existing property list * \param[in] compare Callback routine called when a property is compared * with another property list * \param[in] close Callback routine called when a property list is * being closed and the property value will be disposed * of * * \return \herr_t * * \details H5Pinsert2() creates a new property in a property * list. The property will exist only in this property list and * copies made from it. * * The initial property value must be provided in \p value and * the property value will be set accordingly. * * The name of the property must not already exist in this list, * or this routine will fail. * * The \p set and \p get callback routines may be set to NULL * if they are not needed. * * Zero-sized properties are allowed and do not store any data * in the property list. The default value of a zero-size * property may be set to NULL. They may be used to indicate the * presence or absence of a particular piece of information. * * The \p set routine is called before a new value is copied * into the property. The #H5P_prp_set_func_t callback function * is defined as follows: * \snippet this H5P_prp_cb2_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list being * modified
\Code{const char * name}IN: The name of the property being modified
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN: Pointer to new value pointer for the property * being modified
* * The \p set routine may modify the value pointer to be set and * those changes will be used when setting the property's value. * If the \p set routine returns a negative value, the new property * value is not copied into the property and the \p set routine * returns an error value. The \p set routine will be called for * the initial value. * * \b Note: The \p set callback function may be useful to range * check the value being set for the property or may perform some * transformation or translation of the value set. The \p get * callback would then reverse the transformation or translation. * A single \p get or \p set callback could handle multiple * properties by performing different actions based on the * property name or other properties in the property list. * * The \p get routine is called when a value is retrieved from * a property value. The #H5P_prp_get_func_t callback function * is defined as follows: * * \snippet this H5P_prp_cb2_t_snip * * The parameters to the above callback function are: * * * * * * * * * * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list being queried
\Code{const char * name}IN: The name of the property being queried
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN: The value of the property being returned
* * The \p get routine may modify the value to be returned from * the query and those changes will be preserved. If the \p get * routine returns a negative value, the query routine returns * an error value. * * The \p prp_del routine is called when a property is being * deleted from a property list. The #H5P_prp_delete_func_t * callback function is defined as follows: * * \snippet this H5P_prp_cb2_t_snip * * The parameters to the above callback function are: * * * * * * * * * * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list the property is * being deleted from
\Code{const char * name}IN: The name of the property in the list
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN: The value for the property being deleted
* * The \p prp_del routine may modify the value passed in, but the * value is not used by the library when the \p prp_del routine * returns. If the \p prp_del routine returns a negative value, * the property list \p prp_del routine returns an error value but * the property is still deleted. * * The \p copy routine is called when a new property list with * this property is being created through a \p copy operation. * * The #H5P_prp_copy_func_t callback function is defined as follows: * * \snippet this H5P_prp_cb1_t_snip * * The parameters to the above callback function are: * * * * * * * * * * * * * *
\Code{const char * name}IN: The name of the property being copied
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN/OUT: The value for the property being copied
* * The \p copy routine may modify the value to be set and those * changes will be stored as the new value of the property. If the * \p copy routine returns a negative value, the new property value * is not copied into the property and the copy routine returns an * error value. * * The \p compare routine is called when a property list with this * property is compared to another property list with the same * property. * * The #H5P_prp_compare_func_t callback function is defined as * follows: * * \snippet this H5P_prp_compare_func_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * *
\Code{const void * value1}IN: The value of the first property to compare
\Code{const void * value2}IN: The value of the second property to compare
\Code{size_t size}IN: The size of the property in bytes
* * The \p compare routine may not modify the values. The \p compare * routine should return a positive value if \p value1 is greater * than \p value2, a negative value if \p value2 is greater than * \p value1 and zero if \p value1 and \p value2 are equal. * * The \p close routine is called when a property list with this * property is being closed. * * The #H5P_prp_close_func_t callback function is defined as follows: * \snippet this H5P_prp_cb1_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * *
\Code{const char * name}IN: The name of the property in the list
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN: The value for the property being closed
* * The \p close routine may modify the value passed in, the * value is not used by the library when the close routine * returns. If the \p close routine returns a negative value, * the property list \p close routine returns an error value * but the property list is still closed. * * \b Note: There is no \p create callback routine for temporary * property list objects; the initial value is assumed to * have any necessary setup already performed on it. * * \todo "cpp_note" goes here * * \since 1.8.0 * */ H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close); /** * \ingroup GPLOA * * \brief Determines whether a property list is a member of a class * * \plist_id * \plistcls_id{pclass_id} * * \return \htri_t * * \details H5Pisa_class() checks to determine whether the property list * \p plist_id is a member of the property list class * \p pclass_id. * * \see H5Pcreate() * * \since 1.6.0 * */ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); /** * \ingroup GPLOA * * \brief Iterates over properties in a property class or list * * \param[in] id Identifier of property object to iterate over * \param[in,out] idx Index of the property to begin with * \param[in] iter_func Function pointer to function to be called * with each property iterated over * \param[in,out] iter_data Pointer to iteration data from user * * \return On success: the return value of the last call to \p iter_func if * it was non-zero; zero if all properties have been processed. * On Failure, a negative value * * \details H5Piterate() iterates over the properties in the property * object specified in \p id, which may be either a property * list or a property class, performing a specified operation * on each property in turn. * * For each property in the object, \p iter_func and the * additional information specified below are passed to the * #H5P_iterate_t operator function. * * The iteration begins with the \p idx-th property in the * object; the next element to be processed by the operator * is returned in \p idx. If \p idx is NULL, the iterator * starts at the first property; since no stopping point is * returned in this case, the iterator cannot be restarted if * one of the calls to its operator returns non-zero. * * 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 * 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: * * * * * * * * * * * * * * *
ZeroCauses the iterator to continue, returning zero when all * properties have been processed
PositiveCauses the iterator to immediately return that positive * value, indicating short-circuit success. The iterator * can be restarted at the index of the next property
NegativeCauses the iterator to immediately return that value, * indicating failure. The iterator can be restarted at the * index of the next property
* 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 * behavior is undefined. * * * \todo "cpp_note" goes here * * \since 1.4.0 * */ H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data); /** * \ingroup GPLOA * * \brief Registers a permanent property with a property list class * * \plistcls_id{cls_id} * \param[in] name Name of property to register * \param[in] size Size of property in bytes * \param[in] def_value Default value for property in newly created * property lists * \param[in] create Callback routine called when a property list is * being created and the property value will be * initialized * \param[in] set Callback routine called before a new value is * copied into the property's value * \param[in] get Callback routine called when a property value is * retrieved from the property * \param[in] prp_del Callback routine called when a property is deleted * from a property list * \param[in] copy Callback routine called when a property is copied * from a property list * \param[in] compare Callback routine called when a property is compared * with another property list * \param[in] close Callback routine called when a property list is * being closed and the property value will be * disposed of * * \return \herr_t * * \details H5Pregister2() registers a new property with a property list * class. The \p cls_id identifier can be obtained by calling * H5Pcreate_class(). The property will exist in all property * list objects of \p cl_id created after this routine finishes. The * name of the property must not already exist, or this routine * will fail. The default property value must be provided and all * new property lists created with this property will have the * property value set to the default value. Any of the callback * routines may be set to NULL if they are not needed. * * Zero-sized properties are allowed and do not store any data in * the property list. These may be used as flags to indicate the * presence or absence of a particular piece of information. The * default pointer for a zero-sized property may be set to NULL. * The property \p create and \p close callbacks are called for * zero-sized properties, but the \p set and \p get callbacks are * never called. * * The \p create routine is called when a new property list with * this property is being created. The #H5P_prp_create_func_t * callback function is defined as follows: * * \snippet this H5P_prp_cb1_t_snip * * The parameters to this callback function are defined as follows: * * * * * * * * * * * * * * *
\Code{const char * name}IN: The name of the property being modified
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN/OUT: The default value for the property being created, * which will be passed to H5Pregister2()
* * The \p create routine may modify the value to be set and those * changes will be stored as the initial value of the property. * If the \p create routine returns a negative value, the new * property value is not copied into the property and the * \p create routine returns an error value. * * The \p set routine is called before a new value is copied into * the property. The #H5P_prp_set_func_t callback function is defined * as follows: * * \snippet this H5P_prp_cb2_t_snip * * The parameters to this callback function are defined as follows: * * * * * * * * * * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list being modified
\Code{const char * name}IN: The name of the property being modified
\Code{size_t size}IN: The size of the property in bytes
\Code{void *value}IN/OUT: Pointer to new value pointer for the property * being modified
* * The \p set routine may modify the value pointer to be set and * those changes will be used when setting the property's value. * If the \p set routine returns a negative value, the new property * value is not copied into the property and the \p set routine * returns an error value. The \p set routine will not be called * for the initial value; only the \p create routine will be called. * * \b Note: The \p set callback function may be useful to range * check the value being set for the property or may perform some * transformation or translation of the value set. The \p get * callback would then reverse the transformation or translation. * A single \p get or \p set callback could handle multiple * properties by performing different actions based on the property * name or other properties in the property list. * * The \p get routine is called when a value is retrieved from a * property value. The #H5P_prp_get_func_t callback function is * defined as follows: * * \snippet this H5P_prp_cb2_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list being * queried
\Code{const char * name}IN: The name of the property being queried
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN/OUT: The value of the property being returned
* * The \p get routine may modify the value to be returned from the * query and those changes will be returned to the calling routine. * If the \p set routine returns a negative value, the query * routine returns an error value. * * The \p prp_del routine is called when a property is being * deleted from a property list. The #H5P_prp_delete_func_t * callback function is defined as follows: * * \snippet this H5P_prp_cb2_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list the property is * being deleted from
\Code{const char * name}IN: The name of the property in the list
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN: The value for the property being deleted
* * The \p prp_del routine may modify the value passed in, but the * value is not used by the library when the \p prp_del routine * returns. If the \p prp_del routine returns a negative value, * the property list delete routine returns an error value but * the property is still deleted. * * The \p copy routine is called when a new property list with * this property is being created through a \p copy operation. * The #H5P_prp_copy_func_t callback function is defined as follows: * * \snippet this H5P_prp_cb1_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * *
\Code{const char * name}IN: The name of the property being copied
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN/OUT: The value for the property being copied
* * The \p copy routine may modify the value to be set and those * changes will be stored as the new value of the property. If * the \p copy routine returns a negative value, the new * property value is not copied into the property and the \p copy * routine returns an error value. * * The \p compare routine is called when a property list with this * property is compared to another property list with the same * property. The #H5P_prp_compare_func_t callback function is * defined as follows: * * \snippet this H5P_prp_compare_func_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * *
\Code{const void * value1}IN: The value of the first property to compare
\Code{const void * value2}IN: The value of the second property to compare
\Code{size_t size}IN: The size of the property in bytes
* * The \p compare routine may not modify the values. The \p compare * routine should return a positive value if \p value1 is greater * than \p value2, a negative value if \p value2 is greater than * \p value1 and zero if \p value1 and \p value2 are equal. * * The \p close routine is called when a property list with this * property is being closed. The #H5P_prp_close_func_t callback * function is defined as follows: * * \snippet this H5P_prp_cb2_t_snip * * The parameters to the callback function are defined as follows: * * * * * * * * * * * * * * * * * * *
\ref hid_t \c prop_idIN: The identifier of the property list being closed
\Code{const char * name}IN: The name of the property in the list
\Code{size_t size}IN: The size of the property in bytes
\Code{void * value}IN: The value for the property being closed
* * The \p close routine may modify the value passed in, but the * value is not used by the library when the \p close routine returns. * 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. * * \todo "cpp_note" goes here * * \since 1.8.0 * */ H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t create, H5P_prp_set_func_t set, H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close); /** * \ingroup GPLOA * * \brief Removes a property from a property list * * \plist_id * \param[in] name Name of property to remove * * \return \herr_t * * \details H5Premove() removes a property from a property list. Both * properties which were in existence when the property list was * created (i.e. properties registered with H5Pregister()) and * properties added to the list after it was created (i.e. added * with H5Pinsert1() may be removed from a property list. * Properties do not need to be removed from a property list * before the list itself is closed; they will be released * automatically when H5Pclose() is called. * * If a \p close callback exists for the removed property, it * will be called before the property is released. * * \since 1.4.0 * */ H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); /** * \ingroup GPLOA * * \brief Sets a property list value * * \plist_id * \param[in] name Name of property to modify * \param[in] value Pointer to value to set the property to * * \return \herr_t * * \details H5Pset() sets a new value for a property in a property list. * If there is a \p set callback routine registered for this * property, the \p value will be passed to that routine and any * changes to the \p value will be used when setting the property * value. The information pointed to by the \p value pointer * (possibly modified by the \p set callback) is copied into the * property list value and may be changed by the application * making the H5Pset() call without affecting the property value. * * The property name must exist or this routine will fail. * * If the \p set callback routine returns an error, the property * value will not be modified. * * This routine may not be called for zero-sized properties and * will return an error in that case. * * \since 1.4.0 * */ H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, const void *value); /** * \ingroup GPLOA * * \brief Removes a property from a property list class * * \plistcls_id{pclass_id} * \param[in] name Name of property to remove * * \return \herr_t * * \details H5Punregister() removes a property from a property list class. * Future property lists created of that class will not contain * this property; existing property lists containing this property * are not affected. * * \since 1.4.0 * */ H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); /* Object creation property list (OCPL) routines */ /** * \ingroup OCPL * * \brief Verifies that all required filters are available * * \plist_id * * \return \htri_t * * \details H5Pall_filters_avail() verifies that all of the filters set in * the dataset or group creation property list \p plist_id are * currently available. * * \version 1.8.5 Function extended to work with group creation property * lists. * \since 1.6.0 * */ H5_DLL htri_t H5Pall_filters_avail(hid_t plist_id); /** * \ingroup OCPL * * \brief Retrieves tracking and indexing settings for attribute creation * order * * \plist_id * \param[out] crt_order_flags Flags specifying whether to track and * index attribute creation order * * \return \herr_t * * \details H5Pget_attr_creation_order() retrieves the settings for * tracking and indexing attribute creation order on an object. * * \p plist_id is an object creation property list (\p ocpl), * as it can be a dataset or group creation property list * identifier. The term \p ocpl is used when different types * of objects may be involved. * * \p crt_order_flags returns flags with the following meanings: * * * * * * * * * * *
#H5P_CRT_ORDER_TRACKEDAttribute creation order is tracked but not necessarily * indexed.
#H5P_CRT_ORDER_INDEXED Attribute creation order is indexed (requires * #H5P_CRT_ORDER_TRACKED).
* * If \p crt_order_flags is returned with a value of 0 (zero), * attribute creation order is neither tracked nor indexed. * * \since 1.8.0 * */ H5_DLL herr_t H5Pget_attr_creation_order(hid_t plist_id, unsigned *crt_order_flags); /** * \ingroup OCPL * * \brief Retrieves attribute storage phase change thresholds * * \plist_id * \param[out] max_compact Maximum number of attributes to be stored in * compact storage (Default: 8) * \param[out] min_dense Minimum number of attributes to be stored in * dense storage (Default: 6) * * \return \herr_t * * \details H5Pget_attr_phase_change() retrieves threshold values for * attribute storage on an object. These thresholds determine the * point at which attribute storage changes from compact storage * (i.e., storage in the object header) to dense storage (i.e., * storage in a heap and indexed with a B-tree). * * In the general case, attributes are initially kept in compact * storage. When the number of attributes exceeds \p max_compact, * attribute storage switches to dense storage. If the number of * attributes subsequently falls below \p min_dense, the * attributes are returned to compact storage. * * If \p max_compact is set to 0 (zero), dense storage always used. * * \p plist_id is an object creation property list (\p ocpl), as it * can be a dataset or group creation property list identifier. * The term \p ocpl is used when different types of objects may be * involved. * * \since 1.8.0 * */ H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, unsigned *min_dense); /** * \ingroup OCPL * * \brief Returns information about a filter in a pipeline * * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in * H5Ppublic.h * * \plist_id{plist_id} * \param[in] idx Sequence number within the filter pipeline of the filter * for which information is sought * \param[out] flags Bit vector specifying certain general properties of the * filter * \param[in,out] cd_nelmts Number of elements in \p cd_values * \param[out] cd_values Auxiliary data for the filter * \param[in] namelen Anticipated number of characters in \p name * \param[out] name Name of the filter * \param[out] filter_config Bit field, as described in H5Zget_filter_info() * * \return Returns a negative value on failure, and the filter identifier * if successful (see #H5Z_filter_t): * - #H5Z_FILTER_DEFLATE Data compression filter, * employing the gzip algorithm * - #H5Z_FILTER_SHUFFLE Data shuffling filter * - #H5Z_FILTER_FLETCHER32 Error detection filter, employing the * Fletcher32 checksum algorithm * - #H5Z_FILTER_SZIP Data compression filter, employing the * SZIP algorithm * - #H5Z_FILTER_NBIT Data compression filter, employing the * N-bit algorithm * - #H5Z_FILTER_SCALEOFFSET Data compression filter, employing the * scale-offset algorithm * * \details H5Pget_filter2() returns information about a filter specified by * its filter number, in a filter pipeline specified by the property * list with which it is associated. * * \p plist_id must be a dataset or group creation property list. * * \p idx is a value between zero and N-1, as described in * H5Pget_nfilters(). The function will return a negative value if * the filter number is out of range. * * The structure of the \p flags argument is discussed in * H5Pset_filter(). * * On input, \p cd_nelmts indicates the number of entries in the * \p cd_values array, as allocated by the caller; on return, * \p cd_nelmts contains the number of values defined by the filter. * * If \p name is a pointer to an array of at least \p namelen bytes, * the filter name will be copied into that array. The name will be * null terminated if \p namelen is large enough. The filter name * returned will be the name appearing in the file, the name * registered for the filter, or an empty string. * * \p filter_config is the bit field described in * H5Zget_filter_info(). * * \version 1.8.5 Function extended to work with group creation property * lists. * \since 1.8.0 * */ H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx, unsigned int *flags/*out*/, size_t *cd_nelmts/*out*/, unsigned cd_values[]/*out*/, size_t namelen, char name[], unsigned *filter_config /*out*/); /** * \ingroup OCPL * * \brief Returns information about the specified filter * * \plist_id * \param[in] filter_id Filter identifier * \param[out] flags Bit vector specifying certain general * properties of the filter * \param[in,out] cd_nelmts Number of elements in \p cd_values * \param[out] cd_values[] Auxiliary data for the filter * \param[in] namelen Length of filter name and number of * elements in \p name * \param[out] name[] Name of filter * \param[out] filter_config Bit field, as described in * H5Zget_filter_info() * * \return \herr_t * * \details H5Pget_filter_by_id2() returns information about the filter * specified in \p filter_id, a filter identifier. * * \p plist_id must be a dataset or group creation property list * and \p filter_id must be in the associated filter pipeline. * * The \p filter_id and \p flags parameters are used in the same * manner as described in the discussion of H5Pset_filter(). * * Aside from the fact that they are used for output, the * parameters \p cd_nelmts and \p cd_values[] are used in the same * manner as described in the discussion of H5Pset_filter(). On * input, the \p cd_nelmts parameter indicates the number of * entries in the \p cd_values[] array allocated by the calling * program; on exit it contains the number of values defined by * the filter. * * On input, the \p namelen parameter indicates the number of * characters allocated for the filter name by the calling program * in the array \p name[]. On exit \p name[] contains the name of the * filter with one character of the name in each element of the * array. * * \p filter_config is the bit field described in * H5Zget_filter_info(). * * If the filter specified in \p filter_id is not set for the * property list, an error will be returned and * H5Pget_filter_by_id2() will fail. * * \version 1.8.5 Function extended to work with group creation property * lists. * * \since 1.8.0 * */ H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t filter_id, unsigned int *flags/*out*/, size_t *cd_nelmts/*out*/, unsigned cd_values[]/*out*/, size_t namelen, char name[]/*out*/, unsigned *filter_config/*out*/); /** * \ingroup OCPL * * \brief Returns the number of filters in the pipeline * * \todo Signature for H5Pget_nfilters() is different in H5Pocpl.c than in * H5Ppublic.h. * * \plist_id * * \return Returns the number of filters in the pipeline if successful; * otherwise returns a negative value. * * \details H5Pget_nfilters() returns the number of filters defined in the * filter pipeline associated with the property list \p plist_id. * * In each pipeline, the filters are numbered from 0 through N-1, * where N is the value returned by this function. During output to * the file, the filters are applied in increasing order; during * input from the file, they are applied in decreasing order. * * H5Pget_nfilters() returns the number of filters in the pipeline, * including zero (0) if there are none. * * \since 1.0.0 * */ H5_DLL int H5Pget_nfilters(hid_t plist_id); /** * \ingroup OCPL * * \brief Determines whether times associated with an object * are being recorded * * \plist_id * \param[out] track_times Boolean value, 1 (TRUE) or 0 (FALSE), * specifying whether object times are being recorded * * \return \herr_t * * \details H5Pget_obj_track_times() queries the object creation property * list, \p plist_id, to determine whether object times are being * recorded. * * If \p track_times is returned as 1, times are being recorded; * if \p track_times is returned as 0, times are not being * recorded. * * Time data can be retrieved with H5Oget_info(), which will return * it in the #H5O_info_t struct. * * If times are not tracked, they will be reported as follows * when queried: 12:00 AM UDT, Jan. 1, 1970 * * See H5Pset_obj_track_times() for further discussion. * * \since 1.8.0 * */ H5_DLL herr_t H5Pget_obj_track_times(hid_t plist_id, hbool_t *track_times); /** * \ingroup OCPL * * \brief Modifies a filter in the filter pipeline * * \plist_id * \param[in] filter Filter to be modified * \param[in] flags Bit vector specifying certain general properties * of the filter * \param[in] cd_nelmts Number of elements in \p cd_values * \param[in] cd_values[] Auxiliary data for the filter * * \return \herr_t * * \details H5Pmodify_filter() modifies the specified \p filter in the * filter pipeline. \p plist_id must be a dataset or group * creation property list. * * The \p filter, \p flags \p cd_nelmts[], and \p cd_values * parameters are used in the same manner and accept the same * values as described in the discussion of H5Pset_filter(). * * \version 1.8.5 Function extended to work with group creation property * lists. * \since 1.6.0 * */ H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[/*cd_nelmts*/]); /** * \ingroup OCPL * * \brief Delete one or more filters in the filter pipeline * * \plist_id * \param[in] filter Filter to be deleted * * \return \herr_t * * \details H5Premove_filter() removes the specified \p filter from the * filter pipeline in the dataset or group creation property * list \p plist_id. * * The \p filter parameter specifies the filter to be removed. * Valid values for use in \p filter are as follows: * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
#H5Z_FILTER_ALLRemoves all filters from the filter pipeline
#H5Z_FILTER_DEFLATEData compression filter, employing the gzip * algorithm
#H5Z_FILTER_SHUFFLEData shuffling filter
#H5Z_FILTER_FLETCHER32Error detection filter, employing the Fletcher32 * checksum algorithm
#H5Z_FILTER_SZIPData compression filter, employing the SZIP * algorithm
#H5Z_FILTER_NBITData compression filter, employing the N-Bit * algorithm
#H5Z_FILTER_SCALEOFFSETData compression filter, employing the scale-offset * algorithm
* * Additionally, user-defined filters can be removed with this * routine by passing the filter identifier with which they were * registered with the HDF5 library. * * Attempting to remove a filter that is not in the filter * pipeline is an error. * * \version 1.8.5 Function extended to work with group creation property * lists. * \since 1.6.3 * */ H5_DLL herr_t H5Premove_filter(hid_t plist_id, H5Z_filter_t filter); /** * \ingroup OCPL * * \brief Sets tracking and indexing of attribute creation order * * \plist_id * \param[in] crt_order_flags Flags specifying whether to track and index * attribute creation order. \em Default: No * flag set; attribute creation order is neither * tracked not indexed * * \return \herr_t * * \details H5Pset_attr_creation_order() sets flags for tracking and * indexing attribute creation order on an object. * * \p plist_id is a dataset or group creation property list * identifier. * * \p crt_order_flags contains flags with the following meanings: * * * * * * * * * * *
#H5P_CRT_ORDER_TRACKEDAttribute creation order is tracked but not necessarily * indexed.
#H5P_CRT_ORDER_INDEXED Attribute creation order is indexed (requires * #H5P_CRT_ORDER_TRACKED).
* * Default behavior is that attribute creation order is neither * tracked nor indexed. * * H5Pset_attr_creation_order() can be used to set attribute * creation order tracking, or to set attribute creation order * tracking and indexing. * * \note If a creation order index is to be built, it must be specified in * the object creation property list. HDF5 currently provides no * mechanism to turn on attribute creation order tracking at object * creation time and to build the index later. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flags); /** * \ingroup OCPL * * \brief Sets attribute storage phase change thresholds * * \plist_id * \param[in] max_compact Maximum number of attributes to be stored in * compact storage (\em Default: 8); must be greater * than or equal to \p min_dense * * \param[in] min_dense Minimum number of attributes to be stored in * dense storage (\em Default: 6) * * \return \herr_t * * \details H5Pset_attr_phase_change() sets threshold values for attribute * storage on an object. These thresholds determine the point at * which attribute storage changes from compact storage (i.e., * storage in the object header) to dense storage (i.e., storage * in a heap and indexed with a B-tree). * * In the general case, attributes are initially kept in compact * storage. When the number of attributes exceeds \p max_compact, * attribute storage switches to dense storage. If the number of * attributes subsequently falls below \p min_dense, the attributes * are returned to compact storage. * * If \p max_compact is set to 0 (zero), dense storage is always * used. \p min_dense must be set to 0 (zero) when \p max_compact * is 0 (zero). * * \p plist_id is a dataset or group creation property list * identifier. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); /** * \ingroup OCPL * * \brief Sets deflate (GNU gzip) compression method and compression level * * \plist_id * \param[in] level Compression level * * \return \herr_t * * \details H5Pset_deflate() sets the deflate compression method and the * compression level, \p level, for a dataset or group creation * property list, \p plist_id. * * The filter identifier set in the property list is * #H5Z_FILTER_DEFLATE. * * The compression level, \p level, is a value from zero to nine, * inclusive. A compression level of 0 (zero) indicates no * compression; compression improves but speed slows progressively * from levels 1 through 9: * * * * * * * * * * * * * * * * * * * * * * *
Compression LevelGzip Action
0No compression
1Best compression speed; least compression
2 through 8Compression improves; speed degrades
9Best compression ratio; slowest speed
* * Note that setting the compression level to 0 (zero) does not turn * off use of the gzip filter; it simply sets the filter to perform * no compression as it processes the data. * * HDF5 relies on GNU gzip for this compression. * * \version 1.8.5 Function extended to work with group creation property lists. * \since 1.0.0 * */ H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level); /** * \ingroup OCPL * * \brief Adds a filter to the filter pipeline * * \param[in] plist_id Dataset or group creation property list identifier * \param[in] filter Filter identifier for the filter to be added to the * pipeline * \param[in] flags Bit vector specifying certain general properties of * the filter * \param[in] cd_nelmts Number of elements in \p c_values * \param[in] c_values Auxiliary data for the filter * * \return \herr_t * * \details H5Pset_filter() adds the specified \p filter identifier and * corresponding properties to the end of an output filter * pipeline. * * \p plist_id must be either a dataset creation property list or * group creation property list identifier. If \p plist_id is a * dataset creation property list identifier, the filter is added * to the raw data filter pipeline. * * If \p plist_id is a group creation property list identifier, * the filter is added to the link filter pipeline, which filters * the fractal heap used to store most of the link metadata in * certain types of groups. The only predefined filters that can * be set in a group creation property list are the gzip filter * (#H5Z_FILTER_DEFLATE) and the Fletcher32 error detection filter * (#H5Z_FILTER_FLETCHER32). * * The array \p c_values contains \p cd_nelmts integers which are * auxiliary data for the filter. The integer values will be * stored in the dataset object header as part of the filter * information. * * The \p flags argument is a bit vector with the following * fields specifying certain general properties of the filter: * * * * * * * * * * *
#H5Z_FLAG_OPTIONALIf this bit is set then the filter is optional. If the * filter fails (see below) during an H5Dwrite() operation * then the filter is just excluded from the pipeline for * the chunk for which it failed; the filter will not * participate in the pipeline during an H5Dread() of the * chunk. This is commonly used for compression filters: * if the filter result would be larger than the input, * then the compression filter returns failure and the * uncompressed data is stored in the file.

* This flag should not be set for the Fletcher32 checksum * filter as it will bypass the checksum filter without * reporting checksum errors to an application.
#H5Z_FLAG_MANDATORYIf the filter is required, that is, set to mandatory, * and the filter fails, the library’s behavior depends * on whether the chunk cache is in use: * \li If the chunk cache is enabled, data chunks will * be flushed to the file during H5Dclose() and the * library will return the failure in H5Dclose(). * \li When the chunk cache is disabled or not big enough, * or the chunk is being evicted from the cache, the * failure will happen during H5Dwrite(). * * In each case, the library will still write to the file * all data chunks that were processed by the filter * before the failure occurred.

* For example, assume that an application creates a * dataset of four chunks, the chunk cache is enabled and * is big enough to hold all four chunks, and the filter * fails when it tries to write the fourth chunk. The * actual flush of the chunks will happen during * H5Dclose(), not H5Dwrite(). By the time H5Dclose() * fails, the first three chunks will have been written * to the file. Even though H5Dclose() fails, all the * resources will be released and the file can be closed * properly.

* If, however, the filter fails on the second chunk, only * the first chunk will be written to the file as nothing * further can be written once the filter fails.
* The \p filter parameter specifies the filter to be set. Valid * pre-defined filter identifiers are as follows: * * * * * * * * * * * * * * * * * * * * * * * * * * *
#H5Z_FILTER_DEFLATEData compression filter, employing the gzip * algorithm
#H5Z_FILTER_SHUFFLEData shuffling filter
#H5Z_FILTER_FLETCHER32Error detection filter, employing the Fletcher32 * checksum algorithm
#H5Z_FILTER_SZIPData compression filter, employing the SZIP * algorithm
#H5Z_FILTER_NBITData compression filter, employing the N-Bit * algorithm
#H5Z_FILTER_SCALEOFFSETData compression filter, employing the scale-offset * algorithm
* Also see H5Pset_edc_check() and H5Pset_filter_callback(). * * \note When a non-empty filter pipeline is used with a group creation * property list, the group will be created with the new group file * format. The filters will come into play only when dense storage * is used (see H5Pset_link_phase_change()) and will be applied to * the group’s fractal heap. The fractal heap will contain most of * the the group’s link metadata, including link names. * * \note When working with group creation property lists, if you are * adding a filter that is not in HDF5’s set of predefined filters, * i.e., a user-defined or third-party filter, you must first * determine that the filter will work for a group. See the * discussion of the set local and can apply callback functions * in H5Zregister(). * * \note If multiple filters are set for a property list, they will be * applied to each chunk of raw data for datasets or each block * of the fractal heap for groups in the order in which they were * set. * * \note Filters can be applied only to chunked datasets; they cannot be * used with other dataset storage methods, such as contiguous, * compact, or external datasets. * * \note Dataset elements of variable-length and dataset region * reference datatypes are stored in separate structures in the * file called heaps. Filters cannot currently be applied to * these heaps. * * \note Filter Behavior in HDF5:
* Filters can be inserted into the HDF5 pipeline to perform * functions such as compression and conversion. As such, they are * a very flexible aspect of HDF5; for example, a user-defined * filter could provide encryption for an HDF5 dataset. * * \note A filter can be declared as either required or optional. * Required is the default status; optional status must be * explicitly declared. * * \note A required filter that fails or is not defined causes an * entire output operation to fail; if it was applied when the * data was written, such a filter will cause an input operation * to fail. * * \note The following table summarizes required filter behavior. * * * * * * * * * * * * * * * * * * * * * *
Required FILTER_X not availableFILTER_X available
H5Pset_Will fail.Will succeed.
H5Dwrite with FILTER_X setWill fail.Will succeed; FILTER_X will be applied to * the data.
H5Dread with FILTER_X setWill fail.Will succeed.
* \note An optional filter can be set for an HDF5 dataset even when * the filter is not available. Such a filter can then be * applied to the dataset when it becomes available on the * original system or when the file containing the dataset is * processed on a system on which it is available. * * \note A filter can be declared as optional through the use of the * #H5Z_FLAG_OPTIONAL flag with H5Pset_filter(). * * \note Consider a situation where one is creating files that will * normally be used only on systems where the optional (and * fictional) filter FILTER_Z is routinely available. One can * create those files on system A, which lacks FILTER_Z, create * chunked datasets in the files with FILTER_Z defined in the * dataset creation property list, and even write data to those * datasets. The dataset object header will indicate that FILTER_Z * has been associated with this dataset. But since system A does * not have FILTER_Z, dataset chunks will be written without it * being applied. * * \note HDF5 has a mechanism for determining whether chunks are * actually written with the filters specified in the object * header, so while the filter remains unavailable, system A will * be able to read the data. Once the file is moved to system B, * where FILTER_Z is available, HDF5 will apply FILTER_Z to any * data rewritten or new data written in these datasets. Dataset * chunks that have been written on system B will then be * unreadable on system A; chunks that have not been re-written * since being written on system A will remain readable on system * A. All chunks will be readable on system B. * * \note The following table summarizes optional filter behavior. * * * * * * * * * * * * * * * * * * * * * * * * * *
FILTER_Z not availableFILTER_Z available
with encode and decode		FILTER_Z available decode only
H5Pset_Will succeed.Will succeed.Will succeed.
H5Dread with FILTER_Z setWill succeed if FILTER_Z has not actually
* been applied to data.		Will succeed.Will succeed.
H5Dwrite with FILTER_Z setWill succeed;
* FILTER_Z will not be applied to the data.		Will succeed;
* FILTER_Z will be applied to the data.		Will succeed;
* FILTER_Z will not be applied to the data.
* \note The above principles apply generally in the use of HDF5 * optional filters insofar as HDF5 does as much as possible to * complete an operation when an optional filter is unavailable. * (The SZIP filter is an exception to this rule; see H5Pset_szip() * for details.) * * \todo Removed several references to links to documentation * * \version 1.8.5 Function applied to group creation property lists. * \since 1.6.0 * */ H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int flags, size_t cd_nelmts, const unsigned int c_values[]); /** * \ingroup OCPL * * \brief Sets up use of the Fletcher32 checksum filter * * \param[in] plist_id Dataset or group creation property list identifier * * \return \herr_t * * \details H5Pset_fletcher32() sets the Fletcher32 checksum filter in the * dataset or group creation property list \p plist_id. * * \attention The Fletcher32 EDC checksum filter was added in HDF5 Release * 1.6.0. In the original implementation, however, the checksum * value was calculated incorrectly on little-endian systems. * The error was fixed in HDF5 Release 1.6.3. * * \attention As a result of this fix, an HDF5 library of Release 1.6.0 * through Release 1.6.2 cannot read a dataset created or written * with Release 1.6.3 or later if the dataset was created with * the checksum filter and the filter is enabled in the reading * library. (Libraries of Release 1.6.3 and later understand the * earlier error and compensate appropriately.) * * \attention \b Work-around: An HDF5 library of Release 1.6.2 or earlier * will be able to read a dataset created or written with the * checksum filter by an HDF5 library of Release 1.6.3 or later * if the checksum filter is disabled for the read operation. * This can be accomplished via a call to H5Pset_edc_check() * with the value #H5Z_DISABLE_EDC in the second parameter. * This has the obvious drawback that the application will be * unable to verify the checksum, but the data does remain * accessible. * * \version 1.8.5 Function extended to work with group creation property * lists. * \version 1.6.3 Error in checksum calculation on little-endian systems * corrected in this release. * \since 1.6.0 * */ H5_DLL herr_t H5Pset_fletcher32(hid_t plist_id); /** * \ingroup OCPL * * \brief Sets the recording of times associated with an object * * \param[in] plist_id Object creation property list identifier * \param[in] track_times Boolean value, 1 or 0, specifying whether object * times are to be tracked * * \return \herr_t * * \details H5Pset_obj_track_times() sets a property in the object creation * property list, \p plist_id, that governs the recording of times * associated with an object. * * If \p track_times is set to 1, time data will be recorded. If * \p track_times is set to 0, time data will not be recorded. * * Time data can be retrieved with H5Oget_info(), which will * return it in the #H5O_info_t struct. * * If times are not tracked, they will be reported as follows when queried: * \Code{ 12:00 AM UDT, Jan. 1, 1970} * * That date and time are commonly used to represent the beginning of the UNIX epoch. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_obj_track_times(hid_t plist_id, hbool_t track_times); /* File creation property list (FCPL) routines */ /** * \ingroup FCPL * * \brief Retrieves the file space page size for a file creation property * list * * \fcpl_id{plist_id} * \param[out] fsp_size File space page size * * \return \herr_t * * \details H5Pget_file_space_page_size() retrieves the file space page * size for paged aggregation in the parameter \p fsp_size. * * The library default is 4KB (4096) if \p fsp_size is not * previously set via a call to H5Pset_file_space_page_size(). * * \since 1.10.1 * */ H5_DLL herr_t H5Pget_file_space_page_size(hid_t plist_id, hsize_t *fsp_size); /** * \ingroup FCPL * * \brief Retrieves the file space handling strategy, persisting free-space * condition and threshold value for a file creation property list * * \fcpl_id{plist_id} * \param[out] strategy The file space handling strategy * \param[out] persist The boolean value indicating whether free space is * persistent or not * \param[out] threshold The free-space section size threshold value * * \return \herr_t * * \details H5Pget_file_space_strategy() retrieves the file space handling * strategy, the persisting free-space condition and the threshold * value in the parameters \p strategy, \p persist and * \p threshold respectively. * * The library default values returned when * H5Pset_file_space_strategy() has not been called are: * * \li \p strategy - #H5F_FSPACE_STRATEGY_FSM_AGGR * \li \p persist - 0 * \li \p threshold - 1 * * \since 1.10.1 * */ H5_DLL herr_t H5Pget_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t *strategy, hbool_t *persist, hsize_t *threshold); /** * \ingroup FCPL * * \brief Queries the 1/2 rank of an indexed storage B-tree * * \fcpl_id{plist_id} * \param[out] ik Pointer to location to return the chunked storage B-tree * 1/2 rank (Default value of B-tree 1/2 rank: 32) * * \return \herr_t * * \details H5Pget_istore_k() queries the 1/2 rank of an indexed storage * B-tree. * * The argument \p ik may be the null pointer (NULL). * This function is valid only for file creation property lists. * * \see H5Pset_istore_k() * * \version 1.6.4 \p ik parameter type changed to \em unsigned. * \since 1.0.0 * */ H5_DLL herr_t H5Pget_istore_k(hid_t plist_id, unsigned *ik/*out*/); /** * \ingroup FCPL * * \brief Retrieves the configuration settings for a shared message index * * \fcpl_id{plist_id} * \param[in] index_num Index being configured * \param[out] mesg_type_flags Types of messages that may be stored in * this index * \param[out] min_mesg_size Minimum message size * * \return \herr_t * * \details H5Pget_shared_mesg_index() retrieves the message type and * minimum message size settings from the file creation property * list \p plist_id for the shared object header message index * specified by \p index_num. * * \p index_num specifies the index. \p index_num is zero-indexed, * so in a file with three indexes, they will be numbered 0, 1, * and 2. * * \p mesg_type_flags and \p min_mesg_size will contain, * respectively, the types of messages and the minimum size, in * bytes, of messages that can be stored in this index. * * Valid message types are described in H5Pset_shared_mesg_index(). * * \since 1.8.0 * */ H5_DLL herr_t H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned *mesg_type_flags, unsigned *min_mesg_size); /** * \ingroup FCPL * * \brief Retrieves number of shared object header message indexes in file * creation property list * * \fcpl_id{plist_id} * \param[out] nindexes Number of shared object header message indexes * available in files created with this property list * * \return \herr_t * * \details H5Pget_shared_mesg_nindexes() retrieves the number of shared * object header message indexes in the specified file creation * property list \p plist_id. * * If the value of \p nindexes is 0 (zero), shared object header * messages are disabled in files created with this property list. * * \since 1.8.0 * */ H5_DLL herr_t H5Pget_shared_mesg_nindexes(hid_t plist_id, unsigned *nindexes); /** * \ingroup FCPL * * \brief Retrieves shared object header message phase change information * * \fcpl_id{plist_id} * \param[out] max_list Threshold above which storage of a shared object * header message index shifts from list to B-tree * \param[out] min_btree Threshold below which storage of a shared object * header message index reverts to list format * * \return \herr_t * * \details H5Pget_shared_mesg_phase_change() retrieves the threshold values * for storage of shared object header message indexes in a file. * These phase change thresholds determine the point at which the * index storage mechanism changes from a more compact list format * to a more performance-oriented B-tree format, and vice-versa. * * By default, a shared object header message index is initially * stored as a compact list. When the number of messages in an * index exceeds the specified \p max_list threshold, storage * switches to a B-tree format for improved performance. If the * number of messages subsequently falls below the \p min_btree * threshold, the index will revert to the list format. * * If \p max_list is set to 0 (zero), shared object header message * indexes in the file will always be stored as B-trees. * * \p plist_id specifies the file creation property list. * * \since 1.8.0 * */ H5_DLL herr_t H5Pget_shared_mesg_phase_change(hid_t plist_id, unsigned *max_list, unsigned *min_btree); /** * \ingroup FCPL * * \brief Retrieves the size of the offsets and lengths used in an HDF5 * file * * \fcpl_id{plist_id} * \param[out] sizeof_addr Pointer to location to return offset size in * bytes * \param[out] sizeof_size Pointer to location to return length size in * bytes * * \return \herr_t * * \details H5Pget_sizes() retrieves the size of the offsets and lengths * used in an HDF5 file. This function is only valid for file * creation property lists. * * \since 1.0.0 * */ H5_DLL herr_t H5Pget_sizes(hid_t plist_id, size_t *sizeof_addr/*out*/, size_t *sizeof_size/*out*/); /** * \ingroup FCPL * * \brief Retrieves the size of the symbol table B-tree 1/2 rank and the * symbol table leaf node 1/2 size * * \fcpl_id{plist_id} * \param[out] ik Pointer to location to return the symbol table's B-tree * 1/2 rank (Default value of B-tree 1/2 rank: 16) * \param[out] lk Pointer to location to return the symbol table's leaf * node 1/2 size (Default value of leaf node 1/2 * size: 4) * * \return \herr_t * * \details H5Pget_sym_k() retrieves the size of the symbol table B-tree * 1/2 rank and the symbol table leaf node 1/2 size. * * This function is valid only for file creation property lists. * * If a parameter value is set to NULL, that parameter is not * retrieved. * * \see H5Pset_sym_k() * * \version 1.6.4 \p ik parameter type changed to \em unsigned * \version 1.6.0 The \p ik parameter has changed from type int to * \em unsigned * * \since 1.0.0 * */ H5_DLL herr_t H5Pget_sym_k(hid_t plist_id, unsigned *ik/*out*/, unsigned *lk/*out*/); /** * \ingroup FCPL * * \brief Retrieves the size of a user block * * \fcpl_id{plist_id} * \param[out] size Pointer to location to return user-block size * * \return \herr_t * * \details H5Pget_userblock() retrieves the size of a user block in a * file creation property list. * * \since 1.0.0 * */ H5_DLL herr_t H5Pget_userblock(hid_t plist_id, hsize_t *size); /** * \ingroup FCPL * * \brief Sets the file space page size for a file creation property list * * \fcpl_id{plist_id} * \param[in] fsp_size File space page size * * \return \herr_t * * \details H5Pset_file_space_page_size() sets the file space page size * \p fsp_size used in paged aggregation and paged buffering. * * \p fsp_size has a minimum size of 512. Setting a value less * than 512 will return an error. The library default size for * the file space page size when not set is 4096. * * The size set via this routine may not be changed for the life * of the file. * * \since 1.10.1 * */ H5_DLL herr_t H5Pset_file_space_page_size(hid_t plist_id, hsize_t fsp_size); /** * \ingroup FCPL * * \brief Sets the file space handling strategy and persisting free-space * values for a file creation property list * * \fcpl_id{plist_id} * \param[in] strategy The file space handling strategy to be used. See: * #H5F_fspace_strategy_t * \param[in] persist A boolean value to indicate whether free space * should be persistent or not * \param[in] threshold The smallest free-space section size that the free * space manager will track * * \return \herr_t * * \details H5Pset_file_space_strategy() sets the file space handling * \p strategy, specifies persisting free-space or not (\p persist), * and sets the free-space section size \p threshold in the file * creation property list \p plist_id. * * #H5F_fspace_strategy_t is a struct defined in H5Fpublic.h as * follows: * * \snippet H5Fpublic.h H5F_fspace_strategy_t_snip * * This setting cannot be changed for the life of the file. * * As the #H5F_FSPACE_STRATEGY_AGGR and #H5F_FSPACE_STRATEGY_NONE * strategies do not use the free-space managers, the \p persist * and \p threshold settings will be ignored for those strategies. * * \since 1.10.1 * */ H5_DLL herr_t H5Pset_file_space_strategy(hid_t plist_id, H5F_fspace_strategy_t strategy, hbool_t persist, hsize_t threshold); /** * \ingroup FCPL * * \brief Sets the size of the parameter used to control the B-trees for * indexing chunked datasets * * \fcpl_id{plist_id} * \param[in] ik 1/2 rank of chunked storage B-tree * * \return \herr_t * * \details H5Pset_istore_k() sets the size of the parameter used to * control the B-trees for indexing chunked datasets. This * function is valid only for file creation property lists. * * \p ik is one half the rank of a tree that stores chunked * raw data. On average, such a tree will be 75% full, or have * an average rank of 1.5 times the value of \p ik. * * The HDF5 library uses (\p ik*2) as the maximum # of entries * before splitting a B-tree node. Since only 2 bytes are used * in storing # of entries for a B-tree node in an HDF5 file, * (\p ik*2) cannot exceed 65536. The default value for * \p ik is 32. * * \version 1.6.4 \p ik parameter type changed to \p unsigned. * \since 1.0.0 * */ H5_DLL herr_t H5Pset_istore_k(hid_t plist_id, unsigned ik); /** * \ingroup FCPL * * \brief Configures the specified shared object header message index * * \fcpl_id{plist_id} * \param[in] index_num Index being configured * \param[in] mesg_type_flags Types of messages that should be stored in * this index * \param[in] min_mesg_size Minimum message size * * \return \herr_t * * \details H5Pset_shared_mesg_index() is used to configure the specified * shared object header message index, setting the types of * messages that may be stored in the index and the minimum size * of each message. * * \p plist_id specifies the file creation property list. * * \p index_num specifies the index to be configured. * \p index_num is zero-indexed, so in a file with three indexes, * they will be numbered 0, 1, and 2. * * \p mesg_type_flags and \p min_mesg_size specify, respectively, * the types and minimum size of messages that can be stored in * this index. * * Valid message types are as follows: * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
#H5O_SHMESG_NONE_FLAGNo shared messages
#H5O_SHMESG_SDSPACE_FLAGSimple dataspace message
#H5O_SHMESG_DTYPE_FLAGDatatype message
#H5O_SHMESG_FILL_FLAGFill value message
#H5O_SHMESG_PLINE_FLAGFilter pipeline message
#H5O_SHMESG_ATTR_FLAGAttribute message
#H5O_SHMESG_ALL_FLAGAll message types; i.e., equivalent to the following: * (#H5O_SHMESG_SDSPACE_FLAG | #H5O_SHMESG_DTYPE_FLAG | * #H5O_SHMESG_FILL_FLAG | #H5O_SHMESG_PLINE_FLAG | * #H5O_SHMESG_ATTR_FLAG)
* * \since 1.8.0 * */ H5_DLL herr_t H5Pset_shared_mesg_index(hid_t plist_id, unsigned index_num, unsigned mesg_type_flags, unsigned min_mesg_size); /** * \ingroup FCPL * * \brief Sets number of shared object header message indexes * * \fcpl_id{plist_id} * \param[in] nindexes Number of shared object header message indexes to be * available in files created with this property list * (\p nindexes must be <= #H5O_SHMESG_MAX_NINDEXES (8)) * * \return \herr_t * * \details H5Pset_shared_mesg_nindexes() sets the number of shared object * header message indexes in the specified file creation property * list. * * This setting determines the number of shared object header * message indexes, \p nindexes, that will be available in files * created with this property list. These indexes can then be * configured with H5Pset_shared_mesg_index(). * * If \p nindexes is set to 0 (zero), shared object header messages * are disabled in files created with this property list. * * There is a limit of #H5O_SHMESG_MAX_NINDEXES (8) that can be set * with H5Pset_shared_mesg_nindexes(). An error will occur if * specifying a value of \p nindexes that is greater than this value. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_shared_mesg_nindexes(hid_t plist_id, unsigned nindexes); /** * \ingroup FCPL * * \brief Sets shared object header message storage phase change thresholds * * \fcpl_id{plist_id} * \param[in] max_list Threshold above which storage of a shared object * header message index shifts from list to B-tree * \param[in] min_btree Threshold below which storage of a shared object * header message index reverts to list format * * \return \herr_t * * \details H5Pset_shared_mesg_phase_change() sets threshold values for * storage of shared object header message indexes in a file. * These phase change thresholds determine the point at which the * index storage mechanism changes from a more compact list format * to a more performance-oriented B-tree format, and vice-versa. * * By default, a shared object header message index is initially * stored as a compact list. When the number of messages in an * index exceeds the threshold value of \p max_list, storage * switches to a B-tree for improved performance. If the number * of messages subsequently falls below the \p min_btree threshold, * the index will revert to the list format. * * If \p max_list is set to 0 (zero), shared object header message * indexes in the file will be created as B-trees and will never * revert to lists. * * \p plist_id specifies the file creation property list. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_shared_mesg_phase_change(hid_t plist_id, unsigned max_list, unsigned min_btree); /** * \ingroup FCPL * * \brief Sets the byte size of the offsets and lengths used to address * objects in an HDF5 file * * \fcpl_id{plist_id} * \param[in] sizeof_addr Size of an object offset in bytes * \param[in] sizeof_size Size of an object length in bytes * * \return \herr_t * * \details H5Pset_sizes() sets the byte size of the offsets and lengths * used to address objects in an HDF5 file. This function is only * valid for file creation property lists. Passing in a value * of 0 for one of the parameters retains the current value. The * default value for both values is the same as sizeof(hsize_t) * in the library (normally 8 bytes). Valid values currently * are 2, 4, 8 and 16. * * \since 1.0.0 * */ H5_DLL herr_t H5Pset_sizes(hid_t plist_id, size_t sizeof_addr, size_t sizeof_size); /** * \ingroup FCPL * * \brief * * \fcpl_id{plist_id} * \param[in] ik Symbol table tree rank * \param[in] lk Symbol table node size * * \return \herr_t * * \details H5Pset_sym_k() sets the size of parameters used to control the * symbol table nodes. * * This function is valid only for file creation property lists. * Passing in a value of zero (0) for one of the parameters retains * the current value. * * \p ik is one half the rank of a B-tree that stores a symbol * table for a group. Internal nodes of the symbol table are on * average 75% full. That is, the average rank of the tree is * 1.5 times the value of \p ik. The HDF5 library uses (\p ik*2) as * the maximum # of entries before splitting a B-tree node. Since * only 2 bytes are used in storing # of entries for a B-tree node * in an HDF5 file, (\p ik*2) cannot exceed 65536. The default value * for \p ik is 16. * * \p lk is one half of the number of symbols that can be stored in * a symbol table node. A symbol table node is the leaf of a symbol * table tree which is used to store a group. When symbols are * inserted randomly into a group, the group's symbol table nodes are * 75% full on average. That is, they contain 1.5 times the number of * symbols specified by \p lk. The default value for \p lk is 4. * * \version 1.6.4 \p ik parameter type changed to \em unsigned. * \version 1.6.0 The \p ik parameter has changed from type int to * \em unsigned. * * \since 1.0.0 * */ H5_DLL herr_t H5Pset_sym_k(hid_t plist_id, unsigned ik, unsigned lk); /** * \ingroup FCPL * * \brief Sets user block size * * \fcpl_id{plist_id} * \param[in] size Size of the user-block in bytes * * \return \herr_t * * \details H5Pset_userblock() sets the user block size of a file creation * property list. The default user block size is 0; it may be set * to any power of 2 equal to 512 or greater (512, 1024, 2048, etc.). * * \since 1.0.0 * */ H5_DLL herr_t H5Pset_userblock(hid_t plist_id, hsize_t size); /* File access property list (FAPL) routines */ /** * \ingroup FAPL * * \brief Retrieves the current settings for alignment properties from a * file access property list * * \fapl_id * \param[out] threshold Pointer to location of return threshold value * \param[out] alignment Pointer to location of return alignment value * * \return \herr_t * * \details H5Pget_alignment() retrieves the current settings for * alignment properties from a file access property list. The * \p threshold and/or \p alignment pointers may be null * pointers (NULL). * * \since 1.0.0 * */ H5_DLL herr_t H5Pget_alignment(hid_t fapl_id, hsize_t *threshold/*out*/, hsize_t *alignment/*out*/); /** * \ingroup FAPL * * \brief Queries the raw data chunk cache parameters * * \fapl_id{plist_id} * \param[in,out] mdc_nelmts No longer used * \param[in,out] rdcc_nslots Number of elements (objects) in the raw data * chunk cache * \param[in,out] rdcc_nbytes Total size of the raw data chunk cache, in * bytes * \param[in,out] rdcc_w0 Preemption policy * * \return \herr_t * * \details H5Pget_cache() retrieves the maximum possible number of * elements in the raw data chunk cache, the maximum possible * number of bytes in the raw data chunk cache, and the * preemption policy value. * * Any (or all) arguments may be null pointers, in which case * the corresponding datum is not returned. * * Note that the \p mdc_nelmts parameter is no longer used. * * \version 1.8.0 Use of the \p mdc_nelmts parameter discontinued. * Metadata cache configuration is managed with * H5Pset_mdc_config() and H5Pget_mdc_config() * \version 1.6.0 The \p rdcc_nbytes and \p rdcc_nslots parameters changed * from type int to size_t. * * \since 1.0.0 * */ H5_DLL herr_t H5Pget_cache(hid_t plist_id, int *mdc_nelmts, /* out */ size_t *rdcc_nslots/*out*/, size_t *rdcc_nbytes/*out*/, double *rdcc_w0); /** * \ingroup FAPL * * \brief Gets information about the write tracking feature used by * the core VFD * * \fapl_id * \param[out] is_enabled Whether the feature is enabled * \param[out] page_size Size, in bytes, of write aggregation pages * * \return \herr_t * * \details H5Pget_core_write_tracking() retrieves information about the * write tracking feature used by the core VFD. * * When a file is created or opened for writing using the core * virtual file driver (VFD) with the backing store option turned * on, the VFD can be configured to track changes to the file * and only write out the modified bytes. To avoid a large number * of small writes, the changes can be aggregated into pages of * a user-specified size. The core VFD is also known as the * memory VFD. The driver identifier is #H5FD_CORE. * * \note This function is only for use with the core VFD and must be used * after the call to H5Pset_fapl_core(). It is an error to use this * function with any other VFD. * * \note This function only applies to the backing store write operation * which typically occurs when the file is flushed or closed. This * function has no relationship to the increment parameter passed * to H5Pset_fapl_core(). * * \note For optimum performance, the \p page_size parameter should be * a power of two. * * \since 1.8.13 * */ H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, size_t *page_size); /** * \ingroup FAPL * * \brief Returns low-lever driver identifier * * \plist_id * * \return \hid_t{low level driver} * * \details H5Pget_driver() returns the identifier of the low-level file * driver associated with the file access property list or * data transfer property list \p plist_id. * * Valid driver identifiers distributed with HDF5 are listed and * described in the following table. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Driver NameDriver IdentifierDescriptionRelated Function
POSIX#H5FD_SEC2This driver uses POSIX file-system functions like read and * write to perform I/O to a single, permanent file on local disk * with no system buffering. This driver is POSIX-compliant and is * the default file driver for all systems.H5Pset_fapl_sec2()
Direct#H5FD_DIRECTThis is the #H5FD_SEC2 driver except data is written to or * read from the file synchronously without being cached by the * system.H5Pset_fapl_direct()
Log#H5FD_LOGThis is the #H5FD_SEC2 driver with logging capabilities.H5Pset_fapl_log()
Windows#H5FD_WINDOWSThis driver was modified in HDF5-1.8.8 to be a wrapper of the * POSIX driver, #H5FD_SEC2. This change should not affect user * applications.H5Pset_fapl_windows()
STDIO#H5FD_STDIOThis driver uses functions from the standard C stdio.h to * perform I/O to a single, permanent file on local disk with * additional system buffering.H5Pset_fapl_stdio()
Memory#H5FD_COREWith this driver, an application can work with a file in * memory for faster reads and writes. File contents are kept in * memory until the file is closed. At closing, the memory version * of the file can be written back to disk or abandoned.H5Pset_fapl_core()
Family#H5FD_FAMILYWith this driver, the HDF5 file’s address space is partitioned * into pieces and sent to separate storage files using an * underlying driver of the user’s choice. This driver is for * systems that do not support files larger than 2 gigabytes.H5Pset_fapl_family()
Multi#H5FD_MULTIWith this driver, data can be stored in multiple files * according to the type of the data. I/O might work better if * data is stored in separate files based on the type of data. * The Split driver is a special case of this driver.H5Pset_fapl_multi()
Parallel#H5FD_MPIOThis is the standard HDF5 file driver for parallel file * systems. This driver uses the MPI standard for both * communication and file I/O.H5Pset_fapl_mpio()
Parallel POSIXH5FD_MPIPOSIXThis driver is no longer available.
StreamH5FD_STREAMThis driver is no longer available.
* * This list does not include custom drivers that might be * defined and registered by a user. * * The returned driver identifier is only valid as long as the * file driver remains registered. * * * \since 1.4.0 * */ H5_DLL hid_t H5Pget_driver(hid_t plist_id); /** * \ingroup FAPL * * \brief Returns a pointer to file driver information * * \param[in] plist_id File access or data transfer property list * identifier * * \return Returns a pointer to a struct containing low-level driver * information. Otherwise returns NULL. NULL is also returned if * no driver-specific properties have been registered. No error * is pushed on the stack in this case. * * \details H5Pget_driver_info() returns a pointer to file driver-specific * information for the low-level driver associated with the file * access or data transfer property list \p plist_id. * * The pointer returned by this function points to an “uncopied” * struct. Driver-specific versions of that struct are defined * for each low-level driver in the relevant source code file * H5FD*.c. For example, the struct used for the MULTI driver is * #H5FD_multi_fapl_t defined in H5FDmulti.c. * * If no driver-specific properties have been registered, * H5Pget_driver_info() returns NULL. * * \note H5Pget_driver_info() and H5Pset_driver() are used only when * creating a virtual file driver (VFD) in the virtual file * layer (VFL). * * \version 1.10.1 Return value was changed from \em void * to * \em const \em void *. * \version 1.8.2 Function publicized in this release; previous releases * described this function only in the virtual file driver * documentation. * */ H5_DLL const void *H5Pget_driver_info(hid_t plist_id); H5_DLL herr_t H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size); H5_DLL herr_t H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close); /** * \ingroup FAPL * * \brief Retrieves a data offset from the file access property list * * \fapl_id * \param[out] offset Offset in bytes within the HDF5 file * * \return \herr_t * * \details H5Pget_family_offset() retrieves the value of offset from the * file access property list \p fapl_id so that the user * application can retrieve a file handle for low-level access to * a particular member of a family of files. The file handle is * retrieved with a separate call to H5Fget_vfd_handle() (or, * in special circumstances, to H5FDget_vfd_handle()). * * \todo References the VFL documentation. * * \since 1.6.0 * */ H5_DLL herr_t H5Pget_family_offset(hid_t fapl_id, hsize_t *offset); /** * \ingroup FAPL * * \brief Returns the file close degree * * \fapl_id * \param[out] degree Pointer to a location to which to return the file * close degree property, the value of \p degree * * \return \herr_t * * \details H5Pget_fclose_degree() returns the current setting of the file * close degree property \p degree in the file access property * list \p fapl_id. The value of \p degree determines how * aggressively H5Fclose() deals with objects within a file that * remain open when H5Fclose() is called to close that file. * * \since 1.6.0 * */ H5_DLL herr_t H5Pget_fclose_degree(hid_t fapl_id, H5F_close_degree_t *degree); H5_DLL herr_t H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr); H5_DLL herr_t H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr); H5_DLL herr_t H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled); /** * \ingroup FAPL * * \brief Returns garbage collecting references setting * * \fapl_id * \param[out] gc_ref Flag returning the state of reference garbage * collection. A returned value of 1 indicates that * garbage collection is on while 0 indicates that * garbage collection is off. * * \return \herr_t * * \details H5Pget_gc_references() returns the current setting for the * garbage collection references property from the specified * file access property list. The garbage collection references * property is set by H5Pset_gc_references(). * * \since 1.2.0 * */ H5_DLL herr_t H5Pget_gc_references(hid_t fapl_id, unsigned *gc_ref/*out*/); /** * \ingroup FAPL * * \brief Retrieves library version bounds settings that indirectly control * the format versions used when creating objects * * \fapl_id{plist_id} * \param[out] low The earliest version of the library that will be used * for writing objects * \param[out] high The latest version of the library that will be used for * writing objects * * \return \herr_t * * \details H5Pget_libver_bounds() retrieves the lower and upper bounds on * the HDF5 library release versions that indirectly determine the * object format versions used when creating objects in the file. * * This property is retrieved from the file access property list * specified by the parameter \p fapl_id. * * The value returned in the parameters \p low and \p high is one * of the enumerated values in the #H5F_libver_t struct, which is * defined in H5Fpublic.h. * * \version 1.10.2 Add #H5F_LIBVER_V18 to the enumerated defines in * #H5F_libver_t * \since 1.8.0 * */ H5_DLL herr_t H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low, H5F_libver_t *high); H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t * config_ptr); /* out */ H5_DLL herr_t H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr /*out*/); H5_DLL herr_t H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled, char *location, size_t *location_size, hbool_t *start_on_access); H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size/*out*/); H5_DLL herr_t H5Pget_metadata_read_attempts(hid_t plist_id, unsigned *attempts); /** * \ingroup FAPL * * \brief Retrieves type of data property for MULTI driver * * \param[in] fapl_id File access property list or data transfer property * list identifier * \param[out] type Type of data * * \return \herr_t * * \details H5Pget_multi_type() retrieves the type of data setting from * the file access or data transfer property list \p fapl_id. * This enables a user application to specify the type of data * the application wishes to access so that the application can * retrieve a file handle for low-level access to the particular * member of a set of MULTI files in which that type of data is * stored. The file handle is retrieved with a separate call to * H5Fget_vfd_handle() (or, in special circumstances, to * H5FDget_vfd_handle(); see the Virtual File Layer documentation * for more information. * * The type of data returned in \p type will be one of those * listed in the discussion of the \p type parameter in the the * description of the function H5Pset_multi_type(). * * Use of this function is only appropriate for an HDF5 file * written as a set of files with the MULTI file driver. * * \since 1.6.0 * */ H5_DLL herr_t H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type); H5_DLL herr_t H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func, void **udata); H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned *min_meta_per, unsigned *min_raw_per); H5_DLL herr_t H5Pget_sieve_buf_size(hid_t fapl_id, size_t *size/*out*/); H5_DLL herr_t H5Pget_small_data_block_size(hid_t fapl_id, hsize_t *size/*out*/); /** * \ingroup FAPL * * \brief Returns the identifier of the current VOL connector * * \fapl_id{plist_id} * \param[out] vol_id Current VOL connector identifier * * \return \herr_t * * \details H5Pget_vol_id() returns the VOL connector identifier \p vol_id for * the file access property list \p plist_id. This identifier should * be closed with H5VLclose(). * * \since 1.12.0 * */ H5_DLL herr_t H5Pget_vol_id(hid_t plist_id, hid_t *vol_id); /** * \ingroup FAPL * * \brief Returns a copy of the VOL information for a connector * * \fapl_id{plist_id} * \param[out] vol_info The VOL information for a connector * * \return \herr_t * * \details H5Pget_vol_info() returns a copy of the VOL information \p vol_info * for a connector specified by the file access property list * \p plist_id. * * \since 1.12.0 * */ H5_DLL herr_t H5Pget_vol_info(hid_t plist_id, void **vol_info); /** * \ingroup FAPL * * \brief Sets alignment properties of a file access property list * * \fapl_id * \param[in] threshold Threshold value. Note that setting the threshold * value to 0 (zero) has the effect of a special case, * forcing everything to be aligned * \param[in] alignment Alignment value * * \return \herr_t * * \details H5Pset_alignment() sets the alignment properties of a * file access property list so that any file object greater * than or equal in size to \p threshold bytes will be aligned * on an address which is a multiple of \p alignment. The * addresses are relative to the end of the user block; the * alignment is calculated by subtracting the user block size * from the absolute file address and then adjusting the address * to be a multiple of \p alignment. * * Default values for \p threshold and \p alignment are one, * implying no alignment. Generally the default values will * result in the best performance for single-process access to * 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(). * * \since 1.0.0 * */ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignment); /** * \ingroup FAPL * * \brief Sets the raw data chunk cache parameters * * \fapl_id{plist_id} * \param[in] mdc_nelmts No longer used; any value passed is ignored * \param[in] rdcc_nslots The number of chunk slots in the raw data chunk * cache for this dataset. Increasing this value * reduces the number of cache collisions, but * slightly increases the memory used. Due to the * hashing strategy, this value should ideally be a * prime number. As a rule of thumb, this value * should be at least 10 times the number of chunks * that can fit in \p rdcc_nbytes bytes. For * maximum performance, this value should be set * approximately 100 times that number of chunks. * The default value is 521. * \param[in] rdcc_nbytes Total size of the raw data chunk cache in bytes. * The default size is 1 MB per dataset. * \param[in] rdcc_w0 The chunk preemption policy for all datasets. * This must be between 0 and 1 inclusive and * indicates the weighting according to which chunks * which have been fully read or written are * penalized when determining which chunks to flush * from cache. A value of 0 means fully read or * written chunks are treated no differently than * other chunks (the preemption is strictly LRU) * while a value of 1 means fully read or written * chunks are always preempted before other chunks. * If your application only reads or writes data once, * this can be safely set to 1. Otherwise, this should * be set lower depending on how often you re-read or * re-write the same data. The default value is 0.75. * If the value passed is #H5D_CHUNK_CACHE_W0_DEFAULT, * then the property will not be set on the dataset * access property list, and the parameter will come * from the file access property list. * * \return \herr_t * * \details H5Pset_cache() sets the number of elements, the total number of * bytes, and the preemption policy value for all datasets in a file * on the file’s file access property list. * * The raw data chunk cache inserts chunks into the cache by first * computing a hash value using the address of a chunk and then by * using that hash value as the chunk’s index into the table of * cached chunks. In other words, the size of this hash table and the * number of possible hash values is determined by the \p rdcc_nslots * parameter. If a different chunk in the cache has the same hash value, * a collision will occur, which will reduce efficiency. If inserting * the chunk into the cache would cause the cache to be too big, then * the cache will be pruned according to the \p rdcc_w0 parameter. * * The \p mdc_nelmts parameter is no longer used; any value passed * in that parameter will be ignored. * * \note \b Motivation: Setting raw data chunk cache parameters * can be done with H5Pset_cache(), H5Pset_chunk_cache(), * or a combination of both. H5Pset_cache() is used to * adjust the chunk cache parameters for all datasets via * a global setting for the file, and H5Pset_chunk_cache() * is used to adjust the chunk cache parameters for * individual datasets. When both are used, parameters * set with H5Pset_chunk_cache() will override any parameters * set with H5Pset_cache(). * * \note Optimum chunk cache parameters may vary widely depending * on different data layout and access patterns. For datasets * with low performance requirements for example, changing * the cache settings can save memory. * * \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 * 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(). * \version 1.6.0 The \p rdcc_nbytes and \p rdcc_nelmts parameters * changed from type int to size_t. * \since 1.0.0 * */ H5_DLL herr_t H5Pset_cache(hid_t plist_id, int mdc_nelmts, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0); H5_DLL herr_t H5Pset_core_write_tracking(hid_t fapl_id, hbool_t is_enabled, size_t page_size); /** * \ingroup FAPL * * \brief Sets a file driver * * \plist_id * \param[in] driver_id The new driver identifier * \param[in] driver_info Optional struct containing driver properties * * \return \herr_t * * \details H5Pset_driver() sets the file driver, driver_id, for a file * access or data transfer property list, \p plist_id, and * supplies an optional struct containing the driver-specific * properties, \p driver_info. * * The driver properties will be copied into the property list * and the reference count on the driver will be incremented, * allowing the caller to close the driver identifier but still * use the property list. * * \version 1.8.2 Function publicized in this release; previous releases * described this function only in the virtual file driver * documentation. * */ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_info); H5_DLL herr_t H5Pset_elink_file_cache_size(hid_t plist_id, unsigned efc_size); H5_DLL herr_t H5Pset_evict_on_close(hid_t fapl_id, hbool_t evict_on_close); H5_DLL herr_t H5Pset_family_offset(hid_t fapl_id, hsize_t offset); /** * \ingroup FAPL * * \brief Sets the file close degree * * \fapl_id * \param[in] degree Pointer to a location containing the file close * degree property, the value of \p degree * * \return \herr_t * * \details H5Pset_fclose_degree() sets the file close degree property * \p degree in the file access property list \p fapl_id. * * The value of \p degree determines how aggressively * H5Fclose() deals with objects within a file that remain open * when H5Fclose() is called to close that file. \p degree can * have any one of four valid values: * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
Degree nameH5Fclose behavior with no open object in fileH5Fclose behavior with open object(s) in file
#H5F_CLOSE_WEAKActual file is closed.Access to file identifier is terminated; actual file * close is delayed until all objects in file are closed *
#H5F_CLOSE_SEMIActual file is closed.Function returns FAILURE
#H5F_CLOSE_STRONGActual file is closed.All open objects remaining in the file are closed then * file is closed
#H5F_CLOSE_DEFAULTThe VFL driver chooses the behavior. Currently, all VFL * drivers set this value to #H5F_CLOSE_WEAK, except for the * MPI-I/O driver, which sets it to #H5F_CLOSE_SEMI.
* \warning If a file is opened multiple times without being closed, each * open operation must use the same file close degree setting. * For example, if a file is already open with #H5F_CLOSE_WEAK, * an H5Fopen() call with #H5F_CLOSE_STRONG will fail. * * \since 1.6.0 * */ H5_DLL herr_t H5Pset_fclose_degree(hid_t fapl_id, H5F_close_degree_t degree); H5_DLL herr_t H5Pset_file_image(hid_t fapl_id, void *buf_ptr, size_t buf_len); H5_DLL herr_t H5Pset_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr); H5_DLL herr_t H5Pset_file_locking(hid_t fapl_id, hbool_t use_file_locking, hbool_t ignore_when_disabled); H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); /** * \ingroup FAPL * * \brief Controls the range of library release versions used when creating * objects in a file * * \fapl_id{plist_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 H5Pset_libver_bounds() controls the range of library release * versions that will be used when creating objects in a file. * The object format versions are determined indirectly from the * library release versions specified in the call. * * This property is set in the file access property list * specified by the parameter \p fapl_id. * * The parameter \p low sets the earliest possible format * versions that the library will use when creating objects in * the file. Note that earliest possible is different from * earliest, as some features introduced in library versions * later than 1.0.0 resulted in updates to object formats. * The parameter \p high sets the latest format versions that * the library will be allowed to use when creating objects in * the file. * * The parameters \p low and \p high must be one of the * enumerated values in the #H5F_libver_t struct, which is * defined in H5Fpublic.h. * * The macro #H5F_LIBVER_LATEST is aliased to the highest * enumerated value in #H5F_libver_t, indicating that this is * currently the latest format available. * * The library supports the following five pairs of * (\p low, \p high) combinations as derived from the values * in #H5F_libver_t: * * * * * * * * * * * * * * * * * * * * * * * * * * *
Value of \p low and \p highResult
\p low=#H5F_LIBVER_EARLIEST
* \p high=#H5F_LIBVER_V18		 * \li The library will create objects with the earliest * possible format versions. * \li The library will allow objects to be created with the * latest format versions available to library release 1.8.x. * \li API calls that create objects or features that are * available to versions of the library greater than 1.8.x * release will fail. *
\p low=#H5F_LIBVER_EARLIEST
* \p high=#H5F_LIBVER_V110		 * \li The library will create objects with the earliest possible * format versions. * \li The library will allow objects to be created with the latest * format versions available to library release 1.10.x. * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper * limit on the format versions to use. For example, if a newer * format version is required to support a feature e.g. virtual * dataset, this setting will allow the object to be created. * \li This is the library default setting and provides the greatest * format compatibility. *
\p low=#H5F_LIBVER_V18
* \p high=#H5F_LIBVER_V18		 * \li The library will create objects with the latest format versions * available to library release 1.8.x. * \li API calls that create objects or features that are available * to versions of the library greater than 1.8.x release will fail. * \li Earlier versions of the library may not be able to access * objects created with this setting.
\p low=#H5F_LIBVER_V18
* \p high=#H5F_LIBVER_V110		 * \li The library will create objects with the latest format versions * available to library release 1.8.x. * \li The library will allow objects to be created with the latest * format versions available to library release 1.10.x. * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper limit * on the format versions to use. For example, if a newer format * version is required to support a feature e.g. virtual dataset, * this setting will allow the object to be created. * \li Earlier versions of the library may not be able to access * objects created with this setting.
\p low=#H5F_LIBVER_V110
* \p high=#H5F_LIBVER_V110 * 		* \li The library will create objects with the latest format versions * available to library release 1.10.x. * \li The library will allow objects to be created with the latest * format versions available to library release 1.10.x. * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper limit * on the format versions to use. For example, if a newer format * version is required to support a feature e.g. virtual dataset, * this setting will allow the object to be created. * \li This setting allows users to take advantage of the latest * features and performance enhancements in the library. However, * objects written with this setting may be accessible to a smaller * range of library versions than would be the case if low is set * to #H5F_LIBVER_EARLIEST. * \li Earlier versions of the library may not be able to access objects created with this setting. *
* * \version 1.10.2 #H5F_LIBVER_V18 added to the enumerated defines in #H5F_libver_t. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_t high); H5_DLL herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); H5_DLL herr_t H5Pset_mdc_log_options(hid_t plist_id, hbool_t is_enabled, const char *location, hbool_t start_on_access); H5_DLL herr_t H5Pset_meta_block_size(hid_t fapl_id, hsize_t size); H5_DLL herr_t H5Pset_metadata_read_attempts(hid_t plist_id, unsigned attempts); H5_DLL herr_t H5Pset_multi_type(hid_t fapl_id, H5FD_mem_t type); H5_DLL herr_t H5Pset_object_flush_cb(hid_t plist_id, H5F_flush_cb_t func, void *udata); H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size); H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size); /** * \ingroup FAPL * * \brief Set the file VOL connector for a file access property list * * \fapl_id{plist_id} * \param[in] new_vol_id VOL connector identifier * \param[in] new_vol_info Optional VOL information * * \return \herr_t * * \details H5Pset_vol() sets the VOL connector \p new_vol_id for a file access * property list \p plist_id using the (optional) VOL information in * \p new_vol_info. * * \since 1.12.0 * */ H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_info); #ifdef H5_HAVE_PARALLEL H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective); H5_DLL herr_t H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collective); 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); H5_DLL herr_t H5Pget_mpi_params(hid_t fapl_id, MPI_Comm *comm, MPI_Info *info); H5_DLL herr_t H5Pset_mpi_params(hid_t fapl_id, MPI_Comm comm, MPI_Info info); #endif /* H5_HAVE_PARALLEL */ H5_DLL herr_t H5Pset_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr); H5_DLL herr_t H5Pset_page_buffer_size(hid_t plist_id, size_t buf_size, unsigned min_meta_per, unsigned min_raw_per); /* Dataset creation property list (DCPL) routines */ /** * \ingroup DCPL * * \brief Determines whether fill value is defined * * \dcpl_id{plist} * \param[out] status Status of fill value in property list * * \return \herr_t * * \details H5Pfill_value_defined() determines whether a fill value is * defined in the dataset creation property list \p plist. Valid * values returned in status are as follows: * * * * * * * * * * * * * * *
#H5D_FILL_VALUE_UNDEFINEDFill value is undefined.
#H5D_FILL_VALUE_DEFAULTFill value is the library default.
#H5D_FILL_VALUE_USER_DEFINEDFill value is defined by the application.
* * \since 1.6.0 * */ H5_DLL herr_t H5Pfill_value_defined(hid_t plist, H5D_fill_value_t *status); /** * \ingroup DCPL * * \brief Retrieves the timing for storage space allocation * * \dcpl_id{plist_id} * \param[out] alloc_time The timing setting for allocating dataset * storage space * * \return \herr_t * * \details H5Pget_alloc_time() retrieves the timing for allocating storage * space for a dataset's raw data. This property is set in the * dataset creation property list \p plist_id. The timing setting * is returned in \p alloc_time as one of the following values: * * * * * * * * * * * * * * * * * * *
#H5D_ALLOC_TIME_DEFAULT
 		Uses the default allocation time, based on the dataset * storage method.
See the \p alloc_time description in * H5Pset_alloc_time() for default allocation times for * various storage methods.
#H5D_ALLOC_TIME_EARLYAll space is allocated when the dataset is created.
#H5D_ALLOC_TIME_INCRSpace is allocated incrementally as data is written * to the dataset.
#H5D_ALLOC_TIME_LATEAll space is allocated when data is first written to * the dataset.
* * \note H5Pget_alloc_time() is designed to work in concert with the * dataset fill value and fill value write time properties, set * with the functions H5Pget_fill_value() and H5Pget_fill_time(). * * \since 1.6.0 * */ H5_DLL herr_t H5Pget_alloc_time(hid_t plist_id, H5D_alloc_time_t *alloc_time/*out*/); /** * \ingroup DCPL * * \brief Retrieves the size of chunks for the raw data of a chunked * layout dataset * * \dcpl_id{plist_id} * \param[in] max_ndims Size of the \p dims array * \param[out] dim Array to store the chunk dimensions * * \return Returns chunk dimensionality if successful; * otherwise returns a negative value. * * \details H5Pget_chunk() retrieves the size of chunks for the raw data * of a chunked layout dataset. This function is only valid for * dataset creation property lists. At most, \p max_ndims elements * of \p dim will be initialized. * * \since 1.0.0 * */ H5_DLL int H5Pget_chunk(hid_t plist_id, int max_ndims, hsize_t dim[]/*out*/); /** * * \ingroup DCPL * * \brief Retrieves the edge chunk option setting from a dataset creation * property list * * \dcpl_id{plist_id} * \param[out] opts Edge chunk option flag. Valid values are described in * H5Pset_chunk_opts(). The option status can be * retrieved using the bitwise AND operator ( & ). For * example, the expression * (opts&#H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS) will * evaluate to #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS if * that option has been enabled. Otherwise, it will * evaluate to 0 (zero). * * \return \herr_t * * \details H5Pget_chunk_opts() retrieves the edge chunk option setting * stored in the dataset creation property list \p plist_id. * * \since 1.10.0 * */ H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts); /** * \ingroup DCPL * * \brief Retrieves the setting for whether or not to create minimized * dataset object headers * * \dcpl_id * \param[out] minimize Flag indicating whether the library will or will * not create minimized dataset object headers * * \return \herr_t * * \details H5Pget_dset_no_attrs_hint() retrieves the * no dataset attributes hint setting for the dataset * creation property list \p dcpl_id. This setting is used to * inform the library to create minimized dataset object headers * when TRUE. The setting value is returned in the boolean pointer * \p minimize. * * \since 1.10.5 * */ H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize); /** * \ingroup DCPL * * \brief Returns information about an external file * * \dcpl_id{plist_id} * \param[in] idx External file index * \param[in] name_size Maximum length of \p name array * \param[out] name Name of the external file * \param[out] offset Pointer to a location to return an offset value * \param[out] size Pointer to a location to return the size of the * external file data * * \return \herr_t * * \details H5Pget_external() returns information about an external file. * The external file is specified by its index, \p idx, which * is a number from zero to N-1, where N is the value returned * by H5Pget_external_count(). At most \p name_size characters * are copied into the \p name array. If the external file name * is longer than \p name_size with the null terminator, the * return value is not null terminated (similar to strncpy()). * * If \p name_size is zero or \p name is the null pointer, the * external file name is not returned. If \p offset or \p size * are null pointers then the corresponding information is not * returned. * * \version 1.6.4 \p idx parameter type changed to unsigned. * \since 1.0.0 * */ H5_DLL herr_t H5Pget_external(hid_t plist_id, unsigned idx, size_t name_size, char *name/*out*/, off_t *offset/*out*/, hsize_t *size/*out*/); /** * \ingroup DCPL * * \brief Returns the number of external files for a dataset * * \dcpl_id{plist_id} * * \return Returns the number of external files if successful; otherwise * returns a negative value. * * \details H5Pget_external_count() returns the number of external files * for the specified dataset. * * \since 1.0.0 * */ H5_DLL int H5Pget_external_count(hid_t plist_id); /** * \ingroup DCPL * * \brief Retrieves the time when fill values are written to a dataset * * \dcpl_id{plist_id} * \param[out] fill_time Setting for the timing of writing fill values to * the dataset * * \return \herr_t * * \details H5Pget_fill_time() examines the dataset creation property list * \p plist_id to determine when fill values are to be written to * a dataset. Valid values returned in \p fill_time are as * follows: * * * * * * * * * * * * * * *
#H5D_FILL_TIME_IFSETFill values are written to the dataset when storage * space is allocated only if there is a user-defined fill * value, i.e., one set with H5Pset_fill_value(). (Default) *
#H5D_FILL_TIME_ALLOCFill values are written to the dataset when storage * space is allocated.
#H5D_FILL_TIME_NEVERFill values are never written to the dataset.
* * \note H5Pget_fill_time() is designed to work in coordination with the * dataset fill value and dataset storage allocation time properties, * retrieved with the functions H5Pget_fill_value() and * H5Pget_alloc_time(). * * \since 1.6.0 * */ H5_DLL herr_t H5Pget_fill_time(hid_t plist_id, H5D_fill_time_t *fill_time/*out*/); /** * \ingroup DCPL * * \brief Retrieves a dataset fill value * * \dcpl_id{plist_id} * \param[in] type_id Datatype identifier for the value passed via * \p value * \param[out] value Pointer to buffer to contain the returned * fill value * * \return \herr_t * * \details H5Pget_fill_value() returns the dataset fill value defined in * the dataset creation property list \p plist_id. The fill value * is returned through the \p value pointer and will be converted * to the datatype specified by \p type_id. This datatype may * differ from the fill value datatype in the property list, but * the HDF5 library must be able to convert between the two * datatypes. * * If the fill value is undefined, i.e., set to NULL in the * property list, H5Pget_fill_value() will return an error. * H5Pfill_value_defined() should be used to check for this * condition before H5Pget_fill_value() is called. * * Memory must be allocated by the calling application. * * \note H5Pget_fill_value() is designed to coordinate with the dataset * storage allocation time and fill value write time properties, * which can be retrieved with the functions H5Pget_alloc_time() * and H5Pget_fill_time(), respectively. * * \since 1.0.0 * */ H5_DLL herr_t H5Pget_fill_value(hid_t plist_id, hid_t type_id, void *value/*out*/); /** * \ingroup DCPL * * \brief Returns the layout of the raw data for a dataset * * \dcpl_id{plist_id} * * \return Returns the layout type (a non-negative value) of a dataset * creation property list if successful. Valid return values are: * - #H5D_COMPACT: Raw data is stored in the object header in the * file. * - #H5D_CONTIGUOUS: Raw data is stored separately from the object * header in one contiguous chunk in the file. * - #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. * * \details H5Pget_layout() returns the layout of the raw data for a * dataset. This function is only valid for dataset creation * property lists. * * Note that a compact storage layout may affect writing data to * 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 * */ H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id); /** * \ingroup DCPL * * \brief Gets the number of mappings for the virtual dataset * * \dcpl_id * \param[out] count The number of mappings * * \return \herr_t * * \details H5Pget_virtual_count() gets the number of mappings for a * virtual dataset that has the creation property list specified * by \p dcpl_id. * * \virtual * * \since 1.10.0 * */ H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count/*out*/); /** * \ingroup DCPL * * \brief Gets the name of a source dataset used in the mapping * * \dcpl_id * \param[in] index Mapping index. The value of \p index is 0 (zero) or * greater and less than \p count * (0 ≤ \p index < \p count), where \p count is the * number of mappings returned by H5Pget_virtual_count(). * \param[out] name A buffer containing the name of the source dataset * \param[in] size The size, in bytes, of the name buffer. Must be the * size of the dataset name in bytes plus 1 for a NULL * terminator * * \return Returns the length of the dataset name if successful; * otherwise returns a negative value. * * \details H5Pget_virtual_dsetname() takes the dataset creation property * list for the virtual dataset, \p dcpl_id, the mapping index, * \p index, the size of the dataset name for a source dataset, * \p size, and retrieves the name of the source dataset used in * the mapping. * * Up to \p size characters of the dataset name are returned in * \p name; additional characters, if any, are not returned to * the user application. * * If the length of the dataset name, which determines the * required value of \p size, is unknown, a preliminary call * to H5Pget_virtual_dsetname() with the last two parameters * set to NULL and zero respectively can be made. The return * value of this call will be the size in bytes of the dataset * name. That value, plus 1 for a NULL terminator, must then be * assigned to \p size for a second H5Pget_virtual_dsetname() * call, which will retrieve the actual dataset name. * * \virtual * * \since 1.10.0 * */ H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name/*out*/, size_t size); /** * \ingroup DCPL * * \brief Gets the filename of a source dataset used in the mapping * * \dcpl_id * \param[in] index Mapping index. The value of \p index is 0 (zero) or * greater and less than \p count * (0 ≤ \p index < \p count), where \p count is the * number of mappings returned by H5Pget_virtual_count(). * \param[out] name A buffer containing the name of the file containing * the source dataset * \param[in] size The size, in bytes, of the name buffer. Must be the * size of the filename in bytes plus 1 for a NULL * terminator * * \return Returns the length of the filename if successful; otherwise * returns a negative value. * * \details H5Pget_virtual_filename() takes the dataset creation property * list for the virtual dataset, \p dcpl_id, the mapping index, * \p index, the size of the filename for a source dataset, * \p size, and retrieves the name of the file for a source dataset * used in the mapping. * * Up to \p size characters of the filename are returned in * \p name; additional characters, if any, are not returned to * the user application. * * If the length of the filename, which determines the required * value of \p size, is unknown, a preliminary call to * H5Pget_virtual_filename() with the last two parameters set * to NULL and zero respectively can be made. The return value * of this call will be the size in bytes of the filename. That * value, plus 1 for a NULL terminator, must then be assigned to * \p size for a second H5Pget_virtual_filename() call, which * will retrieve the actual filename. * * \virtual * * \since 1.10.0 * */ H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index, char *name/*out*/, size_t size); /** * \ingroup DCPL * * \brief Gets a dataspace identifier for the selection within the source * dataset used in the mapping * * \dcpl_id * \param[in] index Mapping index. The value of \p index is 0 (zero) or * greater and less than \p count * (0 ≤ \p index < \p count), where \p count is the number * of mappings returned by H5Pget_virtual_count(). * * \return \hid_t{valid dataspace identifier} * * \details H5Pget_virtual_srcspace() takes the dataset creation property * list for the virtual dataset, \p dcpl_id, and the mapping * index, \p index, and returns a dataspace identifier for the * selection within the source dataset used in the mapping. * * \virtual * * \since 1.10.0 * */ H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index); /** * \ingroup DCPL * * \brief Gets a dataspace identifier for the selection within the virtual * dataset used in the mapping * * \dcpl_id * \param[in] index Mapping index. The value of \p index is 0 (zero) or * greater and less than \p count * (0 ≤ \p index < \p count), where \p count is the number * of mappings returned by H5Pget_virtual_count() * * \return \hid_t{valid dataspace identifier} * * \details H5Pget_virtual_vspace() takes the dataset creation property * list for the virtual dataset, \p dcpl_id, and the mapping * index, \p index, and returns a dataspace identifier for the * selection within the virtual dataset used in the mapping. * * \virtual * * \since 1.10.0 * */ H5_DLL hid_t H5Pget_virtual_vspace(hid_t dcpl_id, size_t index); /** * \ingroup DCPL * * \brief Sets the timing for storage space allocation * * \dcpl_id{plist_id} * \param[in] alloc_time When to allocate dataset storage space * * \return \herr_t * * \details H5Pset_alloc_time() sets up the timing for the allocation of * storage space for a dataset's raw data. This property is set * in the dataset creation property list \p plist_id. Timing is * specified in \p alloc_time with one of the following values: * * * * * * * * * * * * * * * * * * *
#H5D_ALLOC_TIME_DEFAULTAllocate dataset storage space at the default time
* (Defaults differ by storage method.)
#H5D_ALLOC_TIME_EARLYAllocate all space when the dataset is created
* (Default for compact datasets.)
#H5D_ALLOC_TIME_INCRAllocate space incrementally, as data is written to * the dataset
(Default for chunked storage datasets.) * * \li Chunked datasets: Storage space allocation for each * chunk is deferred until data is written to the chunk. * \li Contiguous datasets: Incremental storage space * allocation for contiguous data is treated as late * allocation. * \li Compact datasets: Incremental allocation is not * allowed with compact datasets; H5Pset_alloc_time() * will return an error.
#H5D_ALLOC_TIME_LATEAllocate all space when data is first written to the * dataset
* (Default for contiguous datasets.)
* * \note H5Pset_alloc_time() is designed to work in concert with the * dataset fill value and fill value write time properties, set * with the functions H5Pset_fill_value() and H5Pset_fill_time(). * * \note See H5Dcreate() for further cross-references. * * \since 1.6.0 * */ H5_DLL herr_t H5Pset_alloc_time(hid_t plist_id, H5D_alloc_time_t alloc_time); /** * \ingroup DCPL * * \brief Sets the size of the chunks used to store a chunked layout * dataset * * \dcpl_id{plist_id} * \param[in] ndims The number of dimensions of each chunk * \param[in] dim An array defining the size, in dataset elements, of * each chunk * * \return \herr_t * \details H5Pset_chunk() sets the size of the chunks used to store a * chunked layout dataset. This function is only valid for dataset * creation property lists. * * The \p ndims parameter currently must be the same size as the * rank of the dataset. * * The values of the \p dim array define the size of the chunks * to store the dataset's raw data. The unit of measure for \p dim * values is dataset elements. * * As a side-effect of this function, the layout of the dataset is * changed to #H5D_CHUNKED, if it is not already so set. * * \note Chunk size cannot exceed the size of a fixed-size dataset. For * example, a dataset consisting of a 5x4 fixed-size array cannot be * defined with 10x10 chunks. Chunk maximums: * - The maximum number of elements in a chunk is 232-1 which * is equal to 4,294,967,295. If the number of elements in a chunk is * set via H5Pset_chunk() to a value greater than 232-1, * then H5Pset_chunk() will fail. * - The maximum size for any chunk is 4GB. If a chunk that is larger * than 4GB attempts to be written with H5Dwrite(), then H5Dwrite() * will fail. * * \see H5Pset_layout(), H5Dwrite() * * \since 1.0.0 * */ H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims*/]); /** * \ingroup DCPL * * \brief Sets the edge chunk option in a dataset creation property list * * \dcpl_id{plist_id} * \param[in] opts Edge chunk option flag. Valid values are: * \li #H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS * When enabled, filters are not applied to partial * edge chunks. When disabled, partial edge chunks are * filtered. Enabling this option will improve * performance when appending to the dataset and, when * compression filters are used, prevent reallocation * of these chunks. Datasets created with this option * enabled will be inaccessible with HDF5 library * versions before Release 1.10. Default: \e Disabled * \li 0 (zero) Disables option; partial edge chunks * will be compressed. * * \return \herr_t * * \details H5Pset_chunk_opts() sets the edge chunk option in the * dataset creation property list \p dcpl_id. * * The available option is detailed in the parameters section. * Only chunks that are not completely filled by the dataset’s * dataspace are affected by this option. Such chunks are * referred to as partial edge chunks. * * \note \b Motivation: H5Pset_chunk_opts() is used to specify storage * options for chunks on the edge of a dataset’s dataspace. This * capability allows the user to tune performance in cases where * the dataset size may not be a multiple of the chunk size and * the handling of partial edge chunks can impact performance. * * \since 1.10.0 * */ H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts); /** * \ingroup DCPL * * \brief Sets the flag to create minimized dataset object headers * * \dcpl_id * \param[in] minimize Flag for indicating whether or not a dataset's * object header will be minimized * * \return \herr_t * * \details H5Pset_dset_no_attrs_hint() sets the no dataset attributes * hint setting for the dataset creation property list \p dcpl_id. * Datasets created with the dataset creation property list * \p dcpl_id will have their object headers minimized if the * boolean flag \p minimize is set to TRUE. By setting \p minimize * to 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. * * This setting interacts with H5Fset_dset_no_attrs_hint(): if * either is set to TRUE, then the created dataset's object header * will be minimized. * * \since 1.10.5 * */ H5_DLL herr_t H5Pset_dset_no_attrs_hint(hid_t dcpl_id, hbool_t minimize); /** * \ingroup DCPL * * \brief Adds an external file to the list of external files * * \dcpl_id{plist_id} * \param[in] name Name of an external file * \param[in] offset Offset, in bytes, from the beginning of the file to * the location in the file where the data starts * \param[in] size Number of bytes reserved in the file for the data * * \return \herr_t * * \details The first call to H5Pset_external() sets the external * storage property in the property list, thus designating that * the dataset will be stored in one or more non-HDF5 file(s) * external to the HDF5 file. This call also adds the file * \p name as the first file in the list of external files. * Subsequent calls to the function add the named file as the * next file in the list. * * If a dataset is split across multiple files, then the files * should be defined in order. The total size of the dataset is * the sum of the \p size arguments for all the external files. * If the total size is larger than the size of a dataset then * the dataset can be extended (provided the data space also * allows the extending). * * The \p size argument specifies the number of bytes reserved * for data in the external file. If \p size is set to * #H5F_UNLIMITED, the external file can be of unlimited size * and no more files can be added to the external files list. * If \p size is set to 0 (zero), no external file will actually * be created. * * All of the external files for a given dataset must be specified * with H5Pset_external() before H5Dcreate() is called to create * the dataset. If one these files does not exist on the system * when H5Dwrite() is called to write data to it, the library * will create the file. * * \since 1.0.0 * */ H5_DLL herr_t H5Pset_external(hid_t plist_id, const char *name, off_t offset, hsize_t size); /** * \ingroup DCPL * * \brief Sets the time when fill values are written to a dataset * * \dcpl_id{plist_id} * \param[in] fill_time When to write fill values to a dataset * * \return \herr_t * * \details H5Pset_fill_time() sets up the timing for writing fill values * to a dataset. This property is set in the dataset creation * property list \p plist_id. Timing is specified in \p fill_time * with one of the following values: * * * * * * * * * * * * * * *
#H5D_FILL_TIME_IFSETWrite fill values to the dataset when storage space is * allocated only if there is a user-defined fill value, * i.e.,one set with H5Pset_fill_value(). (Default)
#H5D_FILL_TIME_ALLOCWrite fill values to the dataset when storage space is * allocated.
#H5D_FILL_TIME_NEVERNever write fill values to the dataset.
* * \note H5Pset_fill_time() is designed for coordination with the dataset * fill value and dataset storage allocation time properties, set * with the functions H5Pset_fill_value() and H5Pset_alloc_time(). * See H5Dcreate() for further cross-references. * * \since 1.6.0 * */ H5_DLL herr_t H5Pset_fill_time(hid_t plist_id, H5D_fill_time_t fill_time); /** * \ingroup DCPL * * \brief Sets the fill value for a dataset * * \dcpl_id{plist_id} * \param[in] type_id Datatype of \p value * \param[in] value Pointer to buffer containing value to use as * fill value * * \return \herr_t * * \details H5Pset_fill_value() sets the fill value for a dataset in the * dataset creation property list. \p value is interpreted as * being of datatype \p type_id. This datatype may differ from * that of the dataset, but the HDF5 library must be able to * convert \p value to the dataset datatype when the dataset is * created. * * The default fill value is 0 (zero), which is interpreted * according to the actual dataset datatype. * * Setting \p value to NULL indicates that the fill value is to * be undefined. * * \note Applications sometimes write data only to portions of an allocated * dataset. It is often useful in such cases to fill the unused space * with a known fill value. This function allows the user application * to set that fill value; the functions H5Dfill() and * H5Pset_fill_time(), respectively, provide the ability to apply the * fill value on demand or to set up its automatic application. * * \note A fill value should be defined so that it is appropriate for the * application. While the HDF5 default fill value is 0 (zero), it is * often appropriate to use another value. It might be useful, for * example, to use a value that is known to be impossible for the * application to legitimately generate. * * \note H5Pset_fill_value() is designed to work in concert with * H5Pset_alloc_time() and H5Pset_fill_time(). H5Pset_alloc_time() * and H5Pset_fill_time() govern the timing of dataset storage * allocation and fill value write operations and can be important in * tuning application performance. * * \note See H5Dcreate() for further cross-references. * * \since 1.0.0 * */ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value); /** * \ingroup DCPL * * \brief Sets up use of the shuffle filter * * \dcpl_id{plist_id} * * \return \herr_t * * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE, * in the dataset creation property list \p plist_id. The shuffle * filter de-interlaces a block of data by reordering the bytes. * All the bytes from one consistent byte position of each data * element are placed together in one block; all bytes from a * second consistent byte position of each data element are placed * together a second block; etc. For example, given three data * elements of a 4-byte datatype stored as 012301230123, shuffling * will re-order data as 000111222333. This can be a valuable step * in an effective compression algorithm because the bytes in each * byte position are often closely related to each other and * putting them together can increase the compression ratio. * * As implied above, the primary value of the shuffle filter lies * in its coordinated use with a compression filter; it does not * provide data compression when used alone. When the shuffle * filter is applied to a dataset immediately prior to the use of * a compression filter, the compression ratio achieved is often * superior to that achieved by the use of a compression filter * without the shuffle filter. * * \since 1.6.0 * */ H5_DLL herr_t H5Pset_shuffle(hid_t plist_id); /** * \ingroup DCPL * * \brief Sets the type of storage used to store the raw data for a dataset * * \dcpl_id{plist_id} * \param[in] layout Type of storage layout for raw data * * \return \herr_t * \details H5Pset_layout() sets the type of storage used to store the raw * data for a dataset. This function is only valid for dataset * creation property lists. * * Valid values for \p layout are: * - #H5D_COMPACT: Store raw data in the dataset object header * in file. This should only be used for datasets * with small amounts of raw data. The raw data * size limit is 64K (65520 bytes). Attempting * to create a dataset with raw data larger than * this limit will cause the H5Dcreate() call to * fail. * - #H5D_CONTIGUOUS: Store raw data separately from the object * header in one large chunk in the file. * - #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 * */ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); //! [nbit_code_snip] /* hid_t nbit_datatype = H5Tcopy(H5T_STD_I32LE); H5Tset_precision(nbit_datatype, 16); H5Tset_offset(nbit_datatype, 4); */ //! [nbit_code_snip] /** * \ingroup DCPL * * \brief Sets up the use of the N-Bit filter * * \dcpl_id{plist_id} * * \return \herr_t * * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the * dataset creation property list \p plist_id. * * The HDF5 user can create an N-Bit datatype with the following * code: * \snippet this nbit_code_snip * * In memory, one value of the N-Bit datatype in the above example * will be stored on a little-endian machine as follows: * * * * * * * * * * * * * * *
byte 3byte 2byte 1byte 0
????????????SPPPPPPPPPPPPPPP????
* Note: S - sign bit, P - significant bit, ? - padding bit; For * signed integer, the sign bit is included in the precision. * * When data of the above datatype is stored on disk using the * N-bit filter, all padding bits are chopped off and only * significant bits are stored. The values on disk will be * something like: * * * * * * * * * * * * *
1st value2nd value...
SPPPPPPPPPPPPPPPSPPPPPPPPPPPPPPP...
* The N-Bit filter is used effectively for compressing data of * an N-Bit datatype as well as a compound and an array * datatype with N-Bit fields. However, the datatype classes of * the N-Bit datatype or the N-Bit field of the compound * datatype or the array datatype are limited to integer or * floating-point. * * The N-Bit filter supports complex situations where a compound * datatype contains member(s) of a compound datatype or an array * datatype that has a compound datatype as the base type. * However, it does not support the situation where an array * datatype has a variable-length or variable-length string as * its base datatype. The filter does support the situation where * a variable-length or variable-length string is a member of a * compound datatype. * * The N-Bit filter allows all other HDF5 datatypes (such as * time, string, bitfield, opaque, reference, enum, and variable * length) to pass through as a no-op. * * Like other I/O filters supported by the HDF5 library, * application using the N-Bit filter must store data with * chunked storage. * * By nature, the N-Bit filter should not be used together with * other I/O filters. * * \version 1.8.8 Fortran subroutine introduced in this release. * \todo fix "nbit_code_snip" * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_nbit(hid_t plist_id); /** * \ingroup DCPL * * \brief Sets up the use of the scale-offset filter * * \dcpl_id{plist_id} * \param[in] scale_type Flag indicating compression method * \param[in] scale_factor Parameter related to scale. Must be * non-negative * * \return \herr_t * * \details H5Pset_scaleoffset() sets the scale-offset filter, * #H5Z_FILTER_SCALEOFFSET, for a dataset. * * Generally speaking, scale-offset compression performs a scale and/or * offset operation on each data value and truncates the resulting * value to a minimum number of bits (MinBits) before storing it. The * current scale-offset filter supports integer and floating-point * datatypes. * * For an integer datatype, the parameter \p scale_type should be set * to #H5Z_SO_INT (2). The parameter \p scale_factor denotes MinBits. * If the user sets it to H5Z_SO_INT_MINBITS_DEFAULT (0), the filter * will calculate MinBits. If \p scale_factor is set to a positive * integer, the filter does not do any calculation and just uses the * number as MinBits. However, if the user gives a MinBits that is less * than what would be generated by the filter, the compression will be * lossy. Also, the MinBits supplied by the user cannot exceed the * number of bits to store one value of the dataset datatype. * * For a floating-point datatype, the filter adopts the GRiB data * packing mechanism, which offers two alternate methods: E-scaling and * D-scaling. Both methods are lossy compression. If the parameter * \p scale_type is set to #H5Z_SO_FLOAT_DSCALE (0), the filter will * use the D-scaling method; if it is set to #H5Z_SO_FLOAT_ESCALE (1), * the filter will use the E-scaling method. Since only the D-scaling * method is implemented, \p scale_type should be set to * #H5Z_SO_FLOAT_DSCALE or 0. * * When the D-scaling method is used, the original data is "D" scaled * — multiplied by 10 to the power of \p scale_factor, and the * "significant" part of the value is moved to the left of the decimal * point. Care should be taken in setting the decimal \p scale_factor * so that the integer part will have enough precision to contain the * appropriate information of the data value. For example, if * \p scale_factor is set to 2, the number 104.561 will be 10456.1 * after "D" scaling. The last digit 1 is not "significant" and is * thrown off in the process of rounding. The user should make sure that * after "D" scaling and rounding, the data values are within the range * that can be represented by the integer (same size as the * floating-point type). * * Valid values for scale_type are as follows: * * * * * * * * * * * * * * *
#H5Z_SO_FLOAT_DSCALE (0)Floating-point type, using variable MinBits method
#H5Z_SO_FLOAT_ESCALE (1)Floating-point type, using fixed MinBits method
#H5Z_SO_INT (2)Integer type
* * The meaning of \p scale_factor varies according to the value * assigned to \p scale_type: * * * * * * * * * * * * * * * * * * *
\p scale_type value\p scale_factor description
#H5Z_SO_FLOAT_DSCALEDenotes the decimal scale factor for D-scaling and can be * positive, negative or zero. This is the current * implementation of the library.
#H5Z_SO_FLOAT_ESCALEDenotes MinBits for E-scaling and must be a positive integer. * This is not currently implemented by the library.
#H5Z_SO_INTDenotes MinBits and it should be a positive integer or * #H5Z_SO_INT_MINBITS_DEFAULT (0). If it is less than 0, the * library will reset it to 0 since it is not implemented. *
* Like other I/O filters supported by the HDF5 library, an * application using the scale-offset filter must store data with * chunked storage. * * \version 1.8.8 Fortran90 subroutine introduced in this release. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, int scale_factor); /** * \ingroup DCPL * * \brief Sets up use of the SZIP compression filter * * \dcpl_id{plist_id} * \param[in] options_mask A bit-mask conveying the desired SZIP options; * Valid values are #H5_SZIP_EC_OPTION_MASK and * #H5_SZIP_NN_OPTION_MASK. * \param[in] pixels_per_block The number of pixels or data elements in each * data block * * \return \herr_t * * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP, * for a dataset. SZIP is a compression method designed for use with * scientific data. * * Before proceeding, all users should review the “Limitations” * section below. * * Users familiar with SZIP outside the HDF5 context may benefit * from reviewing the Note “For Users Familiar with SZIP in Other * Contexts” below. * * In the text below, the term pixel refers to an HDF5 data element. * This terminology derives from SZIP compression's use with image * data, where pixel referred to an image pixel. * * The SZIP \p bits_per_pixel value (see Note, below) is automatically * set, based on the HDF5 datatype. SZIP can be used with atomic * datatypes that may have size of 8, 16, 32, or 64 bits. * Specifically, a dataset with a datatype that is 8-, 16-, 32-, or * 64-bit signed or unsigned integer; char; or 32- or 64-bit float * can be compressed with SZIP. See Note, below, for further * discussion of the the SZIP \p bits_per_pixel setting. * * SZIP options are passed in an options mask, \p options_mask, * as follows. * * * * * * * * * * * * * * *
OptionDescription (Mutually exclusive; select one.)
#H5_SZIP_EC_OPTION_MASKSelects entropy coding method
#H5_SZIP_NN_OPTION_MASKSelects nearest neighbor coding method
* * The following guidelines can be used in determining which * option to select: * * - The entropy coding method, the EC option specified by * #H5_SZIP_EC_OPTION_MASK, is best suited for data that has been * processed. The EC method works best for small numbers. * - The nearest neighbor coding method, the NN option specified * by #H5_SZIP_NN_OPTION_MASK, preprocesses the data then the * applies EC method as above. * * Other factors may affect results, but the above criteria * provides a good starting point for optimizing data compression. * * SZIP compresses data block by block, with a user-tunable block * size. This block size is passed in the parameter * \p pixels_per_block and must be even and not greater than 32, * with typical values being 8, 10, 16, or 32. This parameter * affects compression ratio; the more pixel values vary, the * smaller this number should be to achieve better performance. * * In HDF5, compression can be applied only to chunked datasets. * If \p pixels_per_block is bigger than the total number of * elements in a dataset chunk, H5Pset_szip() will succeed but * the subsequent call to H5Dcreate() will fail; the conflict * can be detected only when the property list is used. * * To achieve optimal performance for SZIP compression, it is * recommended that a chunk's fastest-changing dimension be equal * to N times \p pixels_per_block where N is the maximum number of * blocks per scan line allowed by the SZIP library. In the * current version of SZIP, N is set to 128. * * SZIP compression is an optional HDF5 filter. * * \b Limitations: * * - SZIP compression cannot be applied to compound, array, * variable-length, enumeration, or any other user-defined * datatypes. If an SZIP filter is set in a dataset creation * property list used to create a dataset containing a * non-allowed datatype, the call to H5Dcreate() will fail; the * conflict can be detected only when the property list is used. * - Users should be aware that there are factors that affect one’s * rights and ability to use SZIP compression by reviewing the * SZIP copyright notice. * * \note \b For \b Users \b Familiar \b with \b SZIP \b in \b Other \b Contexts: * * \note The following notes are of interest primarily to those who have * used SZIP compression outside of the HDF5 context. * In non-HDF5 applications, SZIP typically requires that the user * application supply additional parameters: * - \p pixels_in_object, the number of pixels in the object to * be compressed * - \p bits_per_pixel, the number of bits per pixel * - \p pixels_per_scanline, the number of pixels per scan line * * \note These values need not be independently supplied in the HDF5 * environment as they are derived from the datatype and dataspace, * which are already known. In particular, HDF5 sets * \p pixels_in_object to the number of elements in a chunk and * \p bits_per_pixel to the size of the element or pixel datatype. * * \note The following algorithm is used to set \p pixels_per_scanline: * - If the size of a chunk's fastest-changing dimension, size, * is greater than 4K, set \p pixels_per_scanline to 128 times * \p pixels_per_block. * - If size is less than 4K but greater than \p pixels_per_block, * set \p pixels_per_scanline to the minimum of size and 128 * times \p pixels_per_block. * - If size is less than \p pixels_per_block but greater than the * number elements in the chunk, set \p pixels_per_scanline to * the minimum of the number elements in the chunk and 128 times * \p pixels_per_block. * * \note The HDF5 datatype may have precision that is less than the full * size of the data element, e.g., an 11-bit integer can be defined * using H5Tset_precision(). To a certain extent, SZIP can take * advantage of the precision of the datatype to improve compression: * - If the HDF5 datatype size is 24-bit or less and the offset of * the bits in the HDF5 datatype is zero (see H5Tset_offset() or * H5Tget_offset()), the data is the in lowest N bits of the data * element. In this case, the SZIP \p bits_per_pixel is set to the * precision of the HDF5 datatype. * - If the offset is not zero, the SZIP \p bits_per_pixel will be * set to the number of bits in the full size of the data element. * - If the HDF5 datatype precision is 25-bit to 32-bit, the SZIP * \p bits_per_pixel will be set to 32. * - If the HDF5 datatype precision is 33-bit to 64-bit, the SZIP * \p bits_per_pixel will be set to 64. * * \note HDF5 always modifies the options mask provided by the user to set up * usage of RAW_OPTION_MASK, ALLOW_K13_OPTION_MASK, and one of * LSB_OPTION_MASK or MSB_OPTION_MASK, depending on endianness of the * datatype. * * \since 1.6.0 * */ H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name, const char *src_dset_name, hid_t src_space_id); /* Dataset access property list (DAPL) routines */ /** * \ingroup DAPL * * \brief Retrieves the values of the append property that is set up in * the dataset access property list * * \dapl_id * \param[in] dims The number of elements for \p boundary * \param[in] boundary The dimension sizes used to determine the boundary * \param[in] func The user-defined callback function * \param[in] udata The user-defined input data * * \return \herr_t * * \details H5Pget_append_flush() obtains the following information * from the dataset access property list, \p dapl_id. * * \p boundary consists of the sizes set up in the access * property list that are used to determine when a dataset * dimension size hits the boundary. Only at most \p dims * boundary sizes are retrieved, and \p dims will not exceed * the corresponding value that is set in the property list. * * \p func is the user-defined callback function to invoke when * a dataset’s appended dimension size reaches a boundary and * \p udata is the user-defined input data for the callback * function. * * \todo Example Usage was removed and needs to be re-added * * \since 1.10.0 * */ H5_DLL herr_t H5Pget_append_flush(hid_t dapl_id, unsigned dims, hsize_t boundary[], H5D_append_cb_t *func, void **udata); /** * \ingroup DAPL * * \brief Retrieves the raw data chunk cache parameters * * \dapl_id * \param[out] rdcc_nslots Number of chunk slots in the raw data chunk * cache hash table * \param[out] rdcc_nbytes Total size of the raw data chunk cache, in * bytes * \param[out] rdcc_w0 Preemption policy * * \return \herr_t * * \details H5Pget_chunk_cache() retrieves the number of chunk slots in * the raw data chunk cache hash table, the maximum possible * number of bytes in the raw data chunk cache, and the * preemption policy value. * * These values are retrieved from a dataset access property * list. If the values have not been set on the property list, * then values returned will be the corresponding values from * a default file access property list. * * Any (or all) pointer arguments may be null pointers, in which * case the corresponding data is not returned. * * \since 1.8.3 * */ H5_DLL herr_t H5Pget_chunk_cache(hid_t dapl_id, size_t *rdcc_nslots/*out*/, size_t *rdcc_nbytes/*out*/, double *rdcc_w0/*out*/); /** * \ingroup DAPL * * \brief Retrieves the prefix for external raw data storage files as set * in the dataset access property list * * \dapl_id * \param[in,out] prefix Dataset external storage prefix in UTF-8 or * ASCII (\em Path and \em filename must be ASCII * on Windows systems.) * \param[in] size Size of prefix buffer in bytes * * \return Returns the size of \p prefix and the prefix string will be * stored in \p prefix if successful. * Otherwise returns a negative value and the contents of \p prefix * will be undefined. * * \details H5Pget_efile_prefix() retrieves the file system path prefix * for locating external files associated with a dataset that * uses external storage. This will be the value set with * H5Pset_efile_prefix() or the HDF5 library’s default. * * The value of \p size is the size in bytes of the prefix, * including the NULL terminator. If the size is unknown, a * preliminary H5Pget_elink_prefix() call with the pointer * \p prefix set to NULL will return the size of the prefix * without the NULL terminator. * * The \p prefix buffer must be allocated by the caller. In a * call that retrieves the actual prefix, that buffer must be * of the size specified in \p size. * * \note See H5Pset_efile_prefix() for a more complete description of * file location behavior and for notes on the use of the * HDF5_EXTFILE_PREFIX environment variable. * * \since 1.10.0, 1.8.17 * */ H5_DLL ssize_t H5Pget_efile_prefix(hid_t dapl_id, char* prefix /*out*/, size_t size); /** * \ingroup DAPL * * \brief Retrieves prefix applied to VDS source file paths * * \dapl_id * \param[out] prefix Prefix applied to VDS source file paths * \param[in] size Size of prefix, including null terminator * * \return If successful, returns a non-negative value specifying the size * in bytes of the prefix without the NULL terminator; otherwise * returns a negative value. * * \details H5Pget_virtual_prefix() retrieves the prefix applied to the * path of any VDS source files traversed. * * When an VDS source file is traversed, the prefix is retrieved * from the dataset access property list \p dapl_id, returned * in the user-allocated buffer pointed to by \p prefix, and * prepended to the filename stored in the VDS virtual file, set * with H5Pset_virtual(). * * The size in bytes of the prefix, including the NULL terminator, * is specified in \p size. If \p size is unknown, a preliminary * H5Pget_virtual_prefix() call with the pointer \p prefix set to * NULL will return the size of the prefix without the NULL * terminator. * * \virtual * * \since 1.10.2 * */ H5_DLL ssize_t H5Pget_virtual_prefix(hid_t dapl_id, char* prefix /*out*/, size_t size); /** * \ingroup DAPL * * \brief Returns the maximum number of missing source files and/or datasets * with the printf-style names when getting the extent for an unlimited * virtual dataset * * \dapl_id * \param[out] gap_size Maximum number of the files and/or datasets * allowed to be missing for determining the extent * of an unlimited virtual dataset with printf-style * mappings. (\em Default: 0) * * \return \herr_t * * \details H5Pget_virtual_printf_gap() returns the maximum number of * missing printf-style files and/or datasets for determining the * extent of an unlimited virtual dataaset, \p gap_size, using * the access property list for the virtual dataset, \p dapl_id. * * The default library value for \p gap_size is 0 (zero). * * \since 1.10.0 * */ H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t dapl_id, hsize_t *gap_size); /** * \ingroup DAPL * * \brief Retrieves the view of a virtual dataset accessed with * \p dapl_id * * \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 * * \details H5Pget_virtual_view() takes the virtual dataset access property * list, \p dapl_id, and retrieves the flag, \p view, set by the * H5Pset_virtual_view() call. * * \virtual * * \since 1.10.0 * */ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); /** * \ingroup DAPL * * \brief Sets two actions to perform when the size of a dataset’s * dimension being appended reaches a specified boundary * * \dapl_id * \param[in] ndims The number of elements for boundary * \param[in] boundary The dimension sizes used to determine the boundary * \param[in] func The user-defined callback function * \param[in] udata The user-defined input data * * \return \herr_t * * \details H5Pset_append_flush() sets the following two actions to * perform for a dataset associated with the dataset access * property list \p dapl_id: * * \li Call the callback function \p func set in the property * list * \li Flush the dataset associated with the dataset access * property list * * When a user is appending data to a dataset via H5DOappend() * and the dataset’s newly extended dimension size hits a * specified boundary, the library will perform the first action * listed above. Upon return from the callback function, the * library will then perform the second action listed above and * return to the user. If no boundary is hit or set, the two * actions above are not invoked. * * The specified boundary is indicated by the parameter * \p boundary. It is a 1-dimensional array with \p ndims * elements, which should be the same as the rank of the * dataset’s dataspace. While appending to a dataset along a * particular dimension index via H5DOappend(), the library * determines a boundary is reached when the resulting dimension * size is divisible by \p boundary[index]. A zero value for * \p boundary[index] indicates no boundary is set for that * dimension index. * * The setting of this property will apply only for a chunked * dataset with an extendible dataspace. A dataspace is extendible * when it is defined with either one of the following: * * \li A dataspace with fixed current and maximum dimension sizes * \li A dataspace with at least one unlimited dimension for its * maximum dimension size * * When creating or opening a chunked dataset, the library will * check whether the boundary as specified in the access property * list is set up properly. The library will fail the dataset * create or open if the following conditions are true: * * \li \p ndims, the number of elements for boundary, is not the * same as the rank of the dataset’s dataspace. * \li A non-zero boundary value is specified for a non-extendible * dimension. * * The callback function \p func must conform to the following * prototype: * \Code{typedef herr_t (#H5D_append_cb_t)(hid_t dataset_id, * hsize_t *cur_dims, void *user_data)} * * The parameters of the callback function, per the above * prototype, are defined as follows: * * \li \p dataset_id is the dataset identifier. * \li \p cur_dims is the dataset’s current dimension sizes when * a boundary is hit. * \li \p user_data is the user-defined input data. * * \todo Example Usage was removed and should be added back. * \todo Adding snippet for H5D_append_cb_t_snip did not work. * \todo H5DOappend() not found * * \since 1.10.0 * */ H5_DLL herr_t H5Pset_append_flush(hid_t dapl_id, unsigned ndims, const hsize_t boundary[], H5D_append_cb_t func, void *udata); /** * \ingroup DAPL * * \brief Sets the raw data chunk cache parameters * * \dapl_id * \param[in] rdcc_nslots The number of chunk slots in the raw data chunk * cache for this dataset. Increasing this value * reduces the number of cache collisions, but * slightly increases the memory used. Due to the * hashing strategy, this value should ideally be a * prime number. As a rule of thumb, this value * should be at least 10 times the number of chunks * that can fit in \p rdcc_nbytes bytes. For maximum * performance, this value should be set * approximately 100 times that number of chunks. * The default value is 521. If the value passed is * #H5D_CHUNK_CACHE_NSLOTS_DEFAULT, then the * property will not be set on \p dapl_id and the * parameter will come from the file access * property list used to open the file. * \param[in] rdcc_nbytes The total size of the raw data chunk cache for * this dataset. In most cases increasing this * number will improve performance, as long as * you have enough free memory. * The default size is 1 MB. If the value passed is * #H5D_CHUNK_CACHE_NBYTES_DEFAULT, then the * property will not be set on \p dapl_id and the * parameter will come from the file access * property list. * \param[in] rdcc_w0 The chunk preemption policy for this dataset. * This must be between 0 and 1 inclusive and * indicates the weighting according to which chunks * which have been fully read or written are * penalized when determining which chunks to flush * from cache. A value of 0 means fully read or * written chunks are treated no differently than * other chunks (the preemption is strictly LRU) * while a value of 1 means fully read or written * chunks are always preempted before other chunks. * If your application only reads or writes data * once, this can be safely set to 1. Otherwise, * this should be set lower, depending on how often * you re-read or re-write the same data. * The default value is 0.75. If the value passed is * #H5D_CHUNK_CACHE_W0_DEFAULT, then the property * will not be set on \p dapl_id and the parameter * will come from the file access property list. * * \return \herr_t * * \details H5Pset_chunk_cache() sets the number of elements, the total * number of bytes, and the preemption policy value in the raw * data chunk cache on a dataset access property list. After * calling this function, the values set in the property list * will override the values in the file's file access property * list. * * The raw data chunk cache inserts chunks into the cache * by first computing a hash value using the address of a chunk, * then using that hash value as the chunk's index into the table * of cached chunks. The size of this hash table, i.e., and the * number of possible hash values, is determined by the * \p rdcc_nslots parameter. If a different chunk in the cache * has the same hash value, this causes a collision, which * reduces efficiency. If inserting the chunk into cache would * cause the cache to be too big, then the cache is pruned * according to the \p rdcc_w0 parameter. * * \note \b Motivation: H5Pset_chunk_cache() is used to adjust the chunk * cache parameters on a per-dataset basis, as opposed to a global * setting for the file using H5Pset_cache(). The optimum chunk * cache parameters may vary widely with different data layout and * access patterns, so for optimal performance they must be set * individually for each dataset. It may also be beneficial to * reduce the size of the chunk cache for datasets whose * performance is not important in order to save memory space. * * \note \b Example \b Usage: The following code sets the chunk cache to * use a hash table with 12421 elements and a maximum size of * 16 MB, while using the preemption policy specified for the * entire file: * \Code{ * H5Pset_chunk_cache(dapl_id, 12421, 16*1024*1024, * H5D_CHUNK_CACHE_W0_DEFAULT);} * * \note \b Usage \b Notes: The chunk cache size is a property for * accessing a dataset and is not stored with a dataset or a * file. To guarantee the same chunk cache settings each time * the dataset is opened, call H5Dopen() with a dataset access * property list where the chunk cache size is set by calling * H5Pset_chunk_cache() for that property list. The property * list can be used for multiple accesses in the same * application. * * \note For files where the same chunk cache size will be * appropriate for all or most datasets, H5Pset_cache() can * be called with a file access property list to set the * chunk cache size for accessing all datasets in the file. * * \note Both methods can be used in combination, in which case * the chunk cache size set by H5Pset_cache() will apply * except for specific datasets where H5Dopen() is called * with dataset property list with the chunk cache size * set by H5Pset_chunk_cache(). * * \note In the absence of any cache settings, H5Dopen() will * by default create a 1 MB chunk cache for the opened * dataset. If this size happens to be appropriate, no * call will be needed to either function to set the * chunk cache size. * * \note It is also possible that a change in access pattern * for later access to a dataset will change the * appropriate chunk cache size. * * \since 1.8.3 * */ H5_DLL herr_t H5Pset_chunk_cache(hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0); /** * \ingroup DAPL * * \brief Sets the external dataset storage file prefix in the dataset * access property list * * \dapl_id * \param[in] prefix Dataset external storage prefix in UTF-8 or ASCII * (Path and filename must be ASCII on Windows systems.) * * \return \herr_t * * \details H5Pset_efile_prefix() sets the prefix used to locate raw data * files for a dataset that uses external storage. This prefix * can provide either an absolute path or a relative path to the * external files. * * H5Pset_efile_prefix() is used in conjunction with * H5Pset_external() to control the behavior of the HDF5 library * when searching for the raw data files associated with a dataset * that uses external storage: * * \li The default behavior of the library is to search for the * dataset’s external storage raw data files in the same * directory as the HDF5 file which contains the dataset. * \li If the prefix is set to an absolute path, the target * directory will be searched for the dataset’s external * storage raw data files. * \li If the prefix is set to a relative path, the target * directory, relative to the current working directory, will * be searched for the dataset’s external storage raw data * files. * \li If the prefix is set to a relative path that begins with * the special token ${ORIGIN}, that directory, relative to * the HDF5 file containing the dataset, will be searched for * the dataset’s external storage raw data files. * * The HDF5_EXTFILE_PREFIX environment variable can be used to * override the above behavior (the environment variable * supersedes the API call). Setting the variable to a path * string and calling H5Dcreate() or H5Dopen() is the equivalent * of calling H5Pset_efile_prefix() and calling the same create * or open function. The environment variable is checked at the * time of the create or open action and copied so it can be * safely changed after the H5Dcreate() or H5Dopen() call. * * Calling H5Pset_efile_prefix() with \p prefix set to NULL or * the empty string returns the search path to the default. The * result would be the same as if H5Pset_efile_prefix() had never * been called. * * \note If the external file prefix is not an absolute path and the HDF5 * file is moved, the external storage files will also need to be * moved so they can be accessed at the new location. * * \note As stated above, the use of the HDF5_EXTFILE_PREFIX environment * variable overrides any property list setting. * H5Pset_efile_prefix() and H5Pget_efile_prefix(), being property * functions, set and retrieve only the property list setting; they * are unaware of the environment variable. * * \note On Windows, the prefix must be an ASCII string since the Windows * standard C library’s I/O functions cannot handle UTF-8 file names. * * \since 1.10.0, 1.8.17 * */ H5_DLL herr_t H5Pset_efile_prefix(hid_t dapl_id, const char* prefix); /** * \ingroup DAPL * * \brief Sets prefix to be applied to VDS source file paths * * \dapl_id * \param[in] prefix Prefix to be applied to VDS source file paths * * \return \herr_t * * \details H5Pset_virtual_prefix() sets the prefix to be applied to the * path of any VDS source files traversed. The prefix is prepended * to the filename stored in the VDS virtual file, set with * H5Pset_virtual(). * * The prefix is specified in the user-allocated buffer \p prefix * and set in the dataset access property list \p dapl_id. The * buffer should not be freed until the property list has been * closed. * * \virtual * * \since 1.10.2 * */ H5_DLL herr_t H5Pset_virtual_prefix(hid_t dapl_id, const char* prefix); /** * \ingroup DAPL * * \brief Sets the maximum number of missing source files and/or datasets * with the printf-style names when getting the extent of an * unlimited virtual dataset * * \dapl_id * \param[in] gap_size Maximum number of files and/or datasets allowed to * be missing for determining the extent of an * unlimited virtual dataset with printf-style * mappings (Default value: 0) * * \return \herr_t * * \details H5Pset_virtual_printf_gap() sets the access property list for * the virtual dataset, \p dapl_id, to instruct the library to * stop looking for the mapped data stored in the files and/or * datasets with the printf-style names after not finding * \p gap_size files and/or datasets. The found source files and * datasets will determine the extent of the unlimited virtual * dataset with the printf-style mappings. * * Consider the following examples where the regularly spaced * blocks of a virtual dataset are mapped to datasets with the * names d-1, d-2, d-3, ..., d-N, ... : * * \li If the dataset d-2 is missing and \p gap_size is set to 0, * then the virtual dataset will contain only data found * in d-1. * \li If d-2 and d-3 are missing and \p gap_size is set to 2, * then the virtual dataset will contain the data from * d-1, d-3, ..., d-N, ... . The blocks that are mapped to * d-2 and d-3 will be filled according to the virtual * dataset’s fill value setting. * * \virtual * * \since 1.10.0 * */ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); /** * \ingroup DAPL * * \brief Sets the view of the virtual dataset (VDS) to include or exclude * missing mapped elements * * \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 * * \return \herr_t * * \details H5Pset_virtual_view() takes the access property list for the * virtual dataset, \p dapl_id, and the flag, \p view, and sets * the VDS view according to the flag value. * * If \p view is set to #H5D_VDS_FIRST_MISSING, the view includes * all data before the first missing mapped data. This setting * provides a view containing only the continuous data starting * with the dataset’s first data element. Any break in * continuity terminates the view. * * If \p view is set to #H5D_VDS_LAST_AVAILABLE, the view * includes all available mapped data. * * Missing mapped data is filled with the fill value set in the * VDS creation property list. * * \virtual * * \since 1.10.0 * */ H5_DLL herr_t H5Pset_virtual_view(hid_t dapl_id, H5D_vds_view_t view); /* Dataset xfer property list (DXPL) routines */ H5_DLL herr_t H5Pget_btree_ratios(hid_t plist_id, double *left/*out*/, double *middle/*out*/, double *right/*out*/); H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv/*out*/, void **bkg/*out*/); /** * * \ingroup DXPL * * \brief Retrieves a data transform expression * * \param[in] plist_id Identifier of the property list or class * \param[out] expression Pointer to memory where the transform expression * will be copied * \param[in] size Number of bytes of the transform expression to copy to * * \return Returns the size of the transform expression if successful; * otherwise returns a negative value. * * \details H5Pget_data_transform() retrieves the data transform * expression previously set in the dataset transfer property * list \p plist_id by H5Pset_data_transform(). * * H5Pget_data_transform() can be used to both retrieve the * transform expression and to query its size. * * If \p expression is non-NULL, up to \p size bytes of the data * transform expression are written to the buffer. If * \p expression is NULL, \p size is ignored and the function * does not write anything to the buffer. The function always * returns the size of the data transform expression. * * If 0 is returned for the size of the expression, no data * transform expression exists for the property list. * * If an error occurs, the buffer pointed to by \p expression is * unchanged and the function returns a negative value. * * \since 1.8.0 * */ H5_DLL ssize_t H5Pget_data_transform(hid_t plist_id, char* expression /*out*/, size_t size); H5_DLL H5Z_EDC_t H5Pget_edc_check(hid_t plist_id); H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size/*out*/); H5_DLL int H5Pget_preserve(hid_t plist_id); H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void** operate_data); 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); H5_DLL herr_t H5Pset_btree_ratios(hid_t plist_id, double left, double middle, double right); H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *bkg); /** * \ingroup DXPL * * \brief Sets a data transform expression * * \param[in] plist_id Identifier of the property list or class * \param[in] expression Pointer to the null-terminated data transform * expression * * \return \herr_t * * \details H5Pset_data_transform() sets the data transform to be used for * reading and writing data. This function operates on the dataset * transfer property list \p plist_id. * * The \p expression parameter is a string containing an algebraic * expression, such as (5/9.0)*(x-32) or x*(x-5). When a dataset * is read or written with this property list, the transform * expression is applied with the x being replaced by the values * in the dataset. When reading data, the values in the file are * not changed and the transformed data is returned to the user. * * Data transforms can only be applied to integer or * floating-point datasets. Order of operations is obeyed and * the only supported operations are +, -, *, and /. Parentheses * can be nested arbitrarily and can be used to change precedence. * When writing data back to the dataset, the transformed data is * written to the file and there is no way to recover the original * values to which the transform was applied. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_data_transform(hid_t plist_id, const char* expression); H5_DLL herr_t H5Pset_edc_check(hid_t plist_id, H5Z_EDC_t check); H5_DLL herr_t H5Pset_filter_callback(hid_t plist_id, H5Z_filter_func_t func, void* op_data); H5_DLL herr_t H5Pset_hyper_vector_size(hid_t fapl_id, size_t size); H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void* operate_data); 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); #ifdef H5_HAVE_PARALLEL H5_DLL herr_t H5Pget_mpio_actual_chunk_opt_mode(hid_t plist_id, H5D_mpio_actual_chunk_opt_mode_t *actual_chunk_opt_mode); H5_DLL herr_t H5Pget_mpio_actual_io_mode(hid_t plist_id, H5D_mpio_actual_io_mode_t *actual_io_mode); H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no_collective_cause, uint32_t *global_no_collective_cause); #endif /* H5_HAVE_PARALLEL */ /* Link creation property list (LCPL) routines */ H5_DLL herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd); H5_DLL herr_t H5Pget_create_intermediate_group(hid_t plist_id, unsigned *crt_intmd /*out*/); /* Group creation property list (GCPL) routines */ H5_DLL herr_t H5Pset_local_heap_size_hint(hid_t plist_id, size_t size_hint); H5_DLL herr_t H5Pget_local_heap_size_hint(hid_t plist_id, size_t *size_hint /*out*/); H5_DLL herr_t H5Pset_link_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); H5_DLL herr_t H5Pget_link_phase_change(hid_t plist_id, unsigned *max_compact /*out*/, unsigned *min_dense /*out*/); H5_DLL herr_t H5Pset_est_link_info(hid_t plist_id, unsigned est_num_entries, unsigned est_name_len); H5_DLL herr_t H5Pget_est_link_info(hid_t plist_id, unsigned *est_num_entries /* out */, unsigned *est_name_len /* out */); H5_DLL herr_t H5Pset_link_creation_order(hid_t plist_id, unsigned crt_order_flags); H5_DLL herr_t H5Pget_link_creation_order(hid_t plist_id, unsigned *crt_order_flags /* out */); /* Map access property list (MAPL) routines */ #ifdef H5_HAVE_MAP_API H5_DLL herr_t H5Pset_map_iterate_hints(hid_t mapl_id, size_t key_prefetch_size, size_t key_alloc_size); H5_DLL herr_t H5Pget_map_iterate_hints(hid_t mapl_id, size_t *key_prefetch_size /*out*/, size_t *key_alloc_size /*out*/); #endif /* H5_HAVE_MAP_API */ /* String creation property list (STRCPL) routines */ H5_DLL herr_t H5Pset_char_encoding(hid_t plist_id, H5T_cset_t encoding); H5_DLL herr_t H5Pget_char_encoding(hid_t plist_id, H5T_cset_t *encoding /*out*/); /* Link access property list (LAPL) routines */ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); H5_DLL herr_t H5Pget_nlinks(hid_t plist_id, size_t *nlinks); H5_DLL herr_t H5Pset_elink_prefix(hid_t plist_id, const char *prefix); H5_DLL ssize_t H5Pget_elink_prefix(hid_t plist_id, char *prefix, size_t size); H5_DLL hid_t H5Pget_elink_fapl(hid_t lapl_id); H5_DLL herr_t H5Pset_elink_fapl(hid_t lapl_id, hid_t fapl_id); H5_DLL herr_t H5Pset_elink_acc_flags(hid_t lapl_id, unsigned flags); H5_DLL herr_t H5Pget_elink_acc_flags(hid_t lapl_id, unsigned *flags); H5_DLL herr_t H5Pset_elink_cb(hid_t lapl_id, H5L_elink_traverse_t func, void *op_data); H5_DLL herr_t H5Pget_elink_cb(hid_t lapl_id, H5L_elink_traverse_t *func, void **op_data); /* Object copy property list (OCPYPL) routines */ H5_DLL herr_t H5Pset_copy_object(hid_t plist_id, unsigned crt_intmd); H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *crt_intmd /*out*/); H5_DLL herr_t H5Padd_merge_committed_dtype_path(hid_t plist_id, const char *path); H5_DLL herr_t H5Pfree_merge_committed_dtype_paths(hid_t plist_id); H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, void *op_data); H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, void **op_data); /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. */ #ifndef H5_NO_DEPRECATED_SYMBOLS /* Macros */ /* We renamed the "root" of the property list class hierarchy */ #define H5P_NO_CLASS H5P_ROOT /* Typedefs */ /* Function prototypes */ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close); H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close); H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc); /** * \ingroup OCPL * * \brief Returns information about a filter in a pipeline (DEPRECATED) * * \todo H5Pget_filter1() prototype does not match source in H5Pocpl.c. * Also, it is not in a deprecated file. Is that okay? * * \plist_id{plist_id} * \param[in] filter Sequence number within the filter pipeline of the filter * for which information is sought * \param[out] flags Bit vector specifying certain general properties of * the filter * \param[in,out] cd_nelmts Number of elements in \p cd_values * \param[out] cd_values Auxiliary data for the filter * \param[in] namelen Anticipated number of characters in \p name * \param[out] name Name of the filter * * \return Returns the filter identifier if successful; Otherwise returns * a negative value. See: #H5Z_filter_t * * \details H5Pget_filter1() returns information about a filter, specified * by its filter number, in a filter pipeline, specified by the * property list with which it is associated. * * \p plist_id must be a dataset or group creation property list. * * \p filter is a value between zero and N-1, as described in * H5Pget_nfilters(). The function will return a negative value * if the filter number is out of range. * * The structure of the \p flags argument is discussed in * H5Pset_filter(). * * On input, \p cd_nelmts indicates the number of entries in the * \p cd_values array, as allocated by the caller; on return, * \p cd_nelmts contains the number of values defined by the filter. * * If \p name is a pointer to an array of at least \p namelen * bytes, the filter name will be copied into that array. The name * will be null terminated if \p namelen is large enough. The * filter name returned will be the name appearing in the file, the * name registered for the filter, or an empty string. * * \version 1.8.5 Function extended to work with group creation property * lists. * \version 1.8.0 N-bit and scale-offset filters added. * \version 1.8.0 Function H5Pget_filter() renamed to H5Pget_filter1() and * deprecated in this release. * \version 1.6.4 \p filter parameter type changed to unsigned. * */ H5_DLL H5Z_filter_t H5Pget_filter1(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[]); H5_DLL herr_t H5Pget_filter_by_id1(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[] /*out*/); H5_DLL herr_t H5Pget_version(hid_t plist_id, unsigned *boot /*out*/, unsigned *freelist /*out*/, unsigned *stab /*out*/, unsigned *shhdr /*out*/); H5_DLL herr_t H5Pset_file_space(hid_t plist_id, H5F_file_space_type_t strategy, hsize_t threshold); H5_DLL herr_t H5Pget_file_space(hid_t plist_id, H5F_file_space_type_t *strategy, hsize_t *threshold); #endif /* H5_NO_DEPRECATED_SYMBOLS */ #ifdef __cplusplus } #endif #endif /* _H5Ppublic_H */