new home directory
[feisty_meow.git] / 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