src/KM_fileio.h

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