HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
fileUtils.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_TF_FILE_UTILS_H
25 #define PXR_BASE_TF_FILE_UTILS_H
26 
27 /// \file tf/fileUtils.h
28 /// \ingroup group_tf_File
29 /// Definitions of basic file utilities in tf.
30 
31 #include "pxr/pxr.h"
32 #include "pxr/base/tf/api.h"
33 
34 #include <string>
35 #include <vector>
36 #include <functional>
37 
39 
40 /// Returns true if the path exists.
41 ///
42 /// If \p resolveSymlinks is false (default), the path is checked using
43 /// lstat(). if \p resolveSymlinks is true, the path is checked using stat(),
44 /// which resolves all symbolic links in the path.
45 TF_API
46 bool TfPathExists(std::string const& path, bool resolveSymlinks = false);
47 
48 /// Returns true if the path exists and is a directory.
49 ///
50 /// If \p resolveSymlinks is false (default), the path is checked using
51 /// lstat(). if \p resolveSymlinks is true, the path is checked using stat(),
52 /// which resolves all symbolic links in the path.
53 TF_API
54 bool TfIsDir(std::string const& path, bool resolveSymlinks = false);
55 
56 /// Returns true if the path exists and is a file.
57 ///
58 /// If \p resolveSymlinks is false (default), the path is checked using
59 /// lstat(). if \p resolveSymlinks is true, the path is checked using stat(),
60 /// which resolves all symbolic links in the path.
61 TF_API
62 bool TfIsFile(std::string const& path, bool resolveSymlinks = false);
63 
64 /// Returns true if the path exists and is a symbolic link.
65 TF_API
66 bool TfIsLink(std::string const& path);
67 
68 /// Returns true if the file or directory at \p path is writable.
69 ///
70 /// For this function to return true, the file must exist and be writable by
71 /// the effective user, effective group, or all users. This function
72 /// dereferences symbolic links, returning whether or not the resolved file or
73 /// directory path is writable. If the file or directory does not exist, this
74 /// function returns false.
75 TF_API
76 bool TfIsWritable(std::string const& path);
77 
78 /// Returns true if the path is an empty directory.
79 TF_API
80 bool TfIsDirEmpty(std::string const& path);
81 
82 /// Creates a symbolic link from \p src to \p dst.
83 TF_API
84 bool TfSymlink(std::string const& src, std::string const& dst);
85 
86 /// Deletes a file at path.
87 TF_API
88 bool TfDeleteFile(std::string const& path);
89 
90 /// Creates a directory.
91 ///
92 /// If the directory cannot be created, this function returns false. If no
93 /// mode is specified, the default mode is 0777. If the specified path already
94 /// exists, or an error occurs while creating the directory, this method
95 /// returns false.
96 TF_API
97 bool TfMakeDir(std::string const& path, int mode=-1);
98 
99 /// Creates a directory hierarchy.
100 ///
101 /// If any element of the path cannot be created, this function will return
102 /// false. The specified mode will be used to create all new directories. If
103 /// no mode is specified, the default mode of \c TfMakeDir is used. If the
104 /// target directory exists, this function returns false if \p existOk is
105 /// false.
106 TF_API
107 bool TfMakeDirs(std::string const& path, int mode=-1, bool existOk=false);
108 
109 /// Function type for TfWalkDirs.
110 ///
111 /// This function is called once for each directory visited by TfWalkDirs.
112 /// The first parameter is the directory path; if the topmost directory passed
113 /// to TfWalkDirs is relative, this path will also be relative. The second
114 /// parameter is a vector of subdirectory names, relative to the directory
115 /// path. This parameter is a pointer, allowing the subdirectory list to be
116 /// modified, thus controlling which directories are visited. Note that
117 /// modifying the subdirectory vector has no effect when TfWalkDirs is called
118 /// with \c topDown set to \c false. The final parameter is a vector of file
119 /// names found in the directory path. The returned value determines whether
120 /// the walk should be terminated (\c false), or continue (\c true).
121 typedef std::function<bool (std::string const&,
122  std::vector<std::string> *,
123  std::vector<std::string> const&)> TfWalkFunction;
124 
125 /// TfRmTree error handler function.
126 ///
127 /// The first parameter is the path which caused the error (file or directory),
128 /// and the second parameter is an error message indicating why the error
129 /// occurred.
130 typedef std::function<void (std::string const&,
132 
133 /// error handler to use when you want to ignore errors
134 ///
135 /// When calling TfWalkDirs/ChmodTree/RmTree and you want to ignore errors,
136 /// you can pass in this public error handler which will ignore all the
137 /// errors.
138 TF_API
139 void TfWalkIgnoreErrorHandler(std::string const& path, std::string const& msg);
140 
141 /// Directory tree walker.
142 ///
143 /// This function attempts to be as compatible as possible with Python's
144 /// os.walk() function.
145 ///
146 /// For each directory in the tree rooted at \p top (including \p top itself,
147 /// but excluding '.' and '..'), the std::function \p fn is called with
148 /// three arguments: \c dirpath, \c dirnames, and \c filenames.
149 ///
150 /// \c dirpath is a string, the path to the directory. \c dirnames is a list
151 /// of the names of the subdirectories in \c dirpath (excluding '.' and '..').
152 /// \c filenames is a list of the names of the non-directory files in
153 /// \c dirpath. Note that the names in the sets are just names, with no path
154 /// components. To get a full path (which begins with \p top) to a file or
155 /// directory in \c dirpath, use \c TfStringCatPaths(dirpath, name).
156 ///
157 /// If optional argument \p topDown is true, or not specified, \p fn is called
158 /// for a directory before any subdirectories. If topdown is false, \p fn is
159 /// called for a directory after all subdirectories. Additionally, when
160 /// \p topDown is true, the walk function can modify the \c dirnames set in
161 /// place. This can be used to prune the search, or to impose a specific
162 /// visitation order. Modifying \c dirnames when \p topDown is false has no
163 /// effect, since the directories in \c dirnames have already been visited
164 /// by the time they are passed to \p fn.
165 ///
166 /// The value returned by the error handler function \p onError determines what
167 /// further action will be taken if an error is encountered. If \c true is
168 /// returned, the walk will continue; if \c false, the walk will not continue.
169 ///
170 /// If \p followLinks is false, symbolic links to directories encountered
171 /// during the walk are passed to the walk function in the \c filenames vector.
172 /// If \p followLinks is true, symbolic links to directories are passed to the
173 /// walk function in the \p dirnames vector, and the walk will recurse into
174 /// these directories.
175 ///
176 /// If \p top is a symbolic link to a directory, it is followed regardless of
177 /// the value of \p followLinks. Calling TfWalkDirs with a file argument
178 /// returns immediately without calling \p fn.
179 TF_API
180 void TfWalkDirs(std::string const& top,
181  TfWalkFunction fn,
182  bool topDown=true,
183  TfWalkErrorHandler onError = 0,
184  bool followLinks = false);
185 
186 /// Recursively delete a directory tree rooted at \p path.
187 ///
188 /// Tf runtime errors are raised if any errors are encountered while deleting
189 /// the specified \p path. Pass in TfWalkIgnoreErrorHandler() to ignore errors.
190 /// Alternately, sending in a custom TfWalkErrorHandler will
191 /// call this handler when errors occur. This handler receives the path which
192 /// caused the error, and a message indicating why the error occurred.
193 TF_API
194 void TfRmTree(std::string const& path,
195  TfWalkErrorHandler onError = 0);
196 
197 /// Return a list containing files and directories in \p path.
198 ///
199 /// A trailing path separator character is appended to directories returned
200 /// in the listing. If \p recursive is true, the directory listing will
201 /// include all subdirectory structure of \p path.
202 TF_API
203 std::vector<std::string> TfListDir(std::string const& path,
204  bool recursive = false);
205 
206 /// Read the contents of \p dirPath and append the names of the contained
207 /// directories, files, and symlinks to \p dirnames, \p filenames, and
208 /// \p symlinknames, respectively.
209 ///
210 /// Return true if \p dirPath 's contents were read successfully. Otherwise
211 /// return false and set \p errMsg with a description of the error if \p errMsg
212 /// is not NULL.
213 ///
214 /// It is safe to pass NULL for any of \p dirnames, \p filenames, and
215 /// \p symlinknames. In that case those elements are not reported
216 TF_API
217 bool
218 TfReadDir(std::string const &dirPath,
219  std::vector<std::string> *dirnames,
220  std::vector<std::string> *filenames,
221  std::vector<std::string> *symlinknames,
222  std::string *errMsg = NULL);
223 
224 /// Touch \p fileName, updating access and modification time to 'now'.
225 ///
226 /// A simple touch-like functionality. Simple in a sense that it does not
227 /// offer as many options as the same-name unix touch command, but otherwise
228 /// is identical to the default touch behavior. If \p create is true, an empty
229 /// file gets created, otherwise the touch call fails if the file does not
230 /// already exist.
231 TF_API
232 bool TfTouchFile(std::string const &fileName, bool create=true);
233 
235 
236 #endif // PXR_BASE_TF_FILE_UTILS_H
TF_API bool TfIsFile(std::string const &path, bool resolveSymlinks=false)
GLenum src
Definition: glew.h:2410
TF_API bool TfReadDir(std::string const &dirPath, std::vector< std::string > *dirnames, std::vector< std::string > *filenames, std::vector< std::string > *symlinknames, std::string *errMsg=NULL)
TF_API bool TfMakeDir(std::string const &path, int mode=-1)
#define TF_API
Definition: api.h:40
GLenum mode
Definition: glew.h:2163
std::function< bool(std::string const &, std::vector< std::string > *, std::vector< std::string > const &)> TfWalkFunction
Definition: fileUtils.h:123
PXR_NAMESPACE_OPEN_SCOPE TF_API bool TfPathExists(std::string const &path, bool resolveSymlinks=false)
TF_API bool TfSymlink(std::string const &src, std::string const &dst)
Creates a symbolic link from src to dst.
std::function< void(std::string const &, std::string const &)> TfWalkErrorHandler
Definition: fileUtils.h:131
GLfloat GLfloat GLfloat top
Definition: glew.h:15186
void
Definition: png.h:1083
GLenum GLenum dst
Definition: glew.h:2410
TF_API bool TfIsLink(std::string const &path)
Returns true if the path exists and is a symbolic link.
TF_API void TfWalkDirs(std::string const &top, TfWalkFunction fn, bool topDown=true, TfWalkErrorHandler onError=0, bool followLinks=false)
TF_API bool TfDeleteFile(std::string const &path)
Deletes a file at path.
GLsizei const GLchar *const * path
Definition: glew.h:6461
GLsizei const GLchar *const * string
Definition: glew.h:1844
TF_API bool TfIsDirEmpty(std::string const &path)
Returns true if the path is an empty directory.
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1346
TF_API bool TfMakeDirs(std::string const &path, int mode=-1, bool existOk=false)
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
TF_API bool TfIsWritable(std::string const &path)
TF_API bool TfIsDir(std::string const &path, bool resolveSymlinks=false)
TF_API void TfWalkIgnoreErrorHandler(std::string const &path, std::string const &msg)
TF_API std::vector< std::string > TfListDir(std::string const &path, bool recursive=false)
TF_API bool TfTouchFile(std::string const &fileName, bool create=true)
TF_API void TfRmTree(std::string const &path, TfWalkErrorHandler onError=0)