nucleus/library/filesystem/huge_file.h

   1 #ifndef HUGE_FILE_CLASS
   2 #define HUGE_FILE_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : huge_file                                                         *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2007-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include "byte_filer.h"
  19
  20 #include <basis/astring.h>
  21 #include <basis/outcome.h>
  22 #include <basis/common_outcomes.h>
  23 #include <basis/enhance_cpp.h>
  24
  25 namespace filesystem {
  26
  27 //! Supports reading and writing to very large files, > 4 gigabytes.
  28 /*!
  29   The standard file I/O functions only handle files up to 4 gigabytes.  This
  30   class extends the range to essentially unlimited sizes, as long as the
  31   operating system can accurately do relative seeks and can read/write to
  32   files of the size needed.
  33 */
  34
  35 class huge_file
  36 {
  37 public:
  38   huge_file(const basis::astring &filename, const basis::astring &permissions);
  39     //!< opens "filename" for access, where it presumably is a very large file.
  40     /*!< see byte filer for a description of the permissions.
  41     */
  42   virtual ~huge_file();
  43
  44   DEFINE_CLASS_NAME("huge_file");
  45
  46   enum outcomes {
  47     OKAY = basis::common::OKAY,
  48     FAILURE = basis::common::FAILURE,
  49     ACCESS_DENIED = basis::common::ACCESS_DENIED,
  50     BAD_INPUT = basis::common::BAD_INPUT
  51   };
  52
  53   const basis::astring &name() const;
  54     //!< returns the name of the file this operates on.
  55
  56   bool good() const;
  57     //!< reports if the file was opened successfully.
  58
  59   bool eof() const;
  60     //!< reports when the file pointer has reached the end of the file.
  61
  62   double length();
  63     //!< expensive operation accesses the file to find length.
  64
  65   double file_pointer() const { return _file_pointer; }
  66     //!< returns where we currently are in the file.
  67
  68   basis::outcome seek(double new_position,
  69           byte_filer::origins origin = byte_filer::FROM_CURRENT);
  70     //!< move the file pointer to "new_position" if possible.
  71     /*!< the relative seek is the easiest type of seek to accomplish with a
  72     huge file.  the other types are also supported, but take a bit more to
  73     implement. */
  74
  75   basis::outcome move_to(double absolute_posn);
  76     //!< simpler seek just goes from current location to "absolute_posn".
  77
  78   basis::outcome read(basis::byte_array &to_fill, int desired_size, int &size_read);
  79     //!< reads "desired_size" into "to_fill" if possible.
  80     /*!< "size_read" reports how many bytes were actually read. */
  81
  82   basis::outcome write(const basis::byte_array &to_write, int &size_written);
  83     //!< stores the array "to_write" into the file.
  84     /*!< "size_written" reports how many bytes got written. */
  85
  86   bool truncate();
  87     //!< truncates the file after the current position.
  88
  89   basis::outcome touch();
  90     //<! creates the file if it doesn't exist, or updates the time on the file.
  91
  92   void flush();
  93     //!< forces any pending writes to actually be saved to the file.
  94
  95 private:
  96   byte_filer *_real_file;  //!< supports us but is subject to 4g limit.
  97   double _file_pointer;  //!< position in the file if OS is tracking us.
  98 };
  99
 100 } //namespace.
 101
 102 #endif
 103