1 /* $Id: bfile.h,v 1.6 2006-04-04 00:10:09 adam Exp $
2 Copyright (C) 1995-2005
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 Zebra; see the file LICENSE.zebra. If not, write to the
19 Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA
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)
52 BFiles bfs_create (const char *spec, const char *base);
54 /** \brief destroys a block files handle
55 \param bfiles block files handle
57 The files in the block files collection are not deleted. Only the
60 void bfs_destroy (BFiles bfiles);
62 /** \brief closes a Block file
66 int bf_close (BFile bf);
68 /** \brief closes an extended Block file handle..
69 \param bf extended block file opened with bf_xopen
70 \param version version to be put in a file
71 \param more_info more information to be stored in file (header)
74 int bf_xclose (BFile bf, int version, const char *more_info);
76 /** \brief opens and returns a Block file handle
77 \param bfs block files
79 \param block_size block size in bytes
80 \param wflag 1=opened for read&write, 0=read only
83 BFile bf_open (BFiles bfs, const char *name, int block_size, int wflag);
85 /** \brief opens and returns an extended Block file handle
86 \param bfs block files
88 \param block_size block size in bytes
89 \param wflag 1=opened for read&write, 0=read only
90 \param magic magic string to be used for file
91 \param read_version holds after completion of bf_xopen the version
92 \param more_info holds more_info as read from file (header)
95 BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wflag,
96 const char *magic, int *read_version,
97 const char **more_info);
99 /** \brief read from block file
100 \param bf block file handle
101 \param no block no (first block is 0, second is 1..)
102 \param offset offset within block to be read
103 \param nbytes number of bytes to read (0 for whole block)
104 \param buf raw bytes with content (at least nbytes of size)
106 Returns 1 if whole block could be read; 0 otherwise.
109 int bf_read (BFile bf, zint no, int offset, int nbytes, void *buf);
111 /** \brief writes bytes to file
112 \param bf block file handle
114 \param offset within block
115 \param nbytes number of bytes to write
116 \param buf buffer to write
118 Writes the content of buffer to a block within a block file (or
119 whole block). Returns 1 if successful; 0 otherwise.
122 int bf_write (BFile bf, zint no, int offset, int nbytes, const void *buf);
124 /** \brief enables or disables shadow for block files
125 \param bfs block files
126 \param spec such as "shadow:100M /other:200M"; or NULL to disable
129 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
131 /** \brief Check if there is content in shadow area (to be committed).
132 \param bfs block files
134 Returns 1 if there is content in shadow area; 0 otherwise.
137 int bf_commitExists (BFiles bfs);
139 /** \brief Executes commit operation
140 \param bfs block files
143 void bf_commitExec (BFiles bfs);
145 /** \brief Cleans shadow files (remove them)
146 \param bfs block files
147 \param spec shadow specification
150 void bf_commitClean (BFiles bfs, const char *spec);
152 /** \brief Removes register and shadow completely
153 \param bfs block files
156 void bf_reset (BFiles bfs);
158 /** \brief Allocates one or more blocks in an extended block file
159 \param bf extended block file
160 \param no number of blocks to allocate
161 \param blocks output array of size no with block offsets
164 int bf_alloc(BFile bf, int no, zint *blocks);
166 /** \brief Releases one or more blocks in an extended block file
167 \param bf extended block file
168 \param no numer of blocks to release
169 \param blocks input array with block offsets (IDs) to release
172 int bf_free(BFile bf, int no, const zint *blocks);