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   std::string PathCwd();
 137   bool        PathsAreEquivalent(const std::string& lhs, const std::string& rhs); // true if paths point to the same filesystem entry
 138
 139   // Returns free space and total space available for the given path
 140   Result_t    FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
 141
 142   // split and reassemble paths as lists of path components
 143   PathCompList_t& PathToComponents(const std::string& Path, PathCompList_t& CList, char separator = '/'); // removes '//'
 144   std::string ComponentsToPath(const PathCompList_t& CList, char separator = '/');
 145   std::string ComponentsToAbsolutePath(const PathCompList_t& CList, char separator = '/'); // add separator to the front
 146   bool        PathHasComponents(const std::string& Path, char separator = '/'); // true if paths starts with separator
 147
 148   bool        PathIsAbsolute(const std::string& Path, char separator = '/'); // true if path begins with separator
 149   std::string PathMakeAbsolute(const std::string& Path, char separator = '/'); // compute position of relative path using getcwd()
 150   std::string PathMakeLocal(const std::string& Path, const std::string& Parent); // remove Parent from front of Path, if it exists
 151   std::string PathMakeCanonical(const std::string& Path, char separator = '/'); // remove '.' and '..'
 152   bool        PathResolveLinks(const std::string& link_path, std::string& resolved_path, char separator = '/');
 153
 154   // common operations
 155   std::string PathBasename(const std::string& Path, char separator = '/'); // returns right-most path element (list back())
 156   std::string PathDirname(const std::string& Path, char separator = '/'); // returns everything but the right-most element
 157   std::string PathGetExtension(const std::string& Path); // returns everything in the right-most element following the right-most '.'
 158   std::string PathSetExtension(const std::string& Path, const std::string& Extension); // empty extension removes '.' as well
 159
 160   std::string PathJoin(const std::string& Path1, const std::string& Path2, char separator = '/');
 161   std::string PathJoin(const std::string& Path1, const std::string& Path2, const std::string& Path3, char separator = '/');
 162   std::string PathJoin(const std::string& Path1, const std::string& Path2,
 163                        const std::string& Path3, const std::string& Path4, char separator = '/');
 164
 165
 166   //------------------------------------------------------------------------------------------
 167   // Path Search
 168   //------------------------------------------------------------------------------------------
 169
 170   // An interface for a path matching function, used by FindInPath() and FindInPaths() below
 171   //
 172   class IPathMatch
 173   {
 174   public:
 175     virtual ~IPathMatch() {}
 176     virtual bool Match(const std::string& s) const = 0;
 177   };
 178
 179   // matches any pathname
 180  class PathMatchAny : public IPathMatch
 181   {
 182   public:
 183     virtual ~PathMatchAny() {}
 184     inline bool Match(const std::string& s) const { return true; }
 185   };
 186
 187 #ifndef KM_WIN32
 188   // matches pathnames using a regular expression
 189  class PathMatchRegex : public IPathMatch
 190   {
 191     regex_t m_regex;
 192     PathMatchRegex();
 193     const PathMatchRegex& operator=(const PathMatchRegex&);
 194
 195   public:
 196     PathMatchRegex(const std::string& Pattern);
 197     PathMatchRegex(const PathMatchRegex&);
 198     virtual ~PathMatchRegex();
 199     bool Match(const std::string& s) const;
 200   };
 201
 202   // matches pathnames using a Bourne shell glob expression
 203  class PathMatchGlob : public IPathMatch
 204   {
 205     regex_t m_regex;
 206     PathMatchGlob();
 207     const PathMatchGlob& operator=(const PathMatchGlob&);
 208
 209   public:
 210     PathMatchGlob(const std::string& Pattern);
 211     PathMatchGlob(const PathMatchGlob&);
 212     virtual ~PathMatchGlob();
 213     bool Match(const std::string& s) const;
 214   };
 215 #endif /* !KM_WIN32 */
 216
 217   // Search all paths in SearchPaths for filenames matching Pattern (no directories are returned).
 218   // Put results in FoundPaths. Returns after first find if one_shot is true.
 219   PathList_t& FindInPath(const IPathMatch& Pattern, const std::string& SearchDir,
 220                          PathList_t& FoundPaths, bool one_shot = false, char separator = '/');
 221
 222   PathList_t& FindInPaths(const IPathMatch& Pattern, const PathList_t& SearchPaths,
 223                           PathList_t& FoundPaths, bool one_shot = false, char separator = '/');
 224
 225   //------------------------------------------------------------------------------------------
 226   // Directory Manipulation
 227   //------------------------------------------------------------------------------------------
 228
 229   // Create a directory, creates intermediate directories as necessary
 230   Result_t CreateDirectoriesInPath(const std::string& Path);
 231
 232   // Delete a file (fails if the path points to a directory)
 233   Result_t DeleteFile(const std::string& filename);
 234
 235   // Recursively remove a file or directory
 236   Result_t DeletePath(const std::string& pathname);
 237
 238   //------------------------------------------------------------------------------------------
 239   // File I/O Wrappers
 240   //------------------------------------------------------------------------------------------
 241
 242   // Instant IO for strings
 243   //
 244   // Reads an entire file into a string.
 245   Result_t ReadFileIntoString(const char* filename, std::string& outString, ui32_t max_size = 8 * Megabyte);
 246
 247   // Writes a string to a file, overwrites the existing file if present.
 248   Result_t WriteStringIntoFile(const char* filename, const std::string& inString);
 249
 250   // Instant IO for archivable objects
 251   //
 252   // Unarchives a file into an object
 253   Result_t ReadFileIntoObject(const std::string& Filename, IArchive& Object, ui32_t max_size = 8 * Kumu::Megabyte);
 254
 255   // Archives an object into a file
 256   Result_t WriteObjectIntoFile(const IArchive& Object, const std::string& Filename);
 257
 258   // Instant IO for memory buffers
 259   //
 260   // Unarchives a file into a buffer
 261   Result_t ReadFileIntoBuffer(const std::string& Filename, Kumu::ByteString& Buffer,
 262                               ui32_t max_size = 8 * Kumu::Megabyte);
 263
 264   // Archives a buffer into a file
 265   Result_t WriteBufferIntoFile(const Kumu::ByteString& Buffer, const std::string& Filename);
 266
 267
 268   //------------------------------------------------------------------------------------------
 269   // File I/O
 270   //------------------------------------------------------------------------------------------
 271
 272   //
 273   class FileReader
 274     {
 275       KM_NO_COPY_CONSTRUCT(FileReader);
 276
 277     protected:
 278       std::string m_Filename;
 279       FileHandle  m_Handle;
 280
 281     public:
 282       FileReader() : m_Handle(INVALID_HANDLE_VALUE) {}
 283       virtual ~FileReader() { Close(); }
 284
 285       Result_t OpenRead(const char*) const;                          // open the file for reading
 286       Result_t Close() const;                                        // close the file
 287       fsize_t  Size() const;                                         // returns the file's current size
 288       Result_t Seek(Kumu::fpos_t = 0, SeekPos_t = SP_BEGIN) const;   // move the file pointer
 289       Result_t Tell(Kumu::fpos_t* pos) const;                        // report the file pointer's location
 290       Result_t Read(byte_t*, ui32_t, ui32_t* = 0) const;             // read a buffer of data
 291
 292       inline Kumu::fpos_t Tell() const                               // report the file pointer's location
 293         {
 294           Kumu::fpos_t tmp_pos;
 295           Tell(&tmp_pos);
 296           return tmp_pos;
 297         }
 298
 299       inline bool IsOpen() {                                         // returns true if the file is open
 300         return (m_Handle != INVALID_HANDLE_VALUE);
 301       }
 302     };
 303
 304   //
 305   class FileWriter : public FileReader
 306     {
 307       class h__iovec;
 308       mem_ptr<h__iovec>  m_IOVec;
 309       KM_NO_COPY_CONSTRUCT(FileWriter);
 310
 311     public:
 312       FileWriter();
 313       virtual ~FileWriter();
 314
 315       Result_t OpenWrite(const char*);                               // open a new file, overwrites existing
 316       Result_t OpenModify(const char*);                              // open a file for read/write
 317
 318       // this part of the interface takes advantage of the iovec structure on
 319       // platforms that support it. For each call to Writev(const byte_t*, ui32_t, ui32_t*),
 320       // the given buffer is added to an internal iovec struct. All items on the list
 321       // are written to disk by a call to Writev();
 322       Result_t Writev(const byte_t*, ui32_t);                       // queue buffer for "gather" write
 323       Result_t Writev(ui32_t* = 0);                                 // write all queued buffers
 324
 325       // if you call this while there are unwritten items on the iovec list,
 326       // the iovec list will be written to disk before the given buffer,as though
 327       // you had called Writev() first.
 328       Result_t Write(const byte_t*, ui32_t, ui32_t* = 0);            // write buffer to disk
 329    };
 330
 331   Result_t CreateDirectoriesInPath(const std::string& Path);
 332   Result_t FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
 333   Result_t DeleteFile(const std::string& filename);
 334   Result_t DeletePath(const std::string& pathname);
 335
 336 } // namespace Kumu
 337
 338
 339 #endif // _KM_FILEIO_H_
 340
 341
 342 //
 343 // end KM_fileio.h
 344 //