X-Git-Url: http://git.indexdata.com/?p=idzebra-moved-to-github.git;a=blobdiff_plain;f=include%2Fidzebra%2Fbfile.h;h=1316ef89131d1e429dae9048d8ac8baf0ba538d7;hp=486f868bb8db301e9555f11b6818cac7b2b44e96;hb=89d16cf15eda0e4802d18b8ad09bd3653508ebfc;hpb=05b9b8ed020c5bfa48a913d6a2e2b50ddf1bab8e diff --git a/include/idzebra/bfile.h b/include/idzebra/bfile.h index 486f868..1316ef8 100644 --- a/include/idzebra/bfile.h +++ b/include/idzebra/bfile.h @@ -1,8 +1,5 @@ -/* $Id: bfile.h,v 1.1 2004-12-08 12:23:09 adam Exp $ - Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002,2003,2004 - Index Data Aps - -This file is part of the Zebra server. +/* This file is part of the Zebra server. + Copyright (C) 1994-2009 Index Data Zebra is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free @@ -15,73 +12,256 @@ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License -along with Zebra; see the file LICENSE.zebra. If not, write to the -Free Software Foundation, 59 Temple Place - Suite 330, Boston, MA -02111-1307, USA. +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA + +*/ + +/** \file bfile.h + \brief Zebra Block File Layer + + Providers an interface to a file system , AKA persistent storage. + The interface allows safe updates - using a shadow file facility. */ #ifndef BFILE_H #define BFILE_H -#include +#include +#include YAZ_BEGIN_CDECL +/** \var BFiles + \brief A collection of BFile(s). +*/ typedef struct BFiles_struct *BFiles; + +/** \var BFile + \brief A Block File +*/ typedef struct BFile_struct *BFile; +/** \brief creates a Block files collection + \param spec register specification , e.g. "d1:100M d2:1G" + \param base base directory for register spec (if that is relative path) + \return block files handle +*/ BFiles bfs_create (const char *spec, const char *base); + +/** \brief destroys a block files handle + \param bfiles block files handle + + The files in the block files collection are not deleted. Only the + handle is freed. +*/ void bfs_destroy (BFiles bfiles); -/* bf_close: closes bfile. - returns 0 if successful; non-zero otherwise +/** \brief closes a Block file (may call exit) + \param bf block file */ YAZ_EXPORT -int bf_close (BFile); +void bf_close(BFile bf); -/* bf_open: opens bfile. - opens bfile with name 'name' and with 'block_size' as block size. - returns bfile handle is successful; NULL otherwise +/** \brief closes a Block file + \param bf block file + \retval 0 success + \retval -1 failure */ YAZ_EXPORT -BFile bf_open (BFiles bfs, const char *name, int block_size, int wflag); +int bf_close2(BFile bf); + +/** \brief closes an extended Block file handle.. + \param bf extended block file opened with bf_xopen + \param version version to be put in a file + \param more_info more information to be stored in file (header) + \retval 0 success + \retval -1 failure (can never happen as the code is now) +*/ +YAZ_EXPORT +int bf_xclose(BFile bf, int version, const char *more_info); -/* bf_read: reads bytes from bfile 'bf'. - reads 'nbytes' bytes (or whole block if 0) from offset 'offset' from - block 'no'. stores contents in buffer 'buf'. - returns 1 if whole block could be read; 0 otherwise. +/** \brief opens and returns a Block file handle + \param bfs block files + \param name filename + \param block_size block size in bytes + \param wflag 1=opened for read&write, 0=read only + \retval 0 success + \retval -1 failure (can never happen as the code is now) +*/ +YAZ_EXPORT +BFile bf_open(BFiles bfs, const char *name, int block_size, int wflag); + +/** \brief opens and returns an extended Block file handle + \param bfs block files + \param name filename + \param block_size block size in bytes + \param wflag 1=opened for read&write, 0=read only + \param magic magic string to be used for file + \param read_version holds after completion of bf_xopen the version + \param more_info holds more_info as read from file (header) +*/ +YAZ_EXPORT +BFile bf_xopen(BFiles bfs, const char *name, int block_size, int wflag, + const char *magic, int *read_version, + const char **more_info); + +/** \brief read from block file (may call exit) + \param bf block file handle + \param no block no (first block is 0, second is 1..) + \param offset offset within block to be read + \param nbytes number of bytes to read (0 for whole block) + \param buf raw bytes with content (at least nbytes of size) + \retval 1 whole block could be read + \retval 0 whole block could not be read */ YAZ_EXPORT -int bf_read (BFile bf, zint no, int offset, int nbytes, void *buf); +int bf_read(BFile bf, zint no, int offset, int nbytes, void *buf); -/* bf_write: writes bytes to bfile 'bf'. - writes 'nbytes' bytes (or whole block if 0) at offset 'offset' to - block 'no'. retrieves contents from buffer 'buf'. - returns 0 if successful; non-zero otherwise. +/** \brief read from block file + \param bf block file handle + \param no block no (first block is 0, second is 1..) + \param offset offset within block to be read + \param nbytes number of bytes to read (0 for whole block) + \param buf raw bytes with content (at least nbytes of size) + \retval 1 whole block could be read + \retval 0 whole block could not be read + \retval -1 error */ YAZ_EXPORT -int bf_write (BFile bf, zint no, int offset, int nbytes, const void *buf); +int bf_read2(BFile bf, zint no, int offset, int nbytes, void *buf) + ZEBRA_GCC_ATTR((warn_unused_result)); + -/* bf_cache: enables bfile cache if spec is not NULL */ +/** \brief writes block of bytes to file (may call exit) + \param bf block file handle + \param no block no + \param offset within block + \param nbytes number of bytes to write + \param buf buffer to write + \retval 0 success (block could be written) + + This function can not return a failure. System calls exit(1) + if write failed. + */ YAZ_EXPORT -void bf_cache (BFiles bfs, const char *spec); +int bf_write(BFile bf, zint no, int offset, int nbytes, const void *buf); + -/* bf_commitExists: returns 1 if commit is pending; 0 otherwise */ +/** \brief writes block of bytes to file + \param bf block file handle + \param no block no + \param offset within block + \param nbytes number of bytes to write + \param buf buffer to write + \retval 0 success (block written) + \retval -1 error + + This function can not return a failure. System calls exit(1) + if write failed. + */ +YAZ_EXPORT +int bf_write2(BFile bf, zint no, int offset, int nbytes, const void *buf) + ZEBRA_GCC_ATTR((warn_unused_result)); + +/** \brief enables or disables shadow for block files + \param bfs block files + \param spec such as "shadow:100M /other:200M"; or NULL to disable + \retval ZEBRA_OK successful. spec is OK + \retval ZEBRA_FAIL failure. +*/ +YAZ_EXPORT +ZEBRA_RES bf_cache (BFiles bfs, const char *spec); + +/** \brief Check if there is content in shadow area (to be committed). + \param bfs block files + \retval 1 there is content in shadow area + \retval 0 no content in shadow area +*/ YAZ_EXPORT int bf_commitExists (BFiles bfs); -/* bf_commitExec: executes commit */ +/** \brief Executes commit operation + \param bfs block files +*/ YAZ_EXPORT -void bf_commitExec (BFiles bfs); +int bf_commitExec (BFiles bfs) ZEBRA_GCC_ATTR((warn_unused_result)); -/* bf_commitClean: cleans commit files, etc */ +/** \brief Cleans shadow files (remove them) + \param bfs block files + \param spec shadow specification +*/ YAZ_EXPORT void bf_commitClean (BFiles bfs, const char *spec); -/* bf_reset: delete register and shadow completely */ +/** \brief Removes register and shadow completely + \param bfs block files +*/ YAZ_EXPORT void bf_reset (BFiles bfs); +/** \brief Allocates one or more blocks in an extended block file + \param bf extended block file + \param no number of blocks to allocate + \param blocks output array of size no with block offsets +*/ +YAZ_EXPORT +int bf_alloc(BFile bf, int no, zint *blocks); + +/** \brief Releases one or more blocks in an extended block file + \param bf extended block file + \param no numer of blocks to release + \param blocks input array with block offsets (IDs) to release +*/ +YAZ_EXPORT +int bf_free(BFile bf, int no, const zint *blocks); + + +/* \brief gets statistics about directory in register area + \param bfs block files + \param no directory number (0=first, 1=second,...) + \param directory holds directory name (if found) + \param used_bytes used file bytes in directory (if found) + \param max_bytes max usage of bytes (if found) + \retval 1 no is within range and directory, used, max are set. + \retval 0 no is out of range and directory, used, max are unset + + We are using double, because off_t may have a different size + on same platform depending on whether 64-bit is enabled or not. + Note that if a register area has unlimited size, that is represented + as max_bytes = -1. + +*/ +YAZ_EXPORT +int bfs_register_directory_stat(BFiles bfs, int no, const char **directory, + double *used_bytes, double *max_bytes); + +/* \brief gets statistics about directory in shadow area + \param bfs block files + \param no directory number (0=first, 1=second,...) + \param directory holds directory name (if found) + \param used_bytes used file bytes in directory (if found) + \param max_bytes max usage of bytes (if found) + \retval 1 no is within range and directory, used, max are set. + \retval 0 no is out of range and directory, used, max are unset + + We are using double, because off_t may have a different size + on same platform depending on whether 64-bit is enabled or not. + Note that if a shadow area has unlimited size, that is represented + as max_bytes = -1. +*/ +YAZ_EXPORT +int bfs_shadow_directory_stat(BFiles bfs, int no, const char **directory, + double *used_bytes, double *max_bytes); + YAZ_END_CDECL #endif +/* + * Local variables: + * c-basic-offset: 4 + * indent-tabs-mode: nil + * End: + * vim: shiftwidth=4 tabstop=8 expandtab + */ +