src/KM_fileio.h

   1 /*
   2 Copyright (c) 2004-2009, John Hurst
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions
   7 are met:
   8 1. Redistributions of source code must retain the above copyright
   9    notice, this list of conditions and the following disclaimer.
  10 2. Redistributions in binary form must reproduce the above copyright
  11    notice, this list of conditions and the following disclaimer in the
  12    documentation and/or other materials provided with the distribution.
  13 3. The name of the author may not be used to endorse or promote products
  14    derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18 OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19 IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21 NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27   /*! \file    KM_fileio.h
  28     \version $Id$
  29     \brief   portable file i/o
  30   */
  31
  32 #ifndef _KM_FILEIO_H_
  33 #define _KM_FILEIO_H_
  34
  35 #include <KM_util.h>
  36 #include <string>
  37
  38 #ifdef KM_WIN32
  39 # include <io.h>
  40 #else
  41 # include <dirent.h>
  42 # include <unistd.h>
  43 # include <time.h>
  44 # include <sys/types.h>
  45 #include <regex.h>
  46 #endif
  47
  48 #include <sys/stat.h>
  49
  50
  51
  52 namespace Kumu
  53 {
  54   //
  55   class DirScanner
  56     {
  57     public:
  58 #ifdef KM_WIN32
  59       __int64               m_Handle;
  60       struct _finddatai64_t m_FileInfo;
  61 #else
  62       DIR*       m_Handle;
  63 #endif
  64
  65       DirScanner(void);
  66       ~DirScanner() { Close(); }
  67
  68       Result_t Open(const char*);
  69       Result_t Close();
  70       Result_t GetNext(char*);
  71     };
  72
  73 #ifdef KM_WIN32
  74   typedef __int64  fsize_t;
  75   typedef __int64  fpos_t;
  76   typedef HANDLE FileHandle;
  77
  78   enum SeekPos_t {
  79     SP_BEGIN = FILE_BEGIN,
  80     SP_POS   = FILE_CURRENT,
  81     SP_END   = FILE_END
  82   };
  83 #else
  84   typedef off_t    fsize_t;
  85   typedef off_t    fpos_t;
  86   typedef int      FileHandle;
  87   const FileHandle INVALID_HANDLE_VALUE = -1L;
  88
  89   enum SeekPos_t {
  90     SP_BEGIN = SEEK_SET,
  91     SP_POS   = SEEK_CUR,
  92     SP_END   = SEEK_END
  93   };
  94 #endif
  95
  96   //
  97 #ifndef KM_SMALL_FILES_OK
  98   template <bool sizecheck>    void compile_time_size_checker();
  99   template <> inline void compile_time_size_checker<false>() {}
 100   //
 101   // READ THIS if your compiler is complaining about a previously declared implementation of
 102   // compile_time_size_checker(). For example, GCC 4.0.1 looks like this:
 103   //
 104   // error: 'void Kumu::compile_time_size_checker() [with bool sizecheck = false]' previously declared here
 105   //
 106   // This is happening because the equality being tested below is false. The reason for this
 107   // will depend on your OS, but on Linux it is probably because you have not used -D_FILE_OFFSET_BITS=64
 108   // Adding this magic macro to your CFLAGS will get you going again. If you are on a system that
 109   // does not support 64-bit files, you can disable this check by using -DKM_SMALL_FILES_OK. You
 110   // will then of course be limited to file sizes < 4GB.
 111   //
 112   template <> inline void compile_time_size_checker<sizeof(Kumu::fsize_t)==sizeof(ui64_t)>() {}
 113 #endif
 114   //
 115
 116   const ui32_t Kilobyte = 1024;
 117   const ui32_t Megabyte = Kilobyte * Kilobyte;
 118   const ui32_t Gigabyte = Megabyte * Kilobyte;
 119
 120   const ui32_t MaxFilePath = Kilobyte;
 121
 122
 123   //------------------------------------------------------------------------------------------
 124   // Path Manglers
 125   //------------------------------------------------------------------------------------------
 126
 127   // types
 128   typedef std::list<std::string> PathCompList_t; // a list of path components
 129   typedef std::list<std::string> PathList_t; // a list of paths
 130
 131   // tests
 132   bool        PathExists(const std::string& Path); // true if the path exists in the filesystem
 133   bool        PathIsFile(const std::string& Path); // true if the path exists in the filesystem and is a file
 134   bool        PathIsDirectory(const std::string& Path); // true if the path exists in the filesystem and is a directory
 135   fsize_t     FileSize(const std::string& Path); // returns the size of a regular file, 0 for a directory or device
 136   bool        PathsAreEquivalent(const std::string& lhs, const std::string& rhs); // true if paths point to the same filesystem entry
 137
 138   // Returns free space and total space available for the given path
 139   Result_t   FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
 140
 141   // split and reassemble paths as lists of path components
 142   PathCompList_t& PathToComponents(const std::string& Path, PathCompList_t& CList, char separator = '/'); // removes '//'
 143   std::string ComponentsToPath(const PathCompList_t& CList, char separator = '/');
 144   std::string ComponentsToAbsolutePath(const PathCompList_t& CList, char separator = '/'); // add separator to the front
 145   bool        PathHasComponents(const std::string& Path, char separator = '/'); // true if paths starts with separator
 146
 147   bool        PathIsAbsolute(const std::string& Path, char separator = '/'); // true if path begins with separator
 148   std::string PathMakeAbsolute(const std::string& Path, char separator = '/'); // compute position of relative path using getcwd()
 149   std::string PathMakeLocal(const std::string& Path, const std::string& Parent); // remove Parent from front of Path, if it exists
 150   std::string PathMakeCanonical(const std::string& Path, char separator = '/'); // remove '.' and '..'
 151
 152   // common operations
 153   std::string PathBasename(const std::string& Path, char separator = '/'); // returns right-most path element (list back())
 154   std::string PathDirname(const std::string& Path, char separator = '/'); // returns everything but the right-most element
 155   std::string PathGetExtension(const std::string& Path); // returns everything in the right-most element following the right-most '.'
 156   std::string PathSetExtension(const std::string& Path, const std::string& Extension); // empty extension removes '.' as well
 157
 158
 159   //------------------------------------------------------------------------------------------
 160   // Path Search
 161   //------------------------------------------------------------------------------------------
 162
 163   // An interface for a path matching function, used by FindInPath() and FindInPaths() below
 164   //
 165   class IPathMatch
 166   {
 167   public:
 168     virtual ~IPathMatch() {}
 169     virtual bool Match(const std::string& s) const = 0;
 170   };
 171
 172   // matches any pathname
 173  class PathMatchAny : public IPathMatch
 174   {
 175   public:
 176     virtual ~PathMatchAny() {}
 177     inline bool Match(const std::string& s) const { return true; }
 178   };
 179
 180 #ifndef KM_WIN32
 181   // matches pathnames using a regular expression
 182  class PathMatchRegex : public IPathMatch
 183   {
 184     regex_t m_regex;
 185     PathMatchRegex();
 186     const PathMatchRegex& operator=(const PathMatchRegex&);
 187
 188   public:
 189     PathMatchRegex(const std::string& Pattern);
 190     PathMatchRegex(const PathMatchRegex&);
 191     virtual ~PathMatchRegex();
 192     bool Match(const std::string& s) const;
 193   };
 194
 195   // matches pathnames using a Bourne shell glob expression
 196  class PathMatchGlob : public IPathMatch
 197   {
 198     regex_t m_regex;
 199     PathMatchGlob();
 200     const PathMatchGlob& operator=(const PathMatchGlob&);
 201
 202   public:
 203     PathMatchGlob(const std::string& Pattern);
 204     PathMatchGlob(const PathMatchGlob&);
 205     virtual ~PathMatchGlob();
 206     bool Match(const std::string& s) const;
 207   };
 208 #endif /* !KM_WIN32 */
 209
 210   // Search all paths in SearchPaths for filenames matching Pattern (no directories are returned).
 211   // Put results in FoundPaths. Returns after first find if one_shot is true.
 212   PathList_t& FindInPath(const IPathMatch& Pattern, const std::string& SearchDir,
 213                          PathList_t& FoundPaths, bool one_shot = false, char separator = '/');
 214
 215   PathList_t& FindInPaths(const IPathMatch& Pattern, const PathList_t& SearchPaths,
 216                           PathList_t& FoundPaths, bool one_shot = false, char separator = '/');
 217
 218   //------------------------------------------------------------------------------------------
 219   // Directory Manipulation
 220   //------------------------------------------------------------------------------------------
 221
 222   // Create a directory, creates intermediate directories as necessary
 223   Result_t CreateDirectoriesInPath(const std::string& Path);
 224
 225   // Delete a file (fails if the path points to a directory)
 226   Result_t DeleteFile(const std::string& filename);
 227
 228   // Recursively remove a file or directory
 229   Result_t DeletePath(const std::string& pathname);
 230
 231   //------------------------------------------------------------------------------------------
 232   // File I/O Wrappers
 233   //------------------------------------------------------------------------------------------
 234
 235   // Instant IO for strings
 236   //
 237   // Reads an entire file into a string.
 238   Result_t ReadFileIntoString(const char* filename, std::string& outString, ui32_t max_size = 8 * Megabyte);
 239
 240   // Writes a string to a file, overwrites the existing file if present.
 241   Result_t WriteStringIntoFile(const char* filename, const std::string& inString);
 242
 243   // Instant IO for archivable objects
 244   //
 245   // Unarchives a file into an object
 246   Result_t ReadFileIntoObject(const std::string& Filename, IArchive& Object, ui32_t max_size = 8 * Kumu::Megabyte);
 247
 248   // Archives an object into a file
 249   Result_t WriteObjectIntoFile(const IArchive& Object, const std::string& Filename);
 250
 251   // Instant IO for memory buffers
 252   //
 253   // Unarchives a file into a buffer
 254   Result_t ReadFileIntoBuffer(const std::string& Filename, Kumu::ByteString& Buffer,
 255                               ui32_t max_size = 8 * Kumu::Megabyte);
 256
 257   // Archives a buffer into a file
 258   Result_t WriteBufferIntoFile(const Kumu::ByteString& Buffer, const std::string& Filename);
 259
 260
 261   //------------------------------------------------------------------------------------------
 262   // File I/O
 263   //------------------------------------------------------------------------------------------
 264
 265   //
 266   class FileReader
 267     {
 268       KM_NO_COPY_CONSTRUCT(FileReader);
 269
 270     protected:
 271       std::string m_Filename;
 272       FileHandle  m_Handle;
 273
 274     public:
 275       FileReader() : m_Handle(INVALID_HANDLE_VALUE) {}
 276       virtual ~FileReader() { Close(); }
 277
 278       Result_t OpenRead(const char*) const;                          // open the file for reading
 279       Result_t Close() const;                                        // close the file
 280       fsize_t  Size() const;                                         // returns the file's current size
 281       Result_t Seek(Kumu::fpos_t = 0, SeekPos_t = SP_BEGIN) const;   // move the file pointer
 282       Result_t Tell(Kumu::fpos_t* pos) const;                        // report the file pointer's location
 283       Result_t Read(byte_t*, ui32_t, ui32_t* = 0) const;             // read a buffer of data
 284
 285       inline Kumu::fpos_t Tell() const                               // report the file pointer's location
 286         {
 287           Kumu::fpos_t tmp_pos;
 288           Tell(&tmp_pos);
 289           return tmp_pos;
 290         }
 291
 292       inline bool IsOpen() {                                         // returns true if the file is open
 293         return (m_Handle != INVALID_HANDLE_VALUE);
 294       }
 295     };
 296
 297   //
 298   class FileWriter : public FileReader
 299     {
 300       class h__iovec;
 301       mem_ptr<h__iovec>  m_IOVec;
 302       KM_NO_COPY_CONSTRUCT(FileWriter);
 303
 304     public:
 305       FileWriter();
 306       virtual ~FileWriter();
 307
 308       Result_t OpenWrite(const char*);                               // open a new file, overwrites existing
 309       Result_t OpenModify(const char*);                              // open a file for read/write
 310
 311       // this part of the interface takes advantage of the iovec structure on
 312       // platforms that support it. For each call to Writev(const byte_t*, ui32_t, ui32_t*),
 313       // the given buffer is added to an internal iovec struct. All items on the list
 314       // are written to disk by a call to Writev();
 315       Result_t Writev(const byte_t*, ui32_t);                       // queue buffer for "gather" write
 316       Result_t Writev(ui32_t* = 0);                                 // write all queued buffers
 317
 318       // if you call this while there are unwritten items on the iovec list,
 319       // the iovec list will be written to disk before the given buffer,as though
 320       // you had called Writev() first.
 321       Result_t Write(const byte_t*, ui32_t, ui32_t* = 0);            // write buffer to disk
 322    };
 323
 324   Result_t CreateDirectoriesInPath(const std::string& Path);
 325   Result_t FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
 326   Result_t DeleteFile(const std::string& filename);
 327   Result_t DeletePath(const std::string& pathname);
 328
 329 } // namespace Kumu
 330
 331
 332 #endif // _KM_FILEIO_H_
 333
 334
 335 //
 336 // end KM_fileio.h
 337 //