src/KM_fileio.h

   1 /*
   2 Copyright (c) 2004-2014, 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 std::string&);
  69       Result_t Close();
  70       Result_t GetNext(char*);
  71     };
  72
  73
  74   //
  75   enum DirectoryEntryType_t {
  76     DET_FILE,
  77     DET_DIR,
  78     DET_DEV,
  79     DET_LINK
  80   };
  81
  82   //
  83   class DirScannerEx
  84   {
  85     std::string m_Dirname;
  86 #ifdef KM_WIN32
  87     __int64               m_Handle;
  88     struct _finddatai64_t m_FileInfo;
  89 #else
  90     DIR*       m_Handle;
  91 #endif
  92
  93     KM_NO_COPY_CONSTRUCT(DirScannerEx);
  94
  95   public:
  96
  97     DirScannerEx();
  98     ~DirScannerEx() { Close(); }
  99
 100     Result_t Open(const std::string& dirname);
 101     Result_t Close();
 102
 103
 104     inline Result_t GetNext(std::string& next_item_name) {
 105       DirectoryEntryType_t ft;
 106       return GetNext(next_item_name, ft);
 107     }
 108
 109     Result_t GetNext(std::string& next_item_name, DirectoryEntryType_t& next_item_type);
 110   };
 111
 112 #ifdef KM_WIN32
 113   typedef __int64  fsize_t;
 114   typedef __int64  fpos_t;
 115   typedef HANDLE FileHandle;
 116
 117   enum SeekPos_t {
 118     SP_BEGIN = FILE_BEGIN,
 119     SP_POS   = FILE_CURRENT,
 120     SP_END   = FILE_END
 121   };
 122 #else
 123   typedef off_t    fsize_t;
 124   typedef off_t    fpos_t;
 125   typedef int      FileHandle;
 126   const FileHandle INVALID_HANDLE_VALUE = -1L;
 127
 128   enum SeekPos_t {
 129     SP_BEGIN = SEEK_SET,
 130     SP_POS   = SEEK_CUR,
 131     SP_END   = SEEK_END
 132   };
 133 #endif
 134
 135   //
 136 #ifndef KM_SMALL_FILES_OK
 137   template <bool sizecheck>    void compile_time_size_checker();
 138   template <> inline void compile_time_size_checker<false>() {}
 139   //
 140   // READ THIS if your compiler is complaining about a previously declared implementation of
 141   // compile_time_size_checker(). For example, GCC 4.0.1 looks like this:
 142   //
 143   // error: 'void Kumu::compile_time_size_checker() [with bool sizecheck = false]' previously declared here
 144   //
 145   // This is happening because the equality being tested below is false. The reason for this
 146   // will depend on your OS, but on Linux it is probably because you have not used -D_FILE_OFFSET_BITS=64
 147   // Adding this magic macro to your CFLAGS will get you going again. If you are on a system that
 148   // does not support 64-bit files, you can disable this check by using -DKM_SMALL_FILES_OK. You
 149   // will then of course be limited to file sizes < 4GB.
 150   //
 151   template <> inline void compile_time_size_checker<sizeof(Kumu::fsize_t)==sizeof(ui64_t)>() {}
 152 #endif
 153   //
 154
 155   const ui32_t Kilobyte = 1024;
 156   const ui32_t Megabyte = Kilobyte * Kilobyte;
 157   const ui32_t Gigabyte = Megabyte * Kilobyte;
 158
 159   const ui32_t MaxFilePath = Kilobyte;
 160
 161
 162   //------------------------------------------------------------------------------------------
 163   // Path Manglers
 164   //------------------------------------------------------------------------------------------
 165
 166   // types
 167   typedef std::list<std::string> PathCompList_t; // a list of path components
 168   typedef std::list<std::string> PathList_t; // a list of paths
 169
 170   // tests
 171   bool        PathExists(const std::string& Path); // true if the path exists in the filesystem
 172   bool        PathIsFile(const std::string& Path); // true if the path exists in the filesystem and is a file
 173   bool        PathIsDirectory(const std::string& Path); // true if the path exists in the filesystem and is a directory
 174   fsize_t     FileSize(const std::string& Path); // returns the size of a regular file, 0 for a directory or device
 175   std::string PathCwd();
 176   bool        PathsAreEquivalent(const std::string& lhs, const std::string& rhs); // true if paths point to the same filesystem entry
 177
 178   // Returns free space and total space available for the given path
 179   Result_t    FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
 180
 181   // split and reassemble paths as lists of path components
 182   PathCompList_t& PathToComponents(const std::string& Path, PathCompList_t& CList, char separator = '/'); // removes '//'
 183   std::string ComponentsToPath(const PathCompList_t& CList, char separator = '/');
 184   std::string ComponentsToAbsolutePath(const PathCompList_t& CList, char separator = '/'); // add separator to the front
 185   bool        PathHasComponents(const std::string& Path, char separator = '/'); // true if paths starts with separator
 186
 187   bool        PathIsAbsolute(const std::string& Path, char separator = '/'); // true if path begins with separator
 188   std::string PathMakeAbsolute(const std::string& Path, char separator = '/'); // compute position of relative path using getcwd()
 189   std::string PathMakeLocal(const std::string& Path, const std::string& Parent); // remove Parent from front of Path, if it exists
 190   std::string PathMakeCanonical(const std::string& Path, char separator = '/'); // remove '.' and '..'
 191   bool        PathResolveLinks(const std::string& link_path, std::string& resolved_path, char separator = '/');
 192
 193   // common operations
 194   std::string PathBasename(const std::string& Path, char separator = '/'); // returns right-most path element (list back())
 195   std::string PathDirname(const std::string& Path, char separator = '/'); // returns everything but the right-most element
 196   std::string PathGetExtension(const std::string& Path); // returns everything in the right-most element following the right-most '.'
 197   std::string PathSetExtension(const std::string& Path, const std::string& Extension); // empty extension removes '.' as well
 198
 199   std::string PathJoin(const std::string& Path1, const std::string& Path2, char separator = '/');
 200   std::string PathJoin(const std::string& Path1, const std::string& Path2, const std::string& Path3, char separator = '/');
 201   std::string PathJoin(const std::string& Path1, const std::string& Path2,
 202                        const std::string& Path3, const std::string& Path4, char separator = '/');
 203
 204
 205   //------------------------------------------------------------------------------------------
 206   // Path Search
 207   //------------------------------------------------------------------------------------------
 208
 209   // An interface for a path matching function, used by FindInPath() and FindInPaths() below
 210   //
 211   class IPathMatch
 212   {
 213   public:
 214     virtual ~IPathMatch() {}
 215     virtual bool Match(const std::string& s) const = 0;
 216   };
 217
 218   // matches any pathname
 219  class PathMatchAny : public IPathMatch
 220   {
 221   public:
 222     virtual ~PathMatchAny() {}
 223     inline bool Match(const std::string& s) const { return true; }
 224   };
 225
 226 #ifndef KM_WIN32
 227   // matches pathnames using a regular expression
 228  class PathMatchRegex : public IPathMatch
 229   {
 230     regex_t m_regex;
 231     PathMatchRegex();
 232     const PathMatchRegex& operator=(const PathMatchRegex&);
 233
 234   public:
 235     PathMatchRegex(const std::string& Pattern);
 236     PathMatchRegex(const PathMatchRegex&);
 237     virtual ~PathMatchRegex();
 238     bool Match(const std::string& s) const;
 239   };
 240
 241   // matches pathnames using a Bourne shell glob expression
 242  class PathMatchGlob : public IPathMatch
 243   {
 244     regex_t m_regex;
 245     PathMatchGlob();
 246     const PathMatchGlob& operator=(const PathMatchGlob&);
 247
 248   public:
 249     PathMatchGlob(const std::string& Pattern);
 250     PathMatchGlob(const PathMatchGlob&);
 251     virtual ~PathMatchGlob();
 252     bool Match(const std::string& s) const;
 253   };
 254 #endif /* !KM_WIN32 */
 255
 256   // Search all paths in SearchPaths for filenames matching Pattern (no directories are returned).
 257   // Put results in FoundPaths. Returns after first find if one_shot is true.
 258   PathList_t& FindInPath(const IPathMatch& Pattern, const std::string& SearchDir,
 259                          PathList_t& FoundPaths, bool one_shot = false, char separator = '/');
 260
 261   PathList_t& FindInPaths(const IPathMatch& Pattern, const PathList_t& SearchPaths,
 262                           PathList_t& FoundPaths, bool one_shot = false, char separator = '/');
 263
 264   //------------------------------------------------------------------------------------------
 265   // Directory Manipulation
 266   //------------------------------------------------------------------------------------------
 267
 268   // Create a directory, creates intermediate directories as necessary
 269   Result_t CreateDirectoriesInPath(const std::string& Path);
 270
 271   // Delete a file (fails if the path points to a directory)
 272   Result_t DeleteFile(const std::string& filename);
 273
 274   // Recursively remove a file or directory
 275   Result_t DeletePath(const std::string& pathname);
 276
 277   //------------------------------------------------------------------------------------------
 278   // File I/O Wrappers
 279   //------------------------------------------------------------------------------------------
 280
 281   // Instant IO for strings
 282   //
 283   // Reads an entire file into a string.
 284   Result_t ReadFileIntoString(const std::string& filename, std::string& outString, ui32_t max_size = 8 * Megabyte);
 285
 286   // Writes a string to a file, overwrites the existing file if present.
 287   Result_t WriteStringIntoFile(const std::string& filename, const std::string& inString);
 288
 289   // Instant IO for archivable objects
 290   //
 291   // Unarchives a file into an object
 292   Result_t ReadFileIntoObject(const std::string& Filename, IArchive& Object, ui32_t max_size = 8 * Kumu::Megabyte);
 293
 294   // Archives an object into a file
 295   Result_t WriteObjectIntoFile(const IArchive& Object, const std::string& Filename);
 296
 297   // Instant IO for memory buffers
 298   //
 299   // Unarchives a file into a buffer
 300   Result_t ReadFileIntoBuffer(const std::string& Filename, Kumu::ByteString& Buffer,
 301                               ui32_t max_size = 8 * Kumu::Megabyte);
 302
 303   // Archives a buffer into a file
 304   Result_t WriteBufferIntoFile(const Kumu::ByteString& Buffer, const std::string& Filename);
 305
 306
 307   //------------------------------------------------------------------------------------------
 308   // File I/O
 309   //------------------------------------------------------------------------------------------
 310
 311   //
 312   class FileReader
 313     {
 314       KM_NO_COPY_CONSTRUCT(FileReader);
 315
 316     protected:
 317       std::string m_Filename;
 318       FileHandle  m_Handle;
 319
 320     public:
 321       FileReader() : m_Handle(INVALID_HANDLE_VALUE) {}
 322       virtual ~FileReader() { Close(); }
 323
 324       Result_t OpenRead(const std::string&) const;                          // open the file for reading
 325       Result_t Close() const;                                        // close the file
 326       fsize_t  Size() const;                                         // returns the file's current size
 327       Result_t Seek(Kumu::fpos_t = 0, SeekPos_t = SP_BEGIN) const;   // move the file pointer
 328       Result_t Tell(Kumu::fpos_t* pos) const;                        // report the file pointer's location
 329       Result_t Read(byte_t*, ui32_t, ui32_t* = 0) const;             // read a buffer of data
 330
 331       inline Kumu::fpos_t Tell() const                               // report the file pointer's location
 332         {
 333           Kumu::fpos_t tmp_pos;
 334           Tell(&tmp_pos);
 335           return tmp_pos;
 336         }
 337
 338       inline bool IsOpen() {                                         // returns true if the file is open
 339         return (m_Handle != INVALID_HANDLE_VALUE);
 340       }
 341     };
 342
 343   //
 344   class FileWriter : public FileReader
 345     {
 346       class h__iovec;
 347       mem_ptr<h__iovec>  m_IOVec;
 348       KM_NO_COPY_CONSTRUCT(FileWriter);
 349
 350     public:
 351       FileWriter();
 352       virtual ~FileWriter();
 353
 354       Result_t OpenWrite(const std::string&);                               // open a new file, overwrites existing
 355       Result_t OpenModify(const std::string&);                              // open a file for read/write
 356
 357       // this part of the interface takes advantage of the iovec structure on
 358       // platforms that support it. For each call to Writev(const byte_t*, ui32_t, ui32_t*),
 359       // the given buffer is added to an internal iovec struct. All items on the list
 360       // are written to disk by a call to Writev();
 361       Result_t Writev(const byte_t*, ui32_t);                       // queue buffer for "gather" write
 362       Result_t Writev(ui32_t* = 0);                                 // write all queued buffers
 363
 364       // if you call this while there are unwritten items on the iovec list,
 365       // the iovec list will be written to disk before the given buffer,as though
 366       // you had called Writev() first.
 367       Result_t Write(const byte_t*, ui32_t, ui32_t* = 0);            // write buffer to disk
 368    };
 369
 370   Result_t CreateDirectoriesInPath(const std::string& Path);
 371   Result_t FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
 372   Result_t DeleteFile(const std::string& filename);
 373   Result_t DeletePath(const std::string& pathname);
 374
 375 } // namespace Kumu
 376
 377
 378 #endif // _KM_FILEIO_H_
 379
 380
 381 //
 382 // end KM_fileio.h
 383 //