HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 ARCH_FILESYSTEM_H
25 #define ARCH_FILESYSTEM_H
26 
27 /// \file arch/fileSystem.h
28 /// \ingroup group_arch_SystemFunctions
29 /// Architecture dependent file system access
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 #endif
55 
57 
58 /// \addtogroup group_arch_SystemFunctions
59 ///@{
60 #if !defined(ARCH_OS_WINDOWS)
61  #ifdef _POSIX_VERSION
62  #include <limits.h> /* for PATH_MAX */
63  #else
64  #include <sys/param.h> /* for MAXPATHLEN */
65  #endif
66 #else
67  // XXX -- Should probably have ARCH_ macro for this.
68  #define S_ISDIR(m) (((m) & S_IFMT) == S_IFDIR)
69 
70  // See https://msdn.microsoft.com/en-us/library/1w06ktdy.aspx
71  // XXX -- Should probably have Arch enum for these.
72  #define F_OK 0 // Test for existence.
73  #define X_OK 1 // Test for execute permission.
74  #define W_OK 2 // Test for write permission.
75  #define R_OK 4 // Test for read permission.
76 #endif
77 
78 #if defined(ARCH_OS_WINDOWS)
79  #define ARCH_GLOB_NOCHECK 1
80  #define ARCH_GLOB_MARK 2
81  #define ARCH_GLOB_NOSORT 4
82 #else
83  #define ARCH_GLOB_NOCHECK GLOB_NOCHECK
84  #define ARCH_GLOB_MARK GLOB_MARK
85  #define ARCH_GLOB_NOSORT GLOB_NOSORT
86 #endif
87 #define ARCH_GLOB_DEFAULT (ARCH_GLOB_NOCHECK | ARCH_GLOB_MARK)
88 
89 #ifndef ARCH_PATH_MAX
90  #ifdef PATH_MAX
91  #define ARCH_PATH_MAX PATH_MAX
92  #else
93  #ifdef MAXPATHLEN
94  #define ARCH_PATH_MAX MAXPATHLEN
95  #else
96  #ifdef _MAX_PATH
97  #define ARCH_PATH_MAX _MAX_PATH
98  #else
99  #define ARCH_PATH_MAX 1024
100  #endif
101  #endif
102  #endif
103 #endif
104 
105 #if defined(ARCH_OS_WINDOWS)
106  #define ARCH_PATH_SEP "\\"
107  #define ARCH_PATH_LIST_SEP ";"
108  #define ARCH_REL_PATH_IDENT ".\\"
109 #else
110  #define ARCH_PATH_SEP "/"
111  #define ARCH_PATH_LIST_SEP ":"
112  #define ARCH_REL_PATH_IDENT "./"
113 #endif
114 
115 #if defined(ARCH_OS_WINDOWS)
116 typedef struct __stat64 ArchStatType;
117 #else
118 typedef struct stat ArchStatType;
119 #endif
120 
121 /// \file fileSystem.h
122 /// Architecture dependent file system access
123 /// \ingroup group_arch_SystemFunctions
124 ///
125 
126 /// Opens a file.
127 ///
128 /// Opens the file that is specified by filename.
129 /// Returning true if the file was opened successfully; false otherwise.
130 ///
131 ARCH_API FILE*
132 ArchOpenFile(char const* fileName, char const* mode);
133 
134 #if defined(ARCH_OS_WINDOWS)
135 # define ArchChmod(path, mode) _chmod(path, mode)
136 #else
137 # define ArchChmod(path, mode) chmod(path, mode)
138 #endif
139 
140 #if defined(ARCH_OS_WINDOWS)
141 # define ArchCloseFile(fd) _close(fd)
142 #else
143 # define ArchCloseFile(fd) close(fd)
144 #endif
145 
146 #if defined(ARCH_OS_WINDOWS)
147 # define ArchUnlinkFile(path) _unlink(path)
148 #else
149 # define ArchUnlinkFile(path) unlink(path)
150 #endif
151 
152 #if defined(ARCH_OS_WINDOWS)
153  ARCH_API int ArchFileAccess(const char* path, int mode);
154 #else
155 # define ArchFileAccess(path, mode) access(path, mode)
156 #endif
157 
158 #if defined(ARCH_OS_WINDOWS)
159 # define ArchFdOpen(fd, mode) _fdopen(fd, mode)
160 #else
161 # define ArchFdOpen(fd, mode) fdopen(fd, mode)
162 #endif
163 
164 #if defined(ARCH_OS_WINDOWS)
165 # define ArchFileNo(stream) _fileno(stream)
166 #else
167 # define ArchFileNo(stream) fileno(stream)
168 #endif
169 
170 #if defined(ARCH_OS_WINDOWS)
171 # define ArchFileIsaTTY(stream) _isatty(stream)
172 #else
173 # define ArchFileIsaTTY(stream) isatty(stream)
174 #endif
175 
176 #if defined(ARCH_OS_WINDOWS)
177  ARCH_API int ArchRmDir(const char* path);
178 #else
179 # define ArchRmDir(path) rmdir(path)
180 #endif
181 
182 /// Return the length of a file in bytes.
183 ///
184 /// Returns -1 if the file cannot be opened/read.
185 ARCH_API int64_t ArchGetFileLength(const char* fileName);
186 ARCH_API int64_t ArchGetFileLength(FILE *file);
187 
188 /// Return a filename for this file, if one can be obtained.
190 
191 /// Returns true if the data in \c stat struct \p st indicates that the target
192 /// file or directory is writable.
193 ///
194 /// This returns true if the struct pointer is valid, and the stat indicates
195 /// the target is writable by the effective user, effective group, or all
196 /// users.
198 
199 /// Returns the modification time (mtime) in seconds for a file.
200 ///
201 /// This function stores the modification time with as much precision as is
202 /// available in the stat structure for the current platform in \p time and
203 /// returns \c true on success, otherwise just returns \c false.
204 ARCH_API bool ArchGetModificationTime(const char* pathname, double* time);
205 
206 /// Returns the modification time (mtime) in seconds from the stat struct.
207 ///
208 /// This function returns the modification time with as much precision as is
209 /// available in the stat structure for the current platform.
211 
212 /// Normalizes the specified path, eliminating double slashes, etc.
213 ///
214 /// This canonicalizes paths, removing any double slashes, and eliminiating
215 /// '.', and '..' components of the path. This emulates the behavior of
216 /// os.path.normpath in Python.
217 ///
218 /// On Windows, all backslashes are converted to forward slashes and drive
219 /// specifiers (e.g., "C:") are lower-cased. If \p stripDriveSpecifier
220 /// is \c true, these drive specifiers are removed from the path.
222  bool stripDriveSpecifier = false);
223 
224 /// Returns the canonical absolute path of the specified filename.
225 ///
226 /// This makes the specified path absolute, by prepending the current working
227 /// directory. If the path is already absolute, it is returned unmodified.
229 
230 /// Returns the permissions mode (mode_t) for the given pathname.
231 ///
232 /// This function stats the given pathname and returns the permissions flags
233 /// for it and returns true. If the stat fails, returns false.
234 ///
235 ARCH_API bool ArchGetStatMode(const char *pathname, int *mode);
236 
237 /// Return the path to a temporary directory for this platform.
238 ///
239 /// The returned temporary directory will be a location that will normally
240 /// be cleaned out on a reboot. This is /var/tmp on Linux machines (for
241 /// legacy reasons), but /tmp on Darwin machines (/var/tmp on Darwin is
242 /// specified as a location where files are kept between system reboots -
243 /// see "man hier"). The returned string will not have a trailing slash.
244 ///
245 /// This routine is threadsafe and will not perform any memory allocations.
246 ARCH_API const char *ArchGetTmpDir();
247 
248 /// Make a temporary file name, in a system-determined temporary directory.
249 ///
250 /// The result returned has the form TMPDIR/prefix.pid[.n]suffix where TMPDIR
251 /// is a system-determined temporary directory (typically /tmp or /usr/tmp),
252 /// pid is the process id of the process, and the optional .n records the
253 /// number of times this function has been called by a process (and is ommited
254 /// the first time this function is called).
255 ///
256 /// The call is threadsafe.
257 ///
258 /// \warning This call opens a security hole because of the race between
259 /// choosing the name and opening the file. This call should be avoided in
260 /// favor of \c ArchMakeTmpFile().
261 ARCH_API
263  const std::string& suffix = std::string());
264 
265 /// Create a temporary file, in a system-determined temporary directory.
266 ///
267 /// The result returned has the form TMPDIR/prefix.XXXXXX where TMPDIR is a
268 /// system-determined temporary directory (typically /tmp or /usr/tmp) and
269 /// XXXXXX is a unique suffix. Returns the file descriptor of the new file
270 /// and, if pathname isn't NULL, returns the full path to the file in
271 /// pathname. Returns -1 on failure and errno is set.
272 ///
273 /// The call is threadsafe.
274 ARCH_API
275 int ArchMakeTmpFile(const std::string& prefix, std::string* pathname = 0);
276 
277 /// Create a temporary file, in a given temporary directory.
278 ///
279 /// The result returned has the form TMPDIR/prefix.XXXXXX where TMPDIR is the
280 /// given temporary directory and XXXXXX is a unique suffix. Returns the file
281 /// descriptor of the new file and, if pathname isn't NULL, returns the full
282 /// path to the file in pathname. Returns -1 on failure and errno is set.
283 ///
284 /// The call is threadsafe.
285 ARCH_API
286 int ArchMakeTmpFile(const std::string& tmpdir,
287  const std::string& prefix, std::string* pathname = 0);
288 
289 /// Create a temporary sub-direcrory, in a given temporary directory.
290 ///
291 /// The result returned has the form TMPDIR/prefix.XXXXXX/ where TMPDIR is the
292 /// given temporary directory and XXXXXX is a unique suffix. Returns the the
293 /// full path to the subdir in pathname. Returns empty string on failure and
294 /// errno is set.
295 ///
296 /// The call is threadsafe.
297 ARCH_API
299  const std::string& prefix);
300 
301 // Helper 'deleter' for use with std::unique_ptr for file mappings.
303  Arch_Unmapper() : _length(~0) {}
304  explicit Arch_Unmapper(size_t length) : _length(length) {}
305  ARCH_API void operator()(char *mapStart) const;
306  ARCH_API void operator()(char const *mapStart) const;
307  size_t GetLength() const { return _length; }
308 private:
309  size_t _length;
310 };
311 
312 /// ArchConstFileMapping and ArchMutableFileMapping are std::unique_ptr<char
313 /// const *, ...> and std::unique_ptr<char *, ...> respectively. The functions
314 /// ArchMapFileReadOnly() and ArchMapFileReadWrite() return them and provide
315 /// access to memory-mapped file contents.
316 using ArchConstFileMapping = std::unique_ptr<char const, Arch_Unmapper>;
317 using ArchMutableFileMapping = std::unique_ptr<char, Arch_Unmapper>;
318 
319 /// Return the length of an ArchConstFileMapping.
320 inline size_t
322  return m.get_deleter().GetLength();
323 }
324 
325 /// Return the length of an ArchMutableFileMapping.
326 inline size_t
328  return m.get_deleter().GetLength();
329 }
330 
331 /// Privately map the passed \p file into memory and return a unique_ptr to the
332 /// read-only mapped contents. The contents may not be modified. If mapping
333 /// fails, return a null unique_ptr and if errMsg is not null fill it with
334 /// information about the failure.
335 ARCH_API
337 ArchMapFileReadOnly(FILE *file, std::string *errMsg=nullptr);
338 
339 /// \overload
340 ARCH_API
342 ArchMapFileReadOnly(std::string const& path, std::string *errMsg=nullptr);
343 
344 /// Privately map the passed \p file into memory and return a unique_ptr to the
345 /// copy-on-write mapped contents. If modified, the affected pages are
346 /// dissociated from the underlying file and become backed by the system's swap
347 /// or page-file storage. Edits are not carried through to the underlying file.
348 /// If mapping fails, return a null unique_ptr and if errMsg is not null fill it
349 /// with information about the failure.
350 ARCH_API
352 ArchMapFileReadWrite(FILE *file, std::string *errMsg=nullptr);
353 
354 /// \overload
355 ARCH_API
357 ArchMapFileReadWrite(std::string const& path, std::string *errMsg=nullptr);
358 
360  ArchMemAdviceNormal, // Treat range with default behavior.
361  ArchMemAdviceWillNeed, // OS may prefetch this range.
362  ArchMemAdviceDontNeed, // OS may free resources related to this range.
363  ArchMemAdviceRandomAccess, // Prefetching may not be beneficial.
364 };
365 
366 /// Advise the OS regarding how the application intends to access a range of
367 /// memory. See ArchMemAdvice. This is primarily useful for mapped file
368 /// regions. This call does not change program semantics. It is only an
369 /// optimization hint to the OS, and may be a no-op on some systems.
370 ARCH_API
371 void ArchMemAdvise(void const *addr, size_t len, ArchMemAdvice adv);
372 
373 /// Report whether or not the mapped virtual memory pages starting at \p addr
374 /// for \p len bytes are resident in RAM. Pages that are resident will not,
375 /// when accessed, cause a page fault while those that are not will. Return
376 /// true on success and false in case of an error. The \p addr argument must be
377 /// a multiple of ArchGetPageSize(). The \p len argument need not be a multiple
378 /// of the page size; it will be rounded up to the next page boundary. Fill
379 /// \p pageMap with 0s for pages not resident in memory and 1s for pages that
380 /// are. The \p pageMap argument must therefore point to at least (\p len +
381 /// ArchGetPageSize()-1)/ArchGetPageSize() bytes.
382 ///
383 /// Note that currently this function is only implemented on Linux and Darwin.
384 /// On Windows it currently always returns false.
385 ARCH_API
386 bool
388  void const *addr, size_t len, unsigned char *pageMap);
389 
390 /// Read up to \p count bytes from \p offset in \p file into \p buffer. The
391 /// file position indicator for \p file is not changed. Return the number of
392 /// bytes read, or zero if at end of file. Return -1 in case of an error, with
393 /// errno set appropriately.
394 ARCH_API
395 int64_t ArchPRead(FILE *file, void *buffer, size_t count, int64_t offset);
396 
397 /// Write up to \p count bytes from \p buffer to \p file at \p offset. The file
398 /// position indicator for \p file is not changed. Return the number of bytes
399 /// written, possibly zero if none written. Return -1 in case of an error, with
400 /// errno set appropriately.
401 ARCH_API
402 int64_t ArchPWrite(FILE *file, void const *bytes, size_t count, int64_t offset);
403 
404 /// Returns the value of the symbolic link at \p path. Returns the empty
405 /// string on error or if \p path does not refer to a symbolic link.
406 ARCH_API
407 std::string ArchReadLink(const char* path);
408 
410  ArchFileAdviceNormal, // Treat range with default behavior.
411  ArchFileAdviceWillNeed, // OS may prefetch this range.
412  ArchFileAdviceDontNeed, // OS may free resources related to this range.
413  ArchFileAdviceRandomAccess, // Prefetching may not be beneficial.
414 };
415 
416 /// Advise the OS regarding how the application intends to access a range of
417 /// bytes in a file. See ArchFileAdvice. This call does not change program
418 /// semantics. It is only an optimization hint to the OS, and may be a no-op on
419 /// some systems.
420 ARCH_API
421 void ArchFileAdvise(FILE *file, int64_t offset, size_t count,
422  ArchFileAdvice adv);
423 
424 ///@}
425 
427 
428 #endif // ARCH_FILESYSTEM_H
ArchFileAdvice
Definition: fileSystem.h:409
ARCH_API FILE * ArchOpenFile(char const *fileName, char const *mode)
GLenum mode
Definition: glew.h:2163
ARCH_API void ArchMemAdvise(void const *addr, size_t len, ArchMemAdvice adv)
GT_API const UT_StringHolder time
ARCH_API std::string ArchAbsPath(const std::string &path)
ARCH_API void ArchFileAdvise(FILE *file, int64_t offset, size_t count, ArchFileAdvice adv)
ARCH_API std::string ArchNormPath(const std::string &path, bool stripDriveSpecifier=false)
const GLdouble * m
Definition: glew.h:9124
ARCH_API ArchConstFileMapping ArchMapFileReadOnly(FILE *file, std::string *errMsg=nullptr)
std::unique_ptr< char const, Arch_Unmapper > ArchConstFileMapping
Definition: fileSystem.h:316
Arch_Unmapper(size_t length)
Definition: fileSystem.h:304
ARCH_API ArchMutableFileMapping ArchMapFileReadWrite(FILE *file, std::string *errMsg=nullptr)
ARCH_API const char * ArchGetTmpDir()
ARCH_API int ArchMakeTmpFile(const std::string &prefix, std::string *pathname=0)
std::unique_ptr< char, Arch_Unmapper > ArchMutableFileMapping
Definition: fileSystem.h:317
GLuint buffer
Definition: glew.h:1680
ARCH_API std::string ArchReadLink(const char *path)
GLuint GLsizei GLsizei * length
Definition: glew.h:1825
ARCH_API int64_t ArchGetFileLength(const char *fileName)
size_t ArchGetFileMappingLength(ArchConstFileMapping const &m)
Return the length of an ArchConstFileMapping.
Definition: fileSystem.h:321
ARCH_API bool ArchGetStatMode(const char *pathname, int *mode)
GLenum void * addr
Definition: glew.h:11505
GLsizei const GLchar *const * path
Definition: glew.h:6461
ARCH_API bool ArchStatIsWritable(const ArchStatType *st)
struct stat ArchStatType
Definition: fileSystem.h:118
GLsizei const GLchar *const * string
Definition: glew.h:1844
ARCH_API bool ArchQueryMappedMemoryResidency(void const *addr, size_t len, unsigned char *pageMap)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1245
#define ArchRmDir(path)
Definition: fileSystem.h:179
GLuint GLuint GLsizei count
Definition: glew.h:1253
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:83
ARCH_API std::string ArchGetFileName(FILE *file)
Return a filename for this file, if one can be obtained.
#define ARCH_API
Definition: api.h:40
#define ArchFileAccess(path, mode)
Definition: fileSystem.h:155
ARCH_API int64_t ArchPRead(FILE *file, void *buffer, size_t count, int64_t offset)
ARCH_API void operator()(char *mapStart) const
size_t GetLength() const
Definition: fileSystem.h:307
ArchMemAdvice
Definition: fileSystem.h:359
ARCH_API std::string ArchMakeTmpSubdir(const std::string &tmpdir, const std::string &prefix)
ARCH_API int64_t ArchPWrite(FILE *file, void const *bytes, size_t count, int64_t offset)
GLenum GLsizei len
Definition: glew.h:7752
ARCH_API bool ArchGetModificationTime(const char *pathname, double *time)
GLintptr offset
Definition: glew.h:1682
ARCH_API std::string ArchMakeTmpFileName(const std::string &prefix, const std::string &suffix=std::string())