include/idzebra/bfile.h

   1 /* $Id: bfile.h,v 1.11 2006-11-08 22:08:26 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 this program; if not, write to the Free Software
  19 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  20
  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 (may call exit)
 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 read from block file
 117     \param bf block file handle
 118     \param no block no (first block is 0, second is 1..)
 119     \param offset offset within block to be read
 120     \param nbytes number of bytes to read (0 for whole block)
 121     \param buf raw bytes with content (at least nbytes of size)
 122     \retval 1 whole block could be read
 123     \retval 0 whole block could not be read
 124     \retval -1 error
 125  */
 126 YAZ_EXPORT
 127 int bf_read2(BFile bf, zint no, int offset, int nbytes, void *buf);
 128
 129
 130 /** \brief writes block of bytes to file (may call exit)
 131     \param bf block file handle
 132     \param no block no
 133     \param offset within block
 134     \param nbytes number of bytes to write
 135     \param buf buffer to write
 136     \retval 0 success (block could be written)
 137
 138     This function can not return a failure. System calls exit(1)
 139     if write failed.
 140  */
 141 YAZ_EXPORT
 142 int bf_write(BFile bf, zint no, int offset, int nbytes, const void *buf);
 143
 144
 145 /** \brief writes block of bytes to file
 146     \param bf block file handle
 147     \param no block no
 148     \param offset within block
 149     \param nbytes number of bytes to write
 150     \param buf buffer to write
 151     \retval 0 success (block written)
 152     \retval -1 error
 153
 154     This function can not return a failure. System calls exit(1)
 155     if write failed.
 156  */
 157 YAZ_EXPORT
 158 int bf_write2(BFile bf, zint no, int offset, int nbytes, const void *buf);
 159
 160
 161 /** \brief enables or disables shadow for block files
 162     \param bfs block files
 163     \param spec  such as  "shadow:100M /other:200M"; or NULL to disable
 164     \retval ZEBRA_OK successful. spec is OK
 165     \retval ZEBRA_FAIL failure.
 166 */
 167 YAZ_EXPORT
 168 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
 169
 170 /** \brief Check if there is content in shadow area (to be committed).
 171     \param bfs block files
 172     \retval 1 there is content in shadow area
 173     \retval 0 no content in shadow area
 174 */
 175 YAZ_EXPORT
 176 int bf_commitExists (BFiles bfs);
 177
 178 /** \brief Executes commit operation
 179     \param bfs block files
 180 */
 181 YAZ_EXPORT
 182 void bf_commitExec (BFiles bfs);
 183
 184 /** \brief Cleans shadow files (remove them)
 185     \param bfs block files
 186     \param spec shadow specification
 187 */
 188 YAZ_EXPORT
 189 void bf_commitClean (BFiles bfs, const char *spec);
 190
 191 /** \brief Removes register and shadow completely
 192     \param bfs block files
 193 */
 194 YAZ_EXPORT
 195 void bf_reset (BFiles bfs);
 196
 197 /** \brief Allocates one or more blocks in an extended block file
 198     \param bf extended block file
 199     \param no number of blocks to allocate
 200     \param blocks output array of size no with block offsets
 201 */
 202 YAZ_EXPORT
 203 int bf_alloc(BFile bf, int no, zint *blocks);
 204
 205 /** \brief Releases one or more blocks in an extended block file
 206     \param bf extended block file
 207     \param no numer of blocks to release
 208     \param blocks input array with block offsets (IDs) to release
 209 */
 210 YAZ_EXPORT
 211 int bf_free(BFile bf, int no, const zint *blocks);
 212
 213
 214 /* \brief gets statistics about directory in register area
 215    \param bfs block files
 216    \param no directory number (0=first, 1=second,...)
 217    \param directory holds directory name (if found)
 218    \param used_bytes used file bytes in directory (if found)
 219    \param max_bytes max usage of bytes (if found)
 220    \retval 1 no is within range and directory, used, max are set.
 221    \retval 0 no is out of range and directory, used, max are unset
 222
 223    We are using double, because off_t may have a different size
 224    on same platform depending on whether 64-bit is enabled or not.
 225    Note that if a register area has unlimited size, that is represented
 226    as max_bytes = -1.
 227
 228 */
 229 YAZ_EXPORT
 230 int bfs_register_directory_stat(BFiles bfs, int no, const char **directory,
 231                                 double *used_bytes, double *max_bytes);
 232
 233 /* \brief gets statistics about directory in shadow area
 234    \param bfs block files
 235    \param no directory number (0=first, 1=second,...)
 236    \param directory holds directory name (if found)
 237    \param used_bytes used file bytes in directory (if found)
 238    \param max_bytes max usage of bytes (if found)
 239    \retval 1 no is within range and directory, used, max are set.
 240    \retval 0 no is out of range and directory, used, max are unset
 241
 242    We are using double, because off_t may have a different size
 243    on same platform depending on whether 64-bit is enabled or not.
 244    Note that if a shadow area has unlimited size, that is represented
 245    as max_bytes = -1.
 246 */
 247 YAZ_EXPORT
 248 int bfs_shadow_directory_stat(BFiles bfs, int no, const char **directory,
 249                               double *used_bytes, double *max_bytes);
 250
 251 YAZ_END_CDECL
 252
 253 #endif
 254 /*
 255  * Local variables:
 256  * c-basic-offset: 4
 257  * indent-tabs-mode: nil
 258  * End:
 259  * vim: shiftwidth=4 tabstop=8 expandtab
 260  */
 261