include/idzebra/bfile.h

   1 /* $Id: bfile.h,v 1.13 2007-01-15 20:08:24 adam Exp $
   2    Copyright (C) 1995-2007
   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 (may call exit)
  64     \param bf block file
  65  */
  66 YAZ_EXPORT
  67 void bf_close(BFile bf);
  68
  69 /** \brief closes a Block file
  70     \param bf block file
  71     \retval 0 success
  72     \retval -1 failure
  73  */
  74 YAZ_EXPORT
  75 int bf_close2(BFile bf);
  76
  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)
  81     \retval 0 success
  82     \retval -1 failure (can never happen as the code is now)
  83 */
  84 YAZ_EXPORT
  85 int bf_xclose(BFile bf, int version, const char *more_info);
  86
  87 /** \brief opens and returns a Block file handle
  88     \param bfs block files
  89     \param name filename
  90     \param block_size block size in bytes
  91     \param wflag 1=opened for read&write, 0=read only
  92     \retval 0 success
  93     \retval -1 failure (can never happen as the code is now)
  94 */
  95 YAZ_EXPORT
  96 BFile bf_open(BFiles bfs, const char *name, int block_size, int wflag);
  97
  98 /** \brief opens and returns an extended Block file handle
  99     \param bfs block files
 100     \param name filename
 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)
 106 */
 107 YAZ_EXPORT
 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);
 111
 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
 120  */
 121 YAZ_EXPORT
 122 int bf_read(BFile bf, zint no, int offset, int nbytes, void *buf);
 123
 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
 132     \retval -1 error
 133  */
 134 YAZ_EXPORT
 135 int bf_read2(BFile bf, zint no, int offset, int nbytes, void *buf)
 136     ZEBRA_GCC_ATTR((warn_unused_result));
 137
 138
 139 /** \brief writes block of bytes to file (may call exit)
 140     \param bf block file handle
 141     \param no block no
 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)
 146
 147     This function can not return a failure. System calls exit(1)
 148     if write failed.
 149  */
 150 YAZ_EXPORT
 151 int bf_write(BFile bf, zint no, int offset, int nbytes, const void *buf);
 152
 153
 154 /** \brief writes block of bytes to file
 155     \param bf block file handle
 156     \param no block no
 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)
 161     \retval -1 error
 162
 163     This function can not return a failure. System calls exit(1)
 164     if write failed.
 165  */
 166 YAZ_EXPORT
 167 int bf_write2(BFile bf, zint no, int offset, int nbytes, const void *buf)
 168     ZEBRA_GCC_ATTR((warn_unused_result));
 169
 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.
 175 */
 176 YAZ_EXPORT
 177 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
 178
 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
 183 */
 184 YAZ_EXPORT
 185 int bf_commitExists (BFiles bfs);
 186
 187 /** \brief Executes commit operation
 188     \param bfs block files
 189 */
 190 YAZ_EXPORT
 191 int bf_commitExec (BFiles bfs) ZEBRA_GCC_ATTR((warn_unused_result));
 192
 193 /** \brief Cleans shadow files (remove them)
 194     \param bfs block files
 195     \param spec shadow specification
 196 */
 197 YAZ_EXPORT
 198 void bf_commitClean (BFiles bfs, const char *spec);
 199
 200 /** \brief Removes register and shadow completely
 201     \param bfs block files
 202 */
 203 YAZ_EXPORT
 204 void bf_reset (BFiles bfs);
 205
 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
 210 */
 211 YAZ_EXPORT
 212 int bf_alloc(BFile bf, int no, zint *blocks);
 213
 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
 218 */
 219 YAZ_EXPORT
 220 int bf_free(BFile bf, int no, const zint *blocks);
 221
 222
 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
 231
 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
 235    as max_bytes = -1.
 236
 237 */
 238 YAZ_EXPORT
 239 int bfs_register_directory_stat(BFiles bfs, int no, const char **directory,
 240                                 double *used_bytes, double *max_bytes);
 241
 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
 250
 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
 254    as max_bytes = -1.
 255 */
 256 YAZ_EXPORT
 257 int bfs_shadow_directory_stat(BFiles bfs, int no, const char **directory,
 258                               double *used_bytes, double *max_bytes);
 259
 260 YAZ_END_CDECL
 261
 262 #endif
 263 /*
 264  * Local variables:
 265  * c-basic-offset: 4
 266  * indent-tabs-mode: nil
 267  * End:
 268  * vim: shiftwidth=4 tabstop=8 expandtab
 269  */
 270