chiark - git - mdw - disorder/blob - lib/hreader.h

   1 /*
   2  * This file is part of DisOrder
   3  * Copyright (C) 2010 Richard Kettlewell
   4  *
   5  * This program is free software: you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation, either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18 /** @file lib/hreader.h
  19  * @brief Hands-off reader - read files without keeping them open
  20  */
  21 #ifndef HREADER_H
  22 #define HREADER_H
  23
  24 #include <unistd.h>
  25
  26 /** @brief A hands-off reader
  27  *
  28  * Allows files to be read without holding them open.
  29  */
  30 struct hreader {
  31   char *path;                   /* file to read */
  32   off_t size;                   /* file size */
  33   off_t read_offset;            /* for next hreader_read() */
  34   off_t buf_offset;             /* offset of start of buffer */
  35   char *buffer;                 /* input buffer */
  36   size_t bufsize;               /* buffer size */
  37   size_t bytes;                 /* size of last read */
  38 };
  39
  40 /** @brief Initialize a hands-off reader
  41  * @param path File to read
  42  * @param h Reader to initialize
  43  * @return 0 on success, -1 on error
  44  */
  45 int hreader_init(const char *path, struct hreader *h);
  46
  47 /** @brief Close a hands-off reader
  48  * @param h Reader to close
  49  */
  50 void hreader_close(struct hreader *h);
  51
  52 /** @brief Read some bytes
  53  * @param h Reader to read from
  54  * @param buffer Where to store bytes
  55  * @param n Maximum bytes to read
  56  * @return Bytes read, or 0 at EOF, or -1 on error
  57  */
  58 int hreader_read(struct hreader *h, void *buffer, size_t n);
  59
  60 /** @brief Read some bytes at a given offset
  61  * @param h Reader to read from
  62  * @param offset Offset to read at
  63  * @param buffer Where to store bytes
  64  * @param n Maximum bytes to read
  65  * @return Bytes read, or 0 at EOF, or -1 on error
  66  */
  67 int hreader_pread(struct hreader *h, void *buffer, size_t n, off_t offset);
  68
  69 /** @brief Seek within a file
  70  * @param h Reader to seek
  71  * @param offset Offset
  72  * @param whence SEEK_*
  73  * @return Result offset
  74  */
  75 off_t hreader_seek(struct hreader *h, off_t offset, int whence);
  76
  77 /** @brief Return file size
  78  * @param h Reader to find size of
  79  * @return Size in bytes
  80  */
  81 static inline off_t hreader_size(const struct hreader *h) {
  82   return h->size;
  83 }
  84
  85 /** @brief Test for end of file
  86  * @param h Reader to test
  87  * @return 1 at eof, 0 otherwise
  88  *
  89  * This tells you whether the next read will return 0 bytes, rather than
  90  * whether the last read reached end of file.  So it is slightly different to
  91  * feof().
  92  */
  93 static inline int hreader_eof(const struct hreader *h) {
  94   return h->read_offset == h->size;
  95 }
  96
  97 #endif /* HREADER_H */
  98
  99 /*
 100 Local Variables:
 101 c-basic-offset:2
 102 comment-column:40
 103 fill-column:79
 104 indent-tabs-mode:nil
 105 End:
 106 */