1 /* $Id: bfile.h,v 1.12 2006-11-14 08:12:07 adam Exp $
2 Copyright (C) 1995-2006
5 This file is part of the Zebra server.
7 Zebra is free software; you can redistribute it and/or modify it under
8 the terms of the GNU General Public License as published by the Free
9 Software Foundation; either version 2, or (at your option) any later
12 Zebra is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
14 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24 \brief Zebra Block File Layer
26 Providers an interface to a file system , AKA persistent storage.
27 The interface allows safe updates - using a shadow file facility.
33 #include <yaz/yconfig.h>
34 #include <idzebra/util.h>
39 \brief A collection of BFile(s).
41 typedef struct BFiles_struct *BFiles;
46 typedef struct BFile_struct *BFile;
48 /** \brief creates a Block files collection
49 \param spec register specification , e.g. "d1:100M d2:1G"
50 \param base base directory for register spec (if that is relative path)
51 \return block files handle
53 BFiles bfs_create (const char *spec, const char *base);
55 /** \brief destroys a block files handle
56 \param bfiles block files handle
58 The files in the block files collection are not deleted. Only the
61 void bfs_destroy (BFiles bfiles);
63 /** \brief closes a Block file (may call exit)
67 void bf_close(BFile bf);
69 /** \brief closes a Block file
75 int bf_close2(BFile bf);
77 /** \brief closes an extended Block file handle..
78 \param bf extended block file opened with bf_xopen
79 \param version version to be put in a file
80 \param more_info more information to be stored in file (header)
82 \retval -1 failure (can never happen as the code is now)
85 int bf_xclose(BFile bf, int version, const char *more_info);
87 /** \brief opens and returns a Block file handle
88 \param bfs block files
90 \param block_size block size in bytes
91 \param wflag 1=opened for read&write, 0=read only
93 \retval -1 failure (can never happen as the code is now)
96 BFile bf_open(BFiles bfs, const char *name, int block_size, int wflag);
98 /** \brief opens and returns an extended Block file handle
99 \param bfs block files
101 \param block_size block size in bytes
102 \param wflag 1=opened for read&write, 0=read only
103 \param magic magic string to be used for file
104 \param read_version holds after completion of bf_xopen the version
105 \param more_info holds more_info as read from file (header)
108 BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wflag,
109 const char *magic, int *read_version,
110 const char **more_info);
112 /** \brief read from block file (may call exit)
113 \param bf block file handle
114 \param no block no (first block is 0, second is 1..)
115 \param offset offset within block to be read
116 \param nbytes number of bytes to read (0 for whole block)
117 \param buf raw bytes with content (at least nbytes of size)
118 \retval 1 whole block could be read
119 \retval 0 whole block could not be read
122 int bf_read(BFile bf, zint no, int offset, int nbytes, void *buf);
124 /** \brief read from block file
125 \param bf block file handle
126 \param no block no (first block is 0, second is 1..)
127 \param offset offset within block to be read
128 \param nbytes number of bytes to read (0 for whole block)
129 \param buf raw bytes with content (at least nbytes of size)
130 \retval 1 whole block could be read
131 \retval 0 whole block could not be read
135 int bf_read2(BFile bf, zint no, int offset, int nbytes, void *buf)
136 ZEBRA_GCC_ATTR((warn_unused_result));
139 /** \brief writes block of bytes to file (may call exit)
140 \param bf block file handle
142 \param offset within block
143 \param nbytes number of bytes to write
144 \param buf buffer to write
145 \retval 0 success (block could be written)
147 This function can not return a failure. System calls exit(1)
151 int bf_write(BFile bf, zint no, int offset, int nbytes, const void *buf);
154 /** \brief writes block of bytes to file
155 \param bf block file handle
157 \param offset within block
158 \param nbytes number of bytes to write
159 \param buf buffer to write
160 \retval 0 success (block written)
163 This function can not return a failure. System calls exit(1)
167 int bf_write2(BFile bf, zint no, int offset, int nbytes, const void *buf)
168 ZEBRA_GCC_ATTR((warn_unused_result));
170 /** \brief enables or disables shadow for block files
171 \param bfs block files
172 \param spec such as "shadow:100M /other:200M"; or NULL to disable
173 \retval ZEBRA_OK successful. spec is OK
174 \retval ZEBRA_FAIL failure.
177 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
179 /** \brief Check if there is content in shadow area (to be committed).
180 \param bfs block files
181 \retval 1 there is content in shadow area
182 \retval 0 no content in shadow area
185 int bf_commitExists (BFiles bfs);
187 /** \brief Executes commit operation
188 \param bfs block files
191 int bf_commitExec (BFiles bfs) ZEBRA_GCC_ATTR((warn_unused_result));
193 /** \brief Cleans shadow files (remove them)
194 \param bfs block files
195 \param spec shadow specification
198 void bf_commitClean (BFiles bfs, const char *spec);
200 /** \brief Removes register and shadow completely
201 \param bfs block files
204 void bf_reset (BFiles bfs);
206 /** \brief Allocates one or more blocks in an extended block file
207 \param bf extended block file
208 \param no number of blocks to allocate
209 \param blocks output array of size no with block offsets
212 int bf_alloc(BFile bf, int no, zint *blocks);
214 /** \brief Releases one or more blocks in an extended block file
215 \param bf extended block file
216 \param no numer of blocks to release
217 \param blocks input array with block offsets (IDs) to release
220 int bf_free(BFile bf, int no, const zint *blocks);
223 /* \brief gets statistics about directory in register area
224 \param bfs block files
225 \param no directory number (0=first, 1=second,...)
226 \param directory holds directory name (if found)
227 \param used_bytes used file bytes in directory (if found)
228 \param max_bytes max usage of bytes (if found)
229 \retval 1 no is within range and directory, used, max are set.
230 \retval 0 no is out of range and directory, used, max are unset
232 We are using double, because off_t may have a different size
233 on same platform depending on whether 64-bit is enabled or not.
234 Note that if a register area has unlimited size, that is represented
239 int bfs_register_directory_stat(BFiles bfs, int no, const char **directory,
240 double *used_bytes, double *max_bytes);
242 /* \brief gets statistics about directory in shadow area
243 \param bfs block files
244 \param no directory number (0=first, 1=second,...)
245 \param directory holds directory name (if found)
246 \param used_bytes used file bytes in directory (if found)
247 \param max_bytes max usage of bytes (if found)
248 \retval 1 no is within range and directory, used, max are set.
249 \retval 0 no is out of range and directory, used, max are unset
251 We are using double, because off_t may have a different size
252 on same platform depending on whether 64-bit is enabled or not.
253 Note that if a shadow area has unlimited size, that is represented
257 int bfs_shadow_directory_stat(BFiles bfs, int no, const char **directory,
258 double *used_bytes, double *max_bytes);
266 * indent-tabs-mode: nil
268 * vim: shiftwidth=4 tabstop=8 expandtab