Fix documentation of of chr's equivalent directive ZEB-672

[idzebra-moved-to-github.git] / bfile / mfile.h

diff --git a/bfile/mfile.h b/bfile/mfile.h
index 7b5be30..81cd224 100644 (file)
--- a/bfile/mfile.h
+++ b/bfile/mfile.h
@@ -1,8 +1,5 @@
-/* $Id: mfile.h,v 1.6 2006-08-14 10:40:05 adam Exp $
-   Copyright (C) 1995-2006
-   Index Data ApS
-
-This file is part of the Zebra server.
+/* This file is part of the Zebra server.
+   Copyright (C) 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
@@ -20,14 +17,13 @@ Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 
 */
 
-
-
 #ifndef MFILE_H
 #define MFILE_H
 
 #include <stdio.h>
 #include <yaz/yconfig.h>
 #include <idzebra/version.h>
+#include <idzebra/util.h>
 
 #ifdef WIN32
 
@@ -85,7 +81,6 @@ typedef struct meta_file
     int no_files;
     int cur_file;
     int open;                          /* is this file open? */
-    int unlink_flag;
     int blocksize;
     mfile_off_t min_bytes_creat;  /* minimum bytes required to enter directory */
     MFile_area ma;
@@ -95,55 +90,77 @@ typedef struct meta_file
     struct meta_file *next;
 } *MFile, meta_file;
 
-typedef struct MFile_area_struct
+struct MFile_area_struct
 {
     char name[FILENAME_MAX+1];
     mf_dir *dirs;
     struct meta_file *mfiles;
     struct MFile_area_struct *next;  /* global list of active areas */
     Zebra_mutex mutex;
-} MFile_area_struct;
-
-/*
- * Open an area, cotaining metafiles in directories.
- */
-MFile_area mf_init(const char *name, const char *spec, const char *base); 
+};
+
+/** \brief creates a metafile area
+    \param name of area (does not show up on disk - purely for notation)
+    \param spec area specification (e.g. "/a:1G dir /b:2000M"
+    \param base base directory (NULL for no base)
+    \param only_shadow_files only consider shadow files in area
+    \returns metafile area handle or NULL if error occurs
+*/
+MFile_area mf_init(const char *name, const char *spec, const char *base,
+                   int only_shadow_files)
+    ZEBRA_GCC_ATTR((warn_unused_result));
 
-/*
- * Release an area.
- */
+/** \brief destroys metafile area handle
+    \param ma metafile area handle
+*/
 void mf_destroy(MFile_area ma);
 
-/*
- * Open a metafile.
+/** \brief opens metafile
+    \param ma metafile area handle
+    \param name pseudo filename (name*.mf)
+    \param block_size block size for this file
+    \param wflag write flag, 0=read, 1=write&read
+    \returns metafile handle, or NULL for error (could not be opened)
  */
-MFile mf_open(MFile_area ma, const char *name, int block_size, int wflag);
+MFile mf_open(MFile_area ma, const char *name, int block_size, int wflag)
+    ZEBRA_GCC_ATTR((warn_unused_result));
 
-/*
- * Close a metafile.
- */
+/** \brief closes metafile
+    \param mf metafile handle
+    \retval 0 OK
+*/
 int mf_close(MFile mf);
 
-/*
- * Read one block from a metafile. Interface mirrors bfile.
- */
-int mf_read(MFile mf, zint no, int offset, int nbytes, void *buf);
-
-/*
- * Same.
- */
-int mf_write(MFile mf, zint no, int offset, int nbytes, const void *buf);
-
-/*
- * Destroy a metafile, unlinking component files. File must be open.
+/** \brief reads block from metafile
+    \param mf metafile handle
+    \param no block position
+    \param offset offset within block
+    \param nbytes no of bytes to read (0 for whole block)
+    \param buf content (filled with data if OK)
+    \retval 0 block partially read
+    \retval 1 block fully read
+    \retval -1 block could not be read due to error
  */
-int mf_unlink(MFile mf);
-
+int mf_read(MFile mf, zint no, int offset, int nbytes, void *buf)
+    ZEBRA_GCC_ATTR((warn_unused_result));
+
+/** \brief writes block to metafile
+    \param mf metafile handle
+    \param no block position
+    \param offset offset within block
+    \param nbytes no of bytes to write (0 for whole block)
+    \param buf content to be written
+    \retval 0 block written
+    \retval -1 error (block not written)
+*/
+int mf_write(MFile mf, zint no, int offset, int nbytes, const void *buf)
+    ZEBRA_GCC_ATTR((warn_unused_result));
 
-/*
- * Destroy all metafiles. No files may be opened.
- */
-void mf_reset(MFile_area ma);
+/** \brief reset all files in a metafile area (optionally delete them as well)
+    \param ma metafile area
+    \param unlink_flag if unlink_flag=1 all files are removed from FS
+*/
+void mf_reset(MFile_area ma, int unlink_flag);
 
 /* \brief gets statistics about directory in metafile area
    \param ma the area
@@ -158,16 +175,17 @@ void mf_reset(MFile_area ma);
    on same platform depending on whether 64-bit is enabled or not.
    Note that if an area has unlimited size, that is represented
    as max_bytes = -1.
-*/ 
+*/
 int mf_area_directory_stat(MFile_area ma, int no, const char **directory,
                           double *bytes_used, double *bytes_max);
-    
+
 YAZ_END_CDECL
 
 #endif
 /*
  * Local variables:
  * c-basic-offset: 4
+ * c-file-style: "Stroustrup"
  * indent-tabs-mode: nil
  * End:
  * vim: shiftwidth=4 tabstop=8 expandtab