Put local variables footer in all c, h files.
[idzebra-moved-to-github.git] / include / idzebra / bfile.h
1 /* $Id: bfile.h,v 1.9 2006-05-10 08:13:20 adam Exp $
2    Copyright (C) 1995-2006
3    Index Data ApS
4
5 This file is part of the Zebra server.
6
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
10 version.
11
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
15 for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with Zebra; see the file LICENSE.zebra.  If not, write to the
19 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
20 02111-1307, USA.
21 */
22
23 /** \file bfile.h
24     \brief Zebra Block File Layer
25
26     Providers an interface to a file system , AKA persistent storage.
27     The interface allows safe updates - using a shadow file facility.
28 */
29
30 #ifndef BFILE_H
31 #define BFILE_H
32
33 #include <yaz/yconfig.h>
34 #include <idzebra/util.h>
35
36 YAZ_BEGIN_CDECL
37
38 /** \var BFiles
39     \brief A collection of BFile(s).
40 */
41 typedef struct BFiles_struct *BFiles;
42
43 /** \var BFile
44     \brief A Block File
45 */
46 typedef struct BFile_struct *BFile;
47
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
52 */
53 BFiles bfs_create (const char *spec, const char *base);
54
55 /** \brief destroys a block files handle
56     \param bfiles block files handle
57    
58     The files in the block files collection are not deleted. Only the
59     handle is 
60 */
61 void bfs_destroy (BFiles bfiles);
62
63 /** \brief closes a Block file
64     \param bf block file
65  */
66 YAZ_EXPORT
67 int bf_close (BFile bf);
68
69 /** \brief closes an extended Block file handle..
70     \param bf extended block file opened with bf_xopen
71     \param version version to be put in a file
72     \param more_info more information to be stored in file (header)
73     \retval 0 succes
74     \retval -1 failure (can never happen as the code is now)
75 */    
76 YAZ_EXPORT
77 int bf_xclose (BFile bf, int version, const char *more_info);
78
79 /** \brief opens and returns a Block file handle
80     \param bfs block files
81     \param name filename
82     \param block_size block size in bytes
83     \param wflag 1=opened for read&write, 0=read only
84     \retval 0 succes
85     \retval -1 failure (can never happen as the code is now)
86 */
87 YAZ_EXPORT
88 BFile bf_open (BFiles bfs, const char *name, int block_size, int wflag);
89
90 /** \brief opens and returns an extended Block file handle
91     \param bfs block files
92     \param name filename
93     \param block_size block size in bytes
94     \param wflag 1=opened for read&write, 0=read only
95     \param magic magic string to be used for file
96     \param read_version holds after completion of bf_xopen the version
97     \param more_info holds more_info as read from file (header)
98 */
99 YAZ_EXPORT
100 BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wflag,
101                const char *magic, int *read_version,
102                const char **more_info);
103
104 /** \brief read from block file
105     \param bf block file handle
106     \param no block no (first block is 0, second is 1..)
107     \param offset offset within block to be read
108     \param nbytes number of bytes to read (0 for whole block)
109     \param buf raw bytes with content (at least nbytes of size)
110     \retval 1 whole block could be read
111     \retval 0 whole block could not be read
112  */
113 YAZ_EXPORT
114 int bf_read (BFile bf, zint no, int offset, int nbytes, void *buf);
115
116 /** \brief writes block of bytes to file
117     \param bf block file handle
118     \param no block no
119     \param offset within block
120     \param nbytes number of bytes to write
121     \param buf buffer to write
122     \retval 0 succes (block could be written)
123
124     This function can not return a failure. System calls exit(1)
125     if write failed.
126  */
127 YAZ_EXPORT
128 int bf_write (BFile bf, zint no, int offset, int nbytes, const void *buf);
129
130 /** \brief enables or disables shadow for block files
131     \param bfs block files
132     \param spec  such as  "shadow:100M /other:200M"; or NULL to disable
133     \retval ZEBRA_OK successful. spec is OK
134     \retval ZEBRA_FAIL failure.
135 */
136 YAZ_EXPORT
137 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
138
139 /** \brief Check if there is content in shadow area (to be committed).
140     \param bfs block files
141     \retval 1 there is content in shadow area
142     \retval 0 no content in shadow area
143 */
144 YAZ_EXPORT
145 int bf_commitExists (BFiles bfs);
146
147 /** \brief Executes commit operation
148     \param bfs block files
149 */
150 YAZ_EXPORT
151 void bf_commitExec (BFiles bfs);
152
153 /** \brief Cleans shadow files (remove them)
154     \param bfs block files
155     \param spec shadow specification
156 */
157 YAZ_EXPORT
158 void bf_commitClean (BFiles bfs, const char *spec);
159
160 /** \brief Removes register and shadow completely
161     \param bfs block files
162 */
163 YAZ_EXPORT
164 void bf_reset (BFiles bfs);
165
166 /** \brief Allocates one or more blocks in an extended block file
167     \param bf extended block file
168     \param no number of blocks to allocate
169     \param blocks output array of size no with block offsets
170 */
171 YAZ_EXPORT
172 int bf_alloc(BFile bf, int no, zint *blocks);
173
174 /** \brief Releases one or more blocks in an extended block file
175     \param bf extended block file
176     \param no numer of blocks to release
177     \param blocks input array with block offsets (IDs) to release
178 */
179 YAZ_EXPORT
180 int bf_free(BFile bf, int no, const zint *blocks);
181
182
183 /* \brief gets statistics about directory in register area
184    \param bfs block files
185    \param no directory number (0=first, 1=second,...)
186    \param directory holds directory name (if found)
187    \param used_bytes used file bytes in directory (if found)
188    \param max_bytes max usage of bytes (if found)
189    \retval 1 no is within range and directory, used, max are set.
190    \retval 0 no is out of range and directory, used, max are unset
191
192    We are using double, because off_t may have a different size
193    on same platform depending on whether 64-bit is enabled or not.
194    Note that if a register area has unlimited size, that is represented
195    as max_bytes = -1.
196
197 */
198 YAZ_EXPORT
199 int bfs_register_directory_stat(BFiles bfs, int no, const char **directory,
200                                 double *used_bytes, double *max_bytes);
201
202 /* \brief gets statistics about directory in shadow area
203    \param bfs block files
204    \param no directory number (0=first, 1=second,...)
205    \param directory holds directory name (if found)
206    \param used_bytes used file bytes in directory (if found)
207    \param max_bytes max usage of bytes (if found)
208    \retval 1 no is within range and directory, used, max are set.
209    \retval 0 no is out of range and directory, used, max are unset
210
211    We are using double, because off_t may have a different size
212    on same platform depending on whether 64-bit is enabled or not.
213    Note that if a shadow area has unlimited size, that is represented
214    as max_bytes = -1.
215 */ 
216 YAZ_EXPORT
217 int bfs_shadow_directory_stat(BFiles bfs, int no, const char **directory,
218                               double *used_bytes, double *max_bytes);
219
220 YAZ_END_CDECL
221
222 #endif
223 /*
224  * Local variables:
225  * c-basic-offset: 4
226  * indent-tabs-mode: nil
227  * End:
228  * vim: shiftwidth=4 tabstop=8 expandtab
229  */
230