include/idzebra/bfile.h

   1 /* $Id: bfile.h,v 1.6 2006-04-04 00:10:09 adam Exp $
   2    Copyright (C) 1995-2005
   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 */
  52 BFiles bfs_create (const char *spec, const char *base);
  53
  54 /** \brief destroys a block files handle
  55     \param bfiles block files handle
  56
  57     The files in the block files collection are not deleted. Only the
  58     handle is
  59 */
  60 void bfs_destroy (BFiles bfiles);
  61
  62 /** \brief closes a Block file
  63     \param bf block file
  64  */
  65 YAZ_EXPORT
  66 int bf_close (BFile bf);
  67
  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)
  72 */
  73 YAZ_EXPORT
  74 int bf_xclose (BFile bf, int version, const char *more_info);
  75
  76 /** \brief opens and returns a Block file handle
  77     \param bfs block files
  78     \param name filename
  79     \param block_size block size in bytes
  80     \param wflag 1=opened for read&write, 0=read only
  81 */
  82 YAZ_EXPORT
  83 BFile bf_open (BFiles bfs, const char *name, int block_size, int wflag);
  84
  85 /** \brief opens and returns an extended Block file handle
  86     \param bfs block files
  87     \param name filename
  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)
  93 */
  94 YAZ_EXPORT
  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);
  98
  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)
 105
 106     Returns 1 if whole block could be read; 0 otherwise.
 107  */
 108 YAZ_EXPORT
 109 int bf_read (BFile bf, zint no, int offset, int nbytes, void *buf);
 110
 111 /** \brief writes bytes to file
 112     \param bf block file handle
 113     \param no block no
 114     \param offset within block
 115     \param nbytes number of bytes to write
 116     \param buf buffer to write
 117
 118     Writes the content of buffer to a block within a block file (or
 119     whole block). Returns 1 if successful; 0 otherwise.
 120  */
 121 YAZ_EXPORT
 122 int bf_write (BFile bf, zint no, int offset, int nbytes, const void *buf);
 123
 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
 127 */
 128 YAZ_EXPORT
 129 ZEBRA_RES bf_cache (BFiles bfs, const char *spec);
 130
 131 /** \brief Check if there is content in shadow area (to be committed).
 132     \param bfs block files
 133
 134     Returns 1 if there is content in shadow area; 0 otherwise.
 135 */
 136 YAZ_EXPORT
 137 int bf_commitExists (BFiles bfs);
 138
 139 /** \brief Executes commit operation
 140     \param bfs block files
 141 */
 142 YAZ_EXPORT
 143 void bf_commitExec (BFiles bfs);
 144
 145 /** \brief Cleans shadow files (remove them)
 146     \param bfs block files
 147     \param spec shadow specification
 148 */
 149 YAZ_EXPORT
 150 void bf_commitClean (BFiles bfs, const char *spec);
 151
 152 /** \brief Removes register and shadow completely
 153     \param bfs block files
 154 */
 155 YAZ_EXPORT
 156 void bf_reset (BFiles bfs);
 157
 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
 162 */
 163 YAZ_EXPORT
 164 int bf_alloc(BFile bf, int no, zint *blocks);
 165
 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
 170 */
 171 YAZ_EXPORT
 172 int bf_free(BFile bf, int no, const zint *blocks);
 173
 174 YAZ_END_CDECL
 175
 176 #endif