source/include/H5FDcore.h

0001 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
0002  * Copyright by The HDF Group.                                               *
0003  * All rights reserved.                                                      *
0004  *                                                                           *
0005  * This file is part of HDF5.  The full HDF5 copyright notice, including     *
0006  * terms governing use, modification, and redistribution, is contained in    *
0007  * the COPYING file, which can be found at the root of the source code       *
0008  * distribution tree, or in https://www.hdfgroup.org/licenses.               *
0009  * If you do not have access to either file, you may request a copy from     *
0010  * help@hdfgroup.org.                                                        *
0011  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
0012
0013 /*
0014  * Purpose: The public header file for the core virtual file driver (VFD)
0015  */
0016 #ifndef H5FDcore_H
0017 #define H5FDcore_H
0018
0019 /** Initializer for the core VFD */
0020 #define H5FD_CORE (H5FDperform_init(H5FD_core_init))
0021
0022 /** Identifier for the core VFD */
0023 #define H5FD_CORE_VALUE H5_VFD_CORE
0024
0025 #ifdef __cplusplus
0026 extern "C" {
0027 #endif
0028
0029 /** @private
0030  *
0031  * \brief Private initializer for the core VFD
0032  */
0033 H5_DLL hid_t H5FD_core_init(void);
0034
0035 /**
0036  * \ingroup FAPL
0037  *
0038  * \brief Modifies the file access property list to use the #H5FD_CORE driver
0039  *
0040  * \fapl_id
0041  * \param[in] increment Size, in bytes, of memory increments
0042  * \param[in] backing_store Boolean flag indicating whether to write the file
0043  *            contents to disk when the file is closed
0044  * \returns \herr_t
0045  *
0046  * \details H5Pset_fapl_core() modifies the file access property list to use the
0047  *          #H5FD_CORE driver.
0048  *
0049  *          The #H5FD_CORE driver enables an application to work with a file in
0050  *          memory, speeding reads and writes as no disk access is made. File
0051  *          contents are stored only in memory until the file is closed. The \p
0052  *          backing_store parameter determines whether file contents are ever
0053  *          written to disk.
0054  *
0055  *          \p increment specifies the increment by which allocated memory is to
0056  *          be increased each time more memory is required.
0057  *
0058  *          While using H5Fcreate() to create a core file, if the \p
0059  *          backing_store is set to 1 (true), the file contents are flushed to a
0060  *          file with the same name as this core file when the file is closed or
0061  *          access to the file is terminated in memory.
0062  *
0063  *          The application is allowed to open an existing file with #H5FD_CORE
0064  *          driver. While using H5Fopen() to open an existing file, if the \p
0065  *          backing_store is set to 1 (true) and the \c flags for H5Fopen() is set to
0066  *          #H5F_ACC_RDWR, any change to the file contents are saved to the file
0067  *          when the file is closed. If \p backing_store is set to 0 (false) and the \c
0068  *          flags for H5Fopen() is set to #H5F_ACC_RDWR, any change to the file
0069  *          contents will be lost when the file is closed. If the flags for
0070  *          H5Fopen() is set to #H5F_ACC_RDONLY, no change to the file is
0071  *          allowed either in memory or on file.
0072  *
0073  * \note Currently this driver cannot create or open family or multi files.
0074  *
0075  * \since 1.4.0
0076  *
0077  */
0078 H5_DLL herr_t H5Pset_fapl_core(hid_t fapl_id, size_t increment, hbool_t backing_store);
0079
0080 /**
0081  * \ingroup FAPL
0082  *
0083  * \brief Queries core file driver properties
0084  *
0085  * \fapl_id
0086  * \param[out] increment Size, in bytes, of memory increments
0087  * \param[out] backing_store Boolean flag indicating whether to write the file
0088  *             contents to disk when the file is closed
0089  * \returns \herr_t
0090  *
0091  * \details H5Pget_fapl_core() queries the #H5FD_CORE driver properties as set
0092  *          by H5Pset_fapl_core().
0093  *
0094  * \since 1.4.0
0095  *
0096  */
0097 H5_DLL herr_t H5Pget_fapl_core(hid_t fapl_id, size_t *increment /*out*/, hbool_t *backing_store /*out*/);
0098 #ifdef __cplusplus
0099 }
0100 #endif
0101
0102 #endif