fileSystem.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_BASE_ARCH_FILE_SYSTEM_H
25 #define PXR_BASE_ARCH_FILE_SYSTEM_H
26 
30 
31 #include "pxr/pxr.h"
32 #include "pxr/base/arch/api.h"
33 #include "pxr/base/arch/defines.h"
34 #include "pxr/base/arch/inttypes.h"
35 #include <memory>
36 #include <cstdio>
37 #include <string>
38 #include <set>
39 
40 #include <fcntl.h>
41 #include <sys/types.h>
42 #include <sys/stat.h>
43 
44 #if defined(ARCH_OS_LINUX)
45 #include <unistd.h>
46 #include <sys/statfs.h>
47 #include <glob.h>
48 #elif defined(ARCH_OS_DARWIN)
49 #include <unistd.h>
50 #include <sys/mount.h>
51 #include <glob.h>
52 #elif defined(ARCH_OS_WINDOWS)
53 #include <io.h>
54 #include <windows.h>
55 #include <stringapiset.h>
56 #endif
57 
58 PXR_NAMESPACE_OPEN_SCOPE
59 
62 #if !defined(ARCH_OS_WINDOWS)
63  #ifdef _POSIX_VERSION
64  #include <limits.h> /* for PATH_MAX */
65  #else
66  #include <sys/param.h> /* for MAXPATHLEN */
67  #endif
68 #else
69  // XXX -- Should probably have ARCH_ macro for this.
70  #define S_ISDIR(m) (((m) & S_IFMT) == S_IFDIR)
71 
72  // See https://msdn.microsoft.com/en-us/library/1w06ktdy.aspx
73  // XXX -- Should probably have Arch enum for these.
74  #define F_OK 0 // Test for existence.
75  #define X_OK 1 // Test for execute permission.
76  #define W_OK 2 // Test for write permission.
77  #define R_OK 4 // Test for read permission.
78 #endif
79 
80 #if defined(ARCH_OS_WINDOWS)
81  #define ARCH_GLOB_NOCHECK 1
82  #define ARCH_GLOB_MARK 2
83  #define ARCH_GLOB_NOSORT 4
84 #else
85  #define ARCH_GLOB_NOCHECK GLOB_NOCHECK
86  #define ARCH_GLOB_MARK GLOB_MARK
87  #define ARCH_GLOB_NOSORT GLOB_NOSORT
88 #endif
89 #define ARCH_GLOB_DEFAULT (ARCH_GLOB_NOCHECK | ARCH_GLOB_MARK)
90 
91 #ifndef ARCH_PATH_MAX
92  #ifdef PATH_MAX
93  #define ARCH_PATH_MAX PATH_MAX
94  #else
95  #ifdef MAXPATHLEN
96  #define ARCH_PATH_MAX MAXPATHLEN
97  #else
98  #ifdef _MAX_PATH
99  #define ARCH_PATH_MAX _MAX_PATH
100  #else
101  #define ARCH_PATH_MAX 1024
102  #endif
103  #endif
104  #endif
105 #endif
106 
107 #if defined(ARCH_OS_WINDOWS)
108  #define ARCH_PATH_SEP "\\"
109  #define ARCH_PATH_LIST_SEP ";"
110  #define ARCH_REL_PATH_IDENT ".\\"
111 #else
112  #define ARCH_PATH_SEP "/"
113  #define ARCH_PATH_LIST_SEP ":"
114  #define ARCH_REL_PATH_IDENT "./"
115 #endif
116 
117 #if defined(ARCH_OS_WINDOWS)
118 typedef struct __stat64 ArchStatType;
119 #else
120 typedef struct stat ArchStatType;
121 #endif
122 
127 
133 ARCH_API FILE*
134 ArchOpenFile(char const* fileName, char const* mode);
135 
136 #if defined(ARCH_OS_WINDOWS)
137 # define ArchChmod(path, mode) _chmod(path, mode)
138 #else
139 # define ArchChmod(path, mode) chmod(path, mode)
140 #endif
141 
142 #if defined(ARCH_OS_WINDOWS)
143 # define ArchCloseFile(fd) _close(fd)
144 #else
145 # define ArchCloseFile(fd) close(fd)
146 #endif
147 
148 #if defined(ARCH_OS_WINDOWS)
149 # define ArchUnlinkFile(path) _unlink(path)
150 #else
151 # define ArchUnlinkFile(path) unlink(path)
152 #endif
153 
154 #if defined(ARCH_OS_WINDOWS)
155  ARCH_API int ArchFileAccess(const char* path, int mode);
156 #else
157 # define ArchFileAccess(path, mode) access(path, mode)
158 #endif
159 
160 #if defined(ARCH_OS_WINDOWS)
161 # define ArchFdOpen(fd, mode) _fdopen(fd, mode)
162 #else
163 # define ArchFdOpen(fd, mode) fdopen(fd, mode)
164 #endif
165 
166 #if defined(ARCH_OS_WINDOWS)
167 # define ArchFileNo(stream) _fileno(stream)
168 #else
169 # define ArchFileNo(stream) fileno(stream)
170 #endif
171 
172 #if defined(ARCH_OS_WINDOWS)
173 # define ArchFileIsaTTY(stream) _isatty(stream)
174 #else
175 # define ArchFileIsaTTY(stream) isatty(stream)
176 #endif
177 
178 #if defined(ARCH_OS_WINDOWS)
179  ARCH_API int ArchRmDir(const char* path);
180 #else
181 # define ArchRmDir(path) rmdir(path)
182 #endif
183 
187 ARCH_API int64_t ArchGetFileLength(const char* fileName);
188 ARCH_API int64_t ArchGetFileLength(FILE *file);
189 
191 ARCH_API std::string ArchGetFileName(FILE *file);
192 
199 ARCH_API bool ArchStatIsWritable(const ArchStatType *st);
200 
206 ARCH_API bool ArchGetModificationTime(const char* pathname, double* time);
207 
212 ARCH_API double ArchGetModificationTime(const ArchStatType& st);
213 
223 ARCH_API std::string ArchNormPath(const std::string& path,
224  bool stripDriveSpecifier = false);
225 
230 ARCH_API std::string ArchAbsPath(const std::string& path);
231 
237 ARCH_API bool ArchGetStatMode(const char *pathname, int *mode);
238 
248 ARCH_API const char *ArchGetTmpDir();
249 
263 ARCH_API
264 std::string ArchMakeTmpFileName(const std::string& prefix,
265  const std::string& suffix = std::string());
266 
276 ARCH_API
277 int ArchMakeTmpFile(const std::string& prefix, std::string* pathname = 0);
278 
287 ARCH_API
288 int ArchMakeTmpFile(const std::string& tmpdir,
289  const std::string& prefix, std::string* pathname = 0);
290 
299 ARCH_API
300 std::string ArchMakeTmpSubdir(const std::string& tmpdir,
301  const std::string& prefix);
302 
303 // Helper 'deleter' for use with std::unique_ptr for file mappings.
304 struct Arch_Unmapper {
305  Arch_Unmapper() : _length(~0) {}
306  explicit Arch_Unmapper(size_t length) : _length(length) {}
307  ARCH_API void operator()(char *mapStart) const;
308  ARCH_API void operator()(char const *mapStart) const;
309  size_t GetLength() const { return _length; }
310 private:
311  size_t _length;
312 };
313 
318 using ArchConstFileMapping = std::unique_ptr<char const, Arch_Unmapper>;
319 using ArchMutableFileMapping = std::unique_ptr<char, Arch_Unmapper>;
320 
322 inline size_t
324  return m.get_deleter().GetLength();
325 }
326 
328 inline size_t
329 ArchGetFileMappingLength(ArchMutableFileMapping const &m) {
330  return m.get_deleter().GetLength();
331 }
332 
337 ARCH_API
339 ArchMapFileReadOnly(FILE *file, std::string *errMsg=nullptr);
340 
342 ARCH_API
344 ArchMapFileReadOnly(std::string const& path, std::string *errMsg=nullptr);
345 
352 ARCH_API
353 ArchMutableFileMapping
354 ArchMapFileReadWrite(FILE *file, std::string *errMsg=nullptr);
355 
357 ARCH_API
358 ArchMutableFileMapping
359 ArchMapFileReadWrite(std::string const& path, std::string *errMsg=nullptr);
360 
361 enum ArchMemAdvice {
362  ArchMemAdviceNormal, // Treat range with default behavior.
363  ArchMemAdviceWillNeed, // OS may prefetch this range.
364  ArchMemAdviceDontNeed, // OS may free resources related to this range.
365  ArchMemAdviceRandomAccess, // Prefetching may not be beneficial.
366 };
367 
372 ARCH_API
373 void ArchMemAdvise(void const *addr, size_t len, ArchMemAdvice adv);
374 
387 ARCH_API
388 bool
390  void const *addr, size_t len, unsigned char *pageMap);
391 
396 ARCH_API
397 int64_t ArchPRead(FILE *file, void *buffer, size_t count, int64_t offset);
398 
403 ARCH_API
404 int64_t ArchPWrite(FILE *file, void const *bytes, size_t count, int64_t offset);
405 
408 ARCH_API
409 std::string ArchReadLink(const char* path);
410 
411 enum ArchFileAdvice {
412  ArchFileAdviceNormal, // Treat range with default behavior.
413  ArchFileAdviceWillNeed, // OS may prefetch this range.
414  ArchFileAdviceDontNeed, // OS may free resources related to this range.
415  ArchFileAdviceRandomAccess, // Prefetching may not be beneficial.
416 };
417 
422 ARCH_API
423 void ArchFileAdvise(FILE *file, int64_t offset, size_t count,
424  ArchFileAdvice adv);
425 
426 #if defined(ARCH_OS_WINDOWS)
427 
429 inline std::string ArchWindowsUtf16ToUtf8(const std::wstring &wstr)
430 {
431  if (wstr.empty()) return std::string();
432  // first call is only to get required size for string
433  int size = WideCharToMultiByte(
434  CP_UTF8, 0, wstr.data(), (int)wstr.size(), NULL, 0, NULL, NULL);
435  if (size == 0) return std::string();
436  std::string str(size, 0);
437  if (WideCharToMultiByte(CP_UTF8, 0, wstr.data(), (int)wstr.size(),
438  &str[0], size, NULL, NULL) == 0) {
439  return std::string();
440  }
441  return str;
442 }
443 
445 inline std::wstring ArchWindowsUtf8ToUtf16(const std::string &str)
446 {
447  if (str.empty()) return std::wstring();
448  // first call is only to get required size for wstring
449  int size = MultiByteToWideChar(
450  CP_UTF8, 0, str.data(), (int)str.size(), NULL, 0);
451  if (size == 0) return std::wstring();
452  std::wstring wstr(size, 0);
453  if(MultiByteToWideChar(
454  CP_UTF8, 0, str.data(), (int)str.size(), &wstr[0], size) == 0) {
455  return std::wstring();
456  }
457  return wstr;
458 }
459 
460 #endif
461 
463 
464 PXR_NAMESPACE_CLOSE_SCOPE
465 
466 #endif // PXR_BASE_ARCH_FILE_SYSTEM_H
ARCH_API FILE * ArchOpenFile(char const *fileName, char const *mode)
Opens a file.
ARCH_API void ArchMemAdvise(void const *addr, size_t len, ArchMemAdvice adv)
Advise the OS regarding how the application intends to access a range of memory.
ARCH_API std::string ArchAbsPath(const std::string &path)
Returns the canonical absolute path of the specified filename.
ARCH_API void ArchFileAdvise(FILE *file, int64_t offset, size_t count, ArchFileAdvice adv)
Advise the OS regarding how the application intends to access a range of bytes in a file.
ARCH_API std::string ArchNormPath(const std::string &path, bool stripDriveSpecifier=false)
Normalizes the specified path, eliminating double slashes, etc.
ARCH_API ArchConstFileMapping ArchMapFileReadOnly(FILE *file, std::string *errMsg=nullptr)
Privately map the passed file into memory and return a unique_ptr to the read-only mapped contents.
std::unique_ptr< char const, Arch_Unmapper > ArchConstFileMapping
ArchConstFileMapping and ArchMutableFileMapping are std::unique_ptr<char const *, ....
Definition: fileSystem.h:318
ARCH_API ArchMutableFileMapping ArchMapFileReadWrite(FILE *file, std::string *errMsg=nullptr)
Privately map the passed file into memory and return a unique_ptr to the copy-on-write mapped content...
ARCH_API const char * ArchGetTmpDir()
Return the path to a temporary directory for this platform.
ARCH_API int ArchMakeTmpFile(const std::string &prefix, std::string *pathname=0)
Create a temporary file, in a system-determined temporary directory.
ARCH_API std::string ArchReadLink(const char *path)
Returns the value of the symbolic link at path.
ARCH_API int64_t ArchGetFileLength(const char *fileName)
Return the length of a file in bytes.
size_t ArchGetFileMappingLength(ArchConstFileMapping const &m)
Return the length of an ArchConstFileMapping.
Definition: fileSystem.h:323
ARCH_API bool ArchGetStatMode(const char *pathname, int *mode)
Returns the permissions mode (mode_t) for the given pathname.
Define integral types.
ARCH_API bool ArchStatIsWritable(const ArchStatType *st)
Returns true if the data in stat struct st indicates that the target file or directory is writable.
ARCH_API bool ArchQueryMappedMemoryResidency(void const *addr, size_t len, unsigned char *pageMap)
Report whether or not the mapped virtual memory pages starting at addr for len bytes are resident in ...
Defines useful mathematical limits.
ARCH_API std::string ArchGetFileName(FILE *file)
Return a filename for this file, if one can be obtained.
ARCH_API int64_t ArchPRead(FILE *file, void *buffer, size_t count, int64_t offset)
Read up to count bytes from offset in file into buffer.
ARCH_API std::string ArchMakeTmpSubdir(const std::string &tmpdir, const std::string &prefix)
Create a temporary sub-direcrory, in a given temporary directory.
ARCH_API int64_t ArchPWrite(FILE *file, void const *bytes, size_t count, int64_t offset)
Write up to count bytes from buffer to file at offset.
ARCH_API bool ArchGetModificationTime(const char *pathname, double *time)
Returns the modification time (mtime) in seconds for a file.
ARCH_API std::string ArchMakeTmpFileName(const std::string &prefix, const std::string &suffix=std::string())
Make a temporary file name, in a system-determined temporary directory.