2 Copyright (c) 2004-2016, John Hurst
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
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.
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.
29 \brief portable file i/o
40 # include "dirent_win.h"
45 # include <sys/types.h>
62 ~DirScanner() { Close(); }
64 Result_t Open(const std::string&);
66 Result_t GetNext(char*);
71 enum DirectoryEntryType_t {
81 std::string m_Dirname;
84 KM_NO_COPY_CONSTRUCT(DirScannerEx);
89 ~DirScannerEx() { Close(); }
91 Result_t Open(const std::string& dirname);
95 inline Result_t GetNext(std::string& next_item_name) {
96 DirectoryEntryType_t ft;
97 return GetNext(next_item_name, ft);
100 Result_t GetNext(std::string& next_item_name, DirectoryEntryType_t& next_item_type);
104 typedef __int64 fsize_t;
105 typedef __int64 fpos_t;
106 typedef HANDLE FileHandle;
109 SP_BEGIN = FILE_BEGIN,
110 SP_POS = FILE_CURRENT,
114 typedef off_t fsize_t;
115 typedef off_t fpos_t;
116 typedef int FileHandle;
117 const FileHandle INVALID_HANDLE_VALUE = -1L;
127 #ifndef KM_SMALL_FILES_OK
128 template <bool sizecheck> void compile_time_size_checker();
129 template <> inline void compile_time_size_checker<false>() {}
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:
134 // error: 'void Kumu::compile_time_size_checker() [with bool sizecheck = false]' previously declared here
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.
142 template <> inline void compile_time_size_checker<sizeof(Kumu::fsize_t)==sizeof(ui64_t)>() {}
146 const ui32_t Kilobyte = 1024;
147 const ui32_t Megabyte = Kilobyte * Kilobyte;
148 const ui32_t Gigabyte = Megabyte * Kilobyte;
150 const ui32_t MaxFilePath = Kilobyte;
153 //------------------------------------------------------------------------------------------
155 //------------------------------------------------------------------------------------------
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
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
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);
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
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 = '/');
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
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 = '/');
196 //------------------------------------------------------------------------------------------
198 //------------------------------------------------------------------------------------------
200 // An interface for a path matching function, used by FindInPath() and FindInPaths() below
205 virtual ~IPathMatch() {}
206 virtual bool Match(const std::string& s) const = 0;
209 // matches any pathname
210 class PathMatchAny : public IPathMatch
213 virtual ~PathMatchAny() {}
214 inline bool Match(const std::string&) const { return true; }
218 // matches pathnames using a regular expression
219 class PathMatchRegex : public IPathMatch
223 const PathMatchRegex& operator=(const PathMatchRegex&);
226 PathMatchRegex(const std::string& Pattern);
227 PathMatchRegex(const PathMatchRegex&);
228 virtual ~PathMatchRegex();
229 bool Match(const std::string& s) const;
232 // matches pathnames using a Bourne shell glob expression
233 class PathMatchGlob : public IPathMatch
237 const PathMatchGlob& operator=(const PathMatchGlob&);
240 PathMatchGlob(const std::string& Pattern);
241 PathMatchGlob(const PathMatchGlob&);
242 virtual ~PathMatchGlob();
243 bool Match(const std::string& s) const;
245 #endif /* !KM_WIN32 */
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 = '/');
252 PathList_t& FindInPaths(const IPathMatch& Pattern, const PathList_t& SearchPaths,
253 PathList_t& FoundPaths, bool one_shot = false, char separator = '/');
255 std::string GetExecutablePath(const std::string& default_path);
257 //------------------------------------------------------------------------------------------
258 // Directory Manipulation
259 //------------------------------------------------------------------------------------------
261 // Create a directory, creates intermediate directories as necessary
262 Result_t CreateDirectoriesInPath(const std::string& Path);
264 // Delete a file (fails if the path points to a directory)
265 Result_t DeleteFile(const std::string& filename);
267 // Recursively remove a file or directory
268 Result_t DeletePath(const std::string& pathname);
270 // Remove the path only if it is a directory that is empty.
271 Result_t DeleteDirectoryIfEmpty(const std::string& path);
273 //------------------------------------------------------------------------------------------
275 //------------------------------------------------------------------------------------------
277 // Instant IO for strings
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);
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);
285 // Instant IO for archivable objects
287 // Unarchives a file into an object
288 Result_t ReadFileIntoObject(const std::string& Filename, IArchive& Object, ui32_t max_size = 8 * Kumu::Megabyte);
290 // Archives an object into a file
291 Result_t WriteObjectIntoFile(const IArchive& Object, const std::string& Filename);
293 // Instant IO for memory buffers
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);
299 // Archives a buffer into a file
300 Result_t WriteBufferIntoFile(const Kumu::ByteString& Buffer, const std::string& Filename);
304 //------------------------------------------------------------------------------------------
305 // wide char support for win32 file I/O
306 //------------------------------------------------------------------------------------------
309 Result_t wbstr_to_utf8(const Kumu::ByteString& in, std::string& out);
310 Result_t utf8_to_wbstr(const std::string& in, Kumu::ByteString& out);
313 //------------------------------------------------------------------------------------------
315 //------------------------------------------------------------------------------------------
320 KM_NO_COPY_CONSTRUCT(FileReader);
323 std::string m_Filename;
327 FileReader() : m_Handle(INVALID_HANDLE_VALUE) {}
328 virtual ~FileReader() { Close(); }
330 Result_t OpenRead(const std::string&) const; // open the file for reading
331 Result_t Close() const; // close the file
332 fsize_t Size() const; // returns the file's current size
333 Result_t Seek(Kumu::fpos_t = 0, SeekPos_t = SP_BEGIN) const; // move the file pointer
334 Result_t Tell(Kumu::fpos_t* pos) const; // report the file pointer's location
335 Result_t Read(byte_t*, ui32_t, ui32_t* = 0) const; // read a buffer of data
337 inline Kumu::fpos_t Tell() const // report the file pointer's location
339 Kumu::fpos_t tmp_pos;
344 inline bool IsOpen() { // returns true if the file is open
345 return (m_Handle != INVALID_HANDLE_VALUE);
350 class FileWriter : public FileReader
353 mem_ptr<h__iovec> m_IOVec;
354 KM_NO_COPY_CONSTRUCT(FileWriter);
358 virtual ~FileWriter();
360 Result_t OpenWrite(const std::string&); // open a new file, overwrites existing
361 Result_t OpenModify(const std::string&); // open a file for read/write
363 // this part of the interface takes advantage of the iovec structure on
364 // platforms that support it. For each call to Writev(const byte_t*, ui32_t, ui32_t*),
365 // the given buffer is added to an internal iovec struct. All items on the list
366 // are written to disk by a call to Writev();
367 Result_t Writev(const byte_t*, ui32_t); // queue buffer for "gather" write
368 Result_t Writev(ui32_t* = 0); // write all queued buffers
370 // if you call this while there are unwritten items on the iovec list,
371 // the iovec list will be written to disk before the given buffer,as though
372 // you had called Writev() first.
373 Result_t Write(const byte_t*, ui32_t, ui32_t* = 0); // write buffer to disk
376 Result_t CreateDirectoriesInPath(const std::string& Path);
377 Result_t FreeSpaceForPath(const std::string& path, Kumu::fsize_t& free_space, Kumu::fsize_t& total_space);
378 Result_t DeleteFile(const std::string& filename);
379 Result_t DeletePath(const std::string& pathname);
384 #endif // _KM_FILEIO_H_