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: KM_fileio.h,v 1.22 2015/10/07 16:41:23 jhurst Exp $
  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&) 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   std::string GetExecutablePath(const std::string& default_path);
 265
 266   //------------------------------------------------------------------------------------------
 267   // Directory Manipulation
 268   //------------------------------------------------------------------------------------------
 269
 270   // Create a directory, creates intermediate directories as necessary
 271   Result_t CreateDirectoriesInPath(const std::string& Path);
 272
 273   // Delete a file (fails if the path points to a directory)
 274   Result_t DeleteFile(const std::string& filename);
 275
 276   // Recursively remove a file or directory
 277   Result_t DeletePath(const std::string& pathname);
 278
 279   // Remove the path only if it is a directory that is empty.
 280   Result_t DeleteDirectoryIfEmpty(const std::string& path);
 281
 282   //------------------------------------------------------------------------------------------
 283   // File I/O Wrappers
 284   //------------------------------------------------------------------------------------------
 285
 286   // Instant IO for strings
 287   //
 288   // Reads an entire file into a string.
 289   Result_t ReadFileIntoString(const std::string& filename, std::string& outString, ui32_t max_size = 8 * Megabyte);
 290
 291   // Writes a string to a file, overwrites the existing file if present.
 292   Result_t WriteStringIntoFile(const std::string& filename, const std::string& inString);
 293
 294   // Instant IO for archivable objects
 295   //
 296   // Unarchives a file into an object
 297   Result_t ReadFileIntoObject(const std::string& Filename, IArchive& Object, ui32_t max_size = 8 * Kumu::Megabyte);
 298
 299   // Archives an object into a file
 300   Result_t WriteObjectIntoFile(const IArchive& Object, const std::string& Filename);
 301
 302   // Instant IO for memory buffers
 303   //
 304   // Unarchives a file into a buffer
 305   Result_t ReadFileIntoBuffer(const std::string& Filename, Kumu::ByteString& Buffer,
 306                               ui32_t max_size = 8 * Kumu::Megabyte);
 307
 308   // Archives a buffer into a file
 309   Result_t WriteBufferIntoFile(const Kumu::ByteString& Buffer, const std::string& Filename);
 310
 311
 312   //------------------------------------------------------------------------------------------
 313   // File I/O
 314   //------------------------------------------------------------------------------------------
 315
 316   //
 317   class FileReader
 318     {
 319       KM_NO_COPY_CONSTRUCT(FileReader);
 320
 321     protected:
 322       std::string m_Filename;
 323       FileHandle  m_Handle;
 324
 325     public:
 326       FileReader() : m_Handle(INVALID_HANDLE_VALUE) {}
 327       virtual ~FileReader() { Close(); }
 328
 329       Result_t OpenRead(const std::string&) const;                          // open the file for reading
 330       Result_t Close() const;                                        // close the file
 331       fsize_t  Size() const;                                         // returns the file's current size
 332       Result_t Seek(Kumu::fpos_t = 0, SeekPos_t = SP_BEGIN) const;   // move the file pointer
 333       Result_t Tell(Kumu::fpos_t* pos) const;                        // report the file pointer's location
 334       Result_t Read(byte_t*, ui32_t, ui32_t* = 0) const;             // read a buffer of data
 335
 336       inline Kumu::fpos_t Tell() const                               // report the file pointer's location
 337         {
 338           Kumu::fpos_t tmp_pos;
 339           Tell(&tmp_pos);
 340           return tmp_pos;
 341         }
 342
 343       inline bool IsOpen() {                                         // returns true if the file is open
 344         return (m_Handle != INVALID_HANDLE_VALUE);
 345       }
 346     };
 347
 348   //
 349   class FileWriter : public FileReader
 350     {
 351       class h__iovec;
 352       mem_ptr<h__iovec>  m_IOVec;
 353       KM_NO_COPY_CONSTRUCT(FileWriter);
 354
 355     public:
 356       FileWriter();
 357       virtual ~FileWriter();
 358
 359       Result_t OpenWrite(const std::string&);                               // open a new file, overwrites existing
 360       Result_t OpenModify(const std::string&);                              // open a file for read/write
 361
 362       // this part of the interface takes advantage of the iovec structure on
 363       // platforms that support it. For each call to Writev(const byte_t*, ui32_t, ui32_t*),
 364       // the given buffer is added to an internal iovec struct. All items on the list
 365       // are written to disk by a call to Writev();
 366       Result_t Writev(const byte_t*, ui32_t);                       // queue buffer for "gather" write
 367       Result_t Writev(ui32_t* = 0);                                 // write all queued buffers
 368
 369       // if you call this while there are unwritten items on the iovec list,
 370       // the iovec list will be written to disk before the given buffer,as though
 371       // you had called Writev() first.
 372       Result_t Write(const byte_t*, ui32_t, ui32_t* = 0);            // write buffer to disk
 373    };
 374
 375   Result_t CreateDirectoriesInPath(const std::string& Path);
 376   Result_t FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
 377   Result_t DeleteFile(const std::string& filename);
 378   Result_t DeletePath(const std::string& pathname);
 379
 380 } // namespace Kumu
 381
 382
 383 #endif // _KM_FILEIO_H_
 384
 385
 386 //
 387 // end KM_fileio.h
 388 //