Merge branch 'master' of ssh://git.indexdata.com/home/git/pub/idzebra
[idzebra-moved-to-github.git] / include / idzebra / bfile.h
1 /* This file is part of the Zebra server.
2    Copyright (C) Index Data
3
4 Zebra is free software; you can redistribute it and/or modify it under
5 the terms of the GNU General Public License as published by the Free
6 Software Foundation; either version 2, or (at your option) any later
7 version.
8
9 Zebra is distributed in the hope that it will be useful, but WITHOUT ANY
10 WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
12 for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
17
18 */
19
20 /** \file bfile.h
21     \brief Zebra Block File Layer
22
23     Providers an interface to a file system , AKA persistent storage.
24     The interface allows safe updates - using a shadow file facility.
25 */
26
27 #ifndef BFILE_H
28 #define BFILE_H
29
30 #include <yaz/yconfig.h>
31 #include <idzebra/util.h>
32
33 YAZ_BEGIN_CDECL
34
35 /** \var BFiles
36     \brief A collection of BFile(s).
37 */
38 typedef struct BFiles_struct *BFiles;
39
40 /** \var BFile
41     \brief A Block File
42 */
43 typedef struct BFile_struct *BFile;
44
45 /** \brief creates a Block files collection
46     \param spec register specification , e.g. "d1:100M d2:1G"
47     \param base base directory for register spec (if that is relative path)
48     \return block files handle
49 */
50 BFiles bfs_create (const char *spec, const char *base);
51
52 /** \brief destroys a block files handle
53     \param bfiles block files handle
54
55     The files in the block files collection are not deleted. Only the
56     handle is freed.
57 */
58 void bfs_destroy (BFiles bfiles);
59
60 /** \brief closes a Block file (may call exit)
61     \param bf block file
62  */
63 YAZ_EXPORT
64 void bf_close(BFile bf);
65
66 /** \brief closes a Block file
67     \param bf block file
68     \retval 0 success
69     \retval -1 failure
70  */
71 YAZ_EXPORT
72 int bf_close2(BFile bf);
73
74 /** \brief closes an extended Block file handle..
75     \param bf extended block file opened with bf_xopen
76     \param version version to be put in a file
77     \param more_info more information to be stored in file (header)
78     \retval 0 success
79     \retval -1 failure (can never happen as the code is now)
80 */
81 YAZ_EXPORT
82 int bf_xclose(BFile bf, int version, const char *more_info);
83
84 /** \brief opens and returns a Block file handle
85     \param bfs block files
86     \param name filename
87     \param block_size block size in bytes
88     \param wflag 1=opened for read&write, 0=read only
89     \retval 0 success
90     \retval -1 failure (can never happen as the code is now)
91 */
92 YAZ_EXPORT
93 BFile bf_open(BFiles bfs, const char *name, int block_size, int wflag);
94
95 /** \brief opens and returns an extended Block file handle
96     \param bfs block files
97     \param name filename
98     \param block_size block size in bytes
99     \param wflag 1=opened for read&write, 0=read only
100     \param magic magic string to be used for file
101     \param read_version holds after completion of bf_xopen the version
102     \param more_info holds more_info as read from file (header)
103 */
104 YAZ_EXPORT
105 BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wflag,
106                const char *magic, int *read_version,
107                const char **more_info);
108
109 /** \brief read from block file (may call exit)
110     \param bf block file handle
111     \param no block no (first block is 0, second is 1..)
112     \param offset offset within block to be read
113     \param nbytes number of bytes to read (0 for whole block)
114     \param buf raw bytes with content (at least nbytes of size)
115     \retval 1 whole block could be read
116     \retval 0 whole block could not be read
117  */
118 YAZ_EXPORT
119 int bf_read(BFile bf, zint no, int offset, int nbytes, void *buf);
120
121 /** \brief read from block file
122     \param bf block file handle
123     \param no block no (first block is 0, second is 1..)
124     \param offset offset within block to be read
125     \param nbytes number of bytes to read (0 for whole block)
126     \param buf raw bytes with content (at least nbytes of size)
127     \retval 1 whole block could be read
128     \retval 0 whole block could not be read
129     \retval -1 error
130  */
131 YAZ_EXPORT
132 int bf_read2(BFile bf, zint no, int offset, int nbytes, void *buf)
133     ZEBRA_GCC_ATTR((warn_unused_result));
134
135
136 /** \brief writes block of bytes to file (may call exit)
137     \param bf block file handle
138     \param no block no
139     \param offset within block
140     \param nbytes number of bytes to write
141     \param buf buffer to write
142     \retval 0 success (block could be written)
143
144     This function can not return a failure. System calls exit(1)
145     if write failed.
146  */
147 YAZ_EXPORT
148 int bf_write(BFile bf, zint no, int offset, int nbytes, const void *buf);
149
150
151 /** \brief writes block of bytes to file
152     \param bf block file handle
153     \param no block no
154     \param offset within block
155     \param nbytes number of bytes to write
156     \param buf buffer to write
157     \retval 0 success (block written)
158     \retval -1 error
159
160     This function can not return a failure. System calls exit(1)
161     if write failed.
162  */
163 YAZ_EXPORT
164 int bf_write2(BFile bf, zint no, int offset, int nbytes, const void *buf)
165     ZEBRA_GCC_ATTR((warn_unused_result));
166
167 /** \brief enables or disables shadow for block files
168     \param bfs block files
169     \param spec  such as  "shadow:100M /other:200M"; or NULL to disable
170     \retval ZEBRA_OK successful. spec is OK
171     \retval ZEBRA_FAIL failure.
172 */
173 YAZ_EXPORT
174 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
175
176 /** \brief Check if there is content in shadow area (to be committed).
177     \param bfs block files
178     \retval 1 there is content in shadow area
179     \retval 0 no content in shadow area
180 */
181 YAZ_EXPORT
182 int bf_commitExists (BFiles bfs);
183
184 /** \brief Executes commit operation
185     \param bfs block files
186 */
187 YAZ_EXPORT
188 int bf_commitExec (BFiles bfs) ZEBRA_GCC_ATTR((warn_unused_result));
189
190 /** \brief Cleans shadow files (remove them)
191     \param bfs block files
192     \param spec shadow specification
193 */
194 YAZ_EXPORT
195 void bf_commitClean (BFiles bfs, const char *spec);
196
197 /** \brief Removes register and shadow completely
198     \param bfs block files
199 */
200 YAZ_EXPORT
201 void bf_reset (BFiles bfs);
202
203 /** \brief Allocates one or more blocks in an extended block file
204     \param bf extended block file
205     \param no number of blocks to allocate
206     \param blocks output array of size no with block offsets
207 */
208 YAZ_EXPORT
209 int bf_alloc(BFile bf, int no, zint *blocks);
210
211 /** \brief Releases one or more blocks in an extended block file
212     \param bf extended block file
213     \param no numer of blocks to release
214     \param blocks input array with block offsets (IDs) to release
215 */
216 YAZ_EXPORT
217 int bf_free(BFile bf, int no, const zint *blocks);
218
219
220 /* \brief gets statistics about directory in register area
221    \param bfs block files
222    \param no directory number (0=first, 1=second,...)
223    \param directory holds directory name (if found)
224    \param used_bytes used file bytes in directory (if found)
225    \param max_bytes max usage of bytes (if found)
226    \retval 1 no is within range and directory, used, max are set.
227    \retval 0 no is out of range and directory, used, max are unset
228
229    We are using double, because off_t may have a different size
230    on same platform depending on whether 64-bit is enabled or not.
231    Note that if a register area has unlimited size, that is represented
232    as max_bytes = -1.
233
234 */
235 YAZ_EXPORT
236 int bfs_register_directory_stat(BFiles bfs, int no, const char **directory,
237                                 double *used_bytes, double *max_bytes);
238
239 /* \brief gets statistics about directory in shadow area
240    \param bfs block files
241    \param no directory number (0=first, 1=second,...)
242    \param directory holds directory name (if found)
243    \param used_bytes used file bytes in directory (if found)
244    \param max_bytes max usage of bytes (if found)
245    \retval 1 no is within range and directory, used, max are set.
246    \retval 0 no is out of range and directory, used, max are unset
247
248    We are using double, because off_t may have a different size
249    on same platform depending on whether 64-bit is enabled or not.
250    Note that if a shadow area has unlimited size, that is represented
251    as max_bytes = -1.
252 */
253 YAZ_EXPORT
254 int bfs_shadow_directory_stat(BFiles bfs, int no, const char **directory,
255                               double *used_bytes, double *max_bytes);
256
257 YAZ_END_CDECL
258
259 #endif
260 /*
261  * Local variables:
262  * c-basic-offset: 4
263  * c-file-style: "Stroustrup"
264  * indent-tabs-mode: nil
265  * End:
266  * vim: shiftwidth=4 tabstop=8 expandtab
267  */
268