1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* 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://www.hdfgroup.org/licenses. *
* If you do not have access to either file, you may request a copy from *
* help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
/*
* Onion Virtual File Driver (VFD)
*
* Purpose: The public header file for the Onion VFD.
*/
#ifndef H5FDonion_H
#define H5FDonion_H
#define H5FD_ONION (H5FDperform_init(H5FD_onion_init))
#define H5FD_ONION_VALUE H5_VFD_ONION
/**
* Current version of the onion VFD fapl info struct.
*/
#define H5FD_ONION_FAPL_INFO_VERSION_CURR 1
#define H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT \
(0x0001u) /**< \
* Onion history metadata will align to page_size. \
* Partial pages of unused space will occur in the file, \
* but may improve read performance from the backing store \
* on some systems. \
* If disabled (0), padding will not be inserted to align \
* to page boundaries. \
*/
/**
* Max length of a comment.
* The buffer is defined to be this size + 1 to handle the NUL.
*/
#define H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN 255
/**
* Indicates that you want the latest revision.
*/
#define H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST UINT64_MAX
/**
* Indicates how the new onion data will be stored.
*/
typedef enum H5FD_onion_target_file_constant_t {
H5FD_ONION_STORE_TARGET_ONION, /**<
* Onion history is stored in a single, separate "onion
* file". Shares filename and path as hdf5 file (if any),
* with only a different filename extension.
*/
} H5FD_onion_target_file_constant_t;
/**
* Stores fapl information for creating onion VFD files.
*/
typedef struct H5FD_onion_fapl_info_t {
uint8_t version; /**<
* Future-proofing identifier. Informs struct membership.
* Must equal H5FD_ONION_FAPL_VERSION_CURR to be considered valid.
*/
hid_t backing_fapl_id; /**<
* Backing or 'child' FAPL ID to handle I/O with the
* underlying backing store. It must use the same backing driver as the
* original file.
*/
uint32_t page_size; /**<
* page_size: Size of the amended data pages. If opening an existing file,
* must equal the existing page size or zero. If creating a new
* file or an initial revision of an existing file, must be a
* power of 2.
*
*/
H5FD_onion_target_file_constant_t store_target; /**<
* Identifies where the history data is stored.
*/
uint64_t revision_num; /**<
* Which revision to open. Valid values are 0 (the original file) or the
* revision number of an existing revision.
* H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST refers to the most
* recently-created revision in the history.
*/
uint8_t force_write_open; /**<
* Flag to ignore the write-lock flag in the onion data
* and attempt to open the file write-only anyway.
* This may be relevant if, for example, the library crashed
* while the file was open in write mode and the write-lock
* flag was not cleared.
* Must equal H5FD_ONION_FAPL_FLAG_FORCE_OPEN to enable.
*
*/
uint8_t creation_flags; /**<
* Flag used only when instantiating an onion file.
* If the relevant bit is set to a nonzero value, its feature
* will be enabled.
*/
char comment[H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN +
1]; /**<
* User-supplied NULL-terminated comment for a revision to be
* written.
* Cannot be longer than H5FD_ONION_FAPL_COMMENT_MAX_LEN.
* Ignored if part of a FAPL used to open in read mode.
*/
} H5FD_onion_fapl_info_t;
#ifdef __cplusplus
extern "C" {
#endif
H5_DLL hid_t H5FD_onion_init(void);
/**
* --------------------------------------------------------------------------
* \ingroup FAPL
*
* \brief get the onion info from the file access property list
*
* \fapl_id
* \param[out] fa_out The pointer to the structure H5FD_onion_fapl_info_t
*
* \return \herr_t
*
* \details H5Pget_fapl_onion() retrieves the structure H5FD_onion_fapl_info_t
* from the file access property list that is set for the onion VFD
* driver.
*
* \since 1.14.0
*/
H5_DLL herr_t H5Pget_fapl_onion(hid_t fapl_id, H5FD_onion_fapl_info_t *fa_out);
/**
* --------------------------------------------------------------------------
* \ingroup FAPL
*
* \brief set the onion info for the file access property list
*
* \fapl_id
* \param[in] fa The pointer to the structure H5FD_onion_fapl_info_t
*
* \return \herr_t
*
* \details H5Pset_fapl_onion() sets the structure H5FD_onion_fapl_info_t
* for the file access property list that is set for the onion VFD
* driver.
*
* \since 1.14.0
*/
H5_DLL herr_t H5Pset_fapl_onion(hid_t fapl_id, const H5FD_onion_fapl_info_t *fa);
/**
* --------------------------------------------------------------------------
* \ingroup H5FD
*
* \brief get the number of revisions
*
* \param[in] filename The name of the onion file
* \param[in] fapl_id The ID of the file access property list
* \param[out] revision_count The number of revisions
*
* \return \herr_t
*
* \details H5FDonion_get_revision_count() returns the number of revisions
* for an onion file. It takes the file name and file access property
* list that is set for the onion VFD driver.
*
*
* \since 1.14.0
*/
H5_DLL herr_t H5FDonion_get_revision_count(const char *filename, hid_t fapl_id, uint64_t *revision_count);
#ifdef __cplusplus
}
#endif
#endif /* H5FDonion_H */
|
