include/idzebra/bfile.h

   1 /* This file is part of the Zebra server.
   2    Copyright (C) 1994-2011 Index Data
   3
   4 Zebra is free software; you can redistribute it and/or modify it under
   5 the terms of the GNU General Public License as published by the Free
   6 Software Foundation; either version 2, or (at your option) any later
   7 version.
   8
   9 Zebra is distributed in the hope that it will be useful, but WITHOUT ANY
  10 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  12 for more details.
  13
  14 You should have received a copy of the GNU General Public License
  15 along with this program; if not, write to the Free Software
  16 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  17
  18 */
  19
  20 /** \file bfile.h
  21     \brief Zebra Block File Layer
  22
  23     Providers an interface to a file system , AKA persistent storage.
  24     The interface allows safe updates - using a shadow file facility.
  25 */
  26
  27 #ifndef BFILE_H
  28 #define BFILE_H
  29
  30 #include <yaz/yconfig.h>
  31 #include <idzebra/util.h>
  32
  33 YAZ_BEGIN_CDECL
  34
  35 /** \var BFiles
  36     \brief A collection of BFile(s).
  37 */
  38 typedef struct BFiles_struct *BFiles;
  39
  40 /** \var BFile
  41     \brief A Block File
  42 */
  43 typedef struct BFile_struct *BFile;
  44
  45 /** \brief creates a Block files collection
  46     \param spec register specification , e.g. "d1:100M d2:1G"
  47     \param base base directory for register spec (if that is relative path)
  48     \return block files handle
  49 */
  50 BFiles bfs_create (const char *spec, const char *base);
  51
  52 /** \brief destroys a block files handle
  53     \param bfiles block files handle
  54
  55     The files in the block files collection are not deleted. Only the
  56     handle is freed.
  57 */
  58 void bfs_destroy (BFiles bfiles);
  59
  60 /** \brief closes a Block file (may call exit)
  61     \param bf block file
  62  */
  63 YAZ_EXPORT
  64 void bf_close(BFile bf);
  65
  66 /** \brief closes a Block file
  67     \param bf block file
  68     \retval 0 success
  69     \retval -1 failure
  70  */
  71 YAZ_EXPORT
  72 int bf_close2(BFile bf);
  73
  74 /** \brief closes an extended Block file handle..
  75     \param bf extended block file opened with bf_xopen
  76     \param version version to be put in a file
  77     \param more_info more information to be stored in file (header)
  78     \retval 0 success
  79     \retval -1 failure (can never happen as the code is now)
  80 */
  81 YAZ_EXPORT
  82 int bf_xclose(BFile bf, int version, const char *more_info);
  83
  84 /** \brief opens and returns a Block file handle
  85     \param bfs block files
  86     \param name filename
  87     \param block_size block size in bytes
  88     \param wflag 1=opened for read&write, 0=read only
  89     \retval 0 success
  90     \retval -1 failure (can never happen as the code is now)
  91 */
  92 YAZ_EXPORT
  93 BFile bf_open(BFiles bfs, const char *name, int block_size, int wflag);
  94
  95 /** \brief opens and returns an extended Block file handle
  96     \param bfs block files
  97     \param name filename
  98     \param block_size block size in bytes
  99     \param wflag 1=opened for read&write, 0=read only
 100     \param magic magic string to be used for file
 101     \param read_version holds after completion of bf_xopen the version
 102     \param more_info holds more_info as read from file (header)
 103 */
 104 YAZ_EXPORT
 105 BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wflag,
 106                const char *magic, int *read_version,
 107                const char **more_info);
 108
 109 /** \brief read from block file (may call exit)
 110     \param bf block file handle
 111     \param no block no (first block is 0, second is 1..)
 112     \param offset offset within block to be read
 113     \param nbytes number of bytes to read (0 for whole block)
 114     \param buf raw bytes with content (at least nbytes of size)
 115     \retval 1 whole block could be read
 116     \retval 0 whole block could not be read
 117  */
 118 YAZ_EXPORT
 119 int bf_read(BFile bf, zint no, int offset, int nbytes, void *buf);
 120
 121 /** \brief read from block file
 122     \param bf block file handle
 123     \param no block no (first block is 0, second is 1..)
 124     \param offset offset within block to be read
 125     \param nbytes number of bytes to read (0 for whole block)
 126     \param buf raw bytes with content (at least nbytes of size)
 127     \retval 1 whole block could be read
 128     \retval 0 whole block could not be read
 129     \retval -1 error
 130  */
 131 YAZ_EXPORT
 132 int bf_read2(BFile bf, zint no, int offset, int nbytes, void *buf)
 133     ZEBRA_GCC_ATTR((warn_unused_result));
 134
 135
 136 /** \brief writes block of bytes to file (may call exit)
 137     \param bf block file handle
 138     \param no block no
 139     \param offset within block
 140     \param nbytes number of bytes to write
 141     \param buf buffer to write
 142     \retval 0 success (block could be written)
 143
 144     This function can not return a failure. System calls exit(1)
 145     if write failed.
 146  */
 147 YAZ_EXPORT
 148 int bf_write(BFile bf, zint no, int offset, int nbytes, const void *buf);
 149
 150
 151 /** \brief writes block of bytes to file
 152     \param bf block file handle
 153     \param no block no
 154     \param offset within block
 155     \param nbytes number of bytes to write
 156     \param buf buffer to write
 157     \retval 0 success (block written)
 158     \retval -1 error
 159
 160     This function can not return a failure. System calls exit(1)
 161     if write failed.
 162  */
 163 YAZ_EXPORT
 164 int bf_write2(BFile bf, zint no, int offset, int nbytes, const void *buf)
 165     ZEBRA_GCC_ATTR((warn_unused_result));
 166
 167 /** \brief enables or disables shadow for block files
 168     \param bfs block files
 169     \param spec  such as  "shadow:100M /other:200M"; or NULL to disable
 170     \retval ZEBRA_OK successful. spec is OK
 171     \retval ZEBRA_FAIL failure.
 172 */
 173 YAZ_EXPORT
 174 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
 175
 176 /** \brief Check if there is content in shadow area (to be committed).
 177     \param bfs block files
 178     \retval 1 there is content in shadow area
 179     \retval 0 no content in shadow area
 180 */
 181 YAZ_EXPORT
 182 int bf_commitExists (BFiles bfs);
 183
 184 /** \brief Executes commit operation
 185     \param bfs block files
 186 */
 187 YAZ_EXPORT
 188 int bf_commitExec (BFiles bfs) ZEBRA_GCC_ATTR((warn_unused_result));
 189
 190 /** \brief Cleans shadow files (remove them)
 191     \param bfs block files
 192     \param spec shadow specification
 193 */
 194 YAZ_EXPORT
 195 void bf_commitClean (BFiles bfs, const char *spec);
 196
 197 /** \brief Removes register and shadow completely
 198     \param bfs block files
 199 */
 200 YAZ_EXPORT
 201 void bf_reset (BFiles bfs);
 202
 203 /** \brief Allocates one or more blocks in an extended block file
 204     \param bf extended block file
 205     \param no number of blocks to allocate
 206     \param blocks output array of size no with block offsets
 207 */
 208 YAZ_EXPORT
 209 int bf_alloc(BFile bf, int no, zint *blocks);
 210
 211 /** \brief Releases one or more blocks in an extended block file
 212     \param bf extended block file
 213     \param no numer of blocks to release
 214     \param blocks input array with block offsets (IDs) to release
 215 */
 216 YAZ_EXPORT
 217 int bf_free(BFile bf, int no, const zint *blocks);
 218
 219
 220 /* \brief gets statistics about directory in register area
 221    \param bfs block files
 222    \param no directory number (0=first, 1=second,...)
 223    \param directory holds directory name (if found)
 224    \param used_bytes used file bytes in directory (if found)
 225    \param max_bytes max usage of bytes (if found)
 226    \retval 1 no is within range and directory, used, max are set.
 227    \retval 0 no is out of range and directory, used, max are unset
 228
 229    We are using double, because off_t may have a different size
 230    on same platform depending on whether 64-bit is enabled or not.
 231    Note that if a register area has unlimited size, that is represented
 232    as max_bytes = -1.
 233
 234 */
 235 YAZ_EXPORT
 236 int bfs_register_directory_stat(BFiles bfs, int no, const char **directory,
 237                                 double *used_bytes, double *max_bytes);
 238
 239 /* \brief gets statistics about directory in shadow area
 240    \param bfs block files
 241    \param no directory number (0=first, 1=second,...)
 242    \param directory holds directory name (if found)
 243    \param used_bytes used file bytes in directory (if found)
 244    \param max_bytes max usage of bytes (if found)
 245    \retval 1 no is within range and directory, used, max are set.
 246    \retval 0 no is out of range and directory, used, max are unset
 247
 248    We are using double, because off_t may have a different size
 249    on same platform depending on whether 64-bit is enabled or not.
 250    Note that if a shadow area has unlimited size, that is represented
 251    as max_bytes = -1.
 252 */
 253 YAZ_EXPORT
 254 int bfs_shadow_directory_stat(BFiles bfs, int no, const char **directory,
 255                               double *used_bytes, double *max_bytes);
 256
 257 YAZ_END_CDECL
 258
 259 #endif
 260 /*
 261  * Local variables:
 262  * c-basic-offset: 4
 263  * c-file-style: "Stroustrup"
 264  * indent-tabs-mode: nil
 265  * End:
 266  * vim: shiftwidth=4 tabstop=8 expandtab
 267  */
 268