HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_FileUtil.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT_FileUtil.h ( UT Library, C++)
7  *
8  * COMMENTS: This verb class provides a wide assortment of
9  * file utility functions.
10  */
11 
12 #ifndef __UT_FileUtil__
13 #define __UT_FileUtil__
14 
15 #include "UT_API.h"
16 #include "UT_Assert.h"
17 #include "UT_NTUtil.h" // for mode_t
18 #include <SYS/SYS_Compiler.h>
19 #include <SYS/SYS_Types.h>
20 #include <SYS/SYS_Stdio.h>
21 
22 #include <iosfwd>
23 #include <stdio.h>
24 #include <time.h>
25 
26 class UT_String;
27 class UT_WorkBuffer;
28 
29 // Here are flags used the by the file utility functions:
30 // If this is set, the showPrompt will be called before any destructive
31 // action.
32 #define UT_FILEUTIL_PROMPT 1
33 // If this is set, the original directory will be included in the
34 // sweep.
35 #define UT_FILEUTIL_INCLUSIVE 2
36 
37 // The standard return code is 0 for success, negative for failure.
38 // An appropriate error is passed to the error method which can
39 // be overridden to do something more interesting than dumping to
40 // the console.
42 {
43 public:
44  enum UT_RemoveDepth { IF_EMPTY, ALL_CONTENTS };
45 
46 
48  virtual ~UT_FileUtil() {}
49 
50  UT_FileUtil(const UT_FileUtil &) = delete;
51  UT_FileUtil &operator=(const UT_FileUtil &) = delete;
52 
53  /// Returns the file size of that file in the given path. Returns -1 on
54  /// error.
55  static int64 getFileSize(const char *path);
56 
57  /// Returns the file modification time of the file in the given path.
58  /// Returns -1 on error.
59  static time_t getFileModTime(const char *path);
60 
61  /// Returns the latest file modification time recusively of all files
62  /// in the given path including the path itself. If the given path
63  /// can be a regular file.
64  /// Returns -1 if no timestamps can be retrieved.
65  static time_t getRecursiveDirMaxModTime(const char *path);
66 
67  /// Return the maximum number of file descriptors that are available
68  /// for this process.
69  static int getMaxFileDescriptors();
70 
71  /// Shorten the given path if possible. Only possibly has an effect on
72  /// Windows. Returns true if successful. Upon returning false, the contents
73  /// of result will be undefined.
74  static bool getShortPathName(UT_WorkBuffer &result,
75  const char *path);
76 
77  /// Follow the specified symbolic link to the contents, recursing if the
78  /// contents are themselves another symbolic link. This method will fail
79  /// if the specified path is not to a symbolic link, or if the link does
80  /// not point to an existing file when allow_dangling_link is false.
81  static int resolveSymbolicLinks(const char *path,
82  UT_WorkBuffer &contents,
83  bool allow_dangling_link = false);
84 
85  // Copies a file on disk from the source to the dest.
86  // This is only good for smallish files as we allocate a file size
87  // memory buffer.
88  static int copyFile(const char *srcname, const char *dstname,
89  std::ostream *error_os = nullptr);
90  // Recursively copy a directory
91  static int copyDir(const char *srcname, const char *dstname);
92  // Copies a file from a disk into a stream. This is good for
93  // building a .cpio archive.
94  static int copyFileToStream(const char *srcname, std::ostream &os);
95 
96  // Move a file, returns 0 on success.
97  static int moveFile(const char *srcname, const char *dstname);
98  // Delete a file
99  static int removeFile(const char *fname);
100 
101  // Delete a directory
102  static int removeDir(const char *dname,
103  UT_RemoveDepth depth = IF_EMPTY);
104 
105  /// Make a single directory. All leading path components must exist.
106  /// The function returns true if the path already exists or if the path was
107  /// made.
108  /// @param path @n The path to create
109  /// @param mode @n The unix file mode
110  /// @param ignore_umask @n
111  /// By default, the users umask will be used in conjunction with the
112  /// mode. This parameter will @b force the mode to be the given value.
113  static bool makeDir(const char *path, mode_t mode=0777,
114  bool ignore_umask = false);
115 
116  /// Make a directory and all the parent directories needed
117  /// @param path @n The path to create
118  /// @param mode @n The unix file mode
119  /// @param ignore_umask @n
120  /// By default, the users umask will be used in conjunction with the
121  /// mode. This parameter will @b force the mode to be the given value.
122  static bool makeDirs(const char *path, mode_t mode=0777,
123  bool ignore_umask = false);
124 
125  /// Locks a file for exclusive access. Will not return until the file lock
126  /// is achiveved or an error occurs. Equivalent to calling writeLockFile().
127  /// @returns true if the file lock succeeded, and false otherwise.
128  /// @note
129  /// - On Linux, if any file descriptor referring to this file is
130  /// closed, the lock will be automatically be closed. Be very careful!
131  /// - On Windows, this is NOT re-entrant (unlike Linux). Treat these locks
132  /// as NOT re-entrant unless you want deadlocking on Windows.
133  static bool lockFile(int fd);
134 
135  /// Unlocks a file that was locked for exclusive access with lockFile,
136  /// above.
137  /// Returns true if the unlock succeeded, and false otherwise.
138  static bool unlockFile(int fd);
139 
140  /// Locks a file for write access. Will not return until the file lock
141  /// is achiveved or an error occurs.
142  /// @returns true if the file lock succeeded, and false otherwise.
143  /// @note
144  /// - On Linux, if any file descriptor referring to this file is
145  /// closed, the lock will be automatically be closed. Be very careful!
146  /// - On Windows, this is NOT re-entrant (unlike Linux). Treat these locks
147  /// as NOT re-entrant unless you want deadlocking on Windows.
148  static bool writeLockFile(int fd);
149 
150  /// Locks a file for read access. Will not return until the file lock
151  /// is achiveved or an error occurs.
152  /// @returns true if the file lock succeeded, and false otherwise.
153  /// @note
154  /// - On Linux, if any file descriptor referring to this file is closed,
155  /// the lock will be automatically be closed. Be very careful!
156  /// - On Windows, this is NOT re-entrant (unlike Linux). Treat these locks
157  /// as NOT re-entrant unless you want deadlocking on Windows.
158  static bool readLockFile(int fd);
159 
160  // This navigates up the given path the specified number of levels.
161  // It adds a \0 at the correct slash, leaving path to be the
162  // proper path name.
163  // eg: upDirectory("foo/bar.vex", 1) = "foo"
164  // upDriectory("foo/bar/", 1) = "foo"
165  static void upDirectory(char *path, int levels);
166 
167  // This scans the (ascii) file fname for any line which starts
168  // with the prefix. If readonly is not true, it writes out a new
169  // version of the file lacking those lines. The return is the
170  // number of lines that would be removed, or negative if error.
171  static int removeLinesFromFile(const char *fname,
172  const char *prefix, int readonly = 0);
173 
174  // This is of the form
175  // removeOverrideFiles("d:/hsite/houdini5",
176  // "subnet/Sop",
177  // "foo.ds", "Dialog Script", UT_FILEUTIL_PROMPT);
178  // If the stripinfo is specified, it will do a removeLinesFromFile
179  // with stripinfo rather than delete.
180  int removeOverrideFiles(const char *newbasepath,
181  const char *relpath, const char *fname,
182  const char *english, int flags,
183  const char *stripinfo = 0);
184 
185  /// Parses the file in search of the given XML element and outputs
186  /// its contents into the string argument. Returns true uppon success
187  /// or false on failure.
188  static bool readXMLElementFromFile( const char * xml_file_path,
189  const char * element_name,
190  UT_String & element_data );
191 
192  // These are UI methods you can override to gain different behaviours
193  // for your instance:
194  // Severity is the same as UI_Manager::UI_ErrorType.
195  virtual void showError(const char *error, int severity = 2);
196  // 0 means Cancel, 1 OK.
197  virtual int showPrompt(const char *prompt);
198 
199 };
200 
202 
203 /// A class that allows you to create and lock a file for exclusive access.
204 /// When instances of this class go out of scope, the locked file is
205 /// automatically unlocked and closed.
207 {
208 public:
209  /// Construct without lock. Use lock() with filename to acquire one.
211  {
212  }
213 
214  /// Open and lock a file for exclusive reading and writing.
216  {
217  lock(filename, /*exclusive*/true);
218  }
219 
220  /// Open and lock a file for read-only (exclusive=false),
221  /// or for read-write (exclusive=true). If filename does not exist, then
222  /// it is opened as read-write.
223  UT_AutoFileLock(const char *filename, bool exclusive)
224  {
225  lock(filename, exclusive);
226  }
227 
229  {
230  unlock();
231  }
232 
233  /// Open and lock a file for read-only (exclusive=false),
234  /// or for read-write (exclusive=true). If filename does not exist, then
235  /// it is opened as read-write.
236  void lock(const char *filename, bool exclusive)
237  {
238  if (myFile)
239  {
240  UT_ASSERT(!"Can't relock");
241  return;
242  }
243 
244  // Try opening it as if it exists first, then try creating it.
245  myFile = SYSfopen(filename, exclusive ? "rb+" : "rb");
246  if (myFile)
247  {
248  if (exclusive)
249  myLockSucceeded = UT_FileUtil::writeLockFile(fileno(myFile));
250  else
251  myLockSucceeded = UT_FileUtil::readLockFile(fileno(myFile));
252  }
253  else
254  {
255  myFile = SYSfopen(filename, "wb+");
256  if (myFile)
257  myLockSucceeded = UT_FileUtil::writeLockFile(fileno(myFile));
258  else
259  myLockSucceeded = false;
260  }
261  }
262 
263  void unlock()
264  {
265  if (myFile)
266  {
267  if (myLockSucceeded)
268  {
269  UT_FileUtil::unlockFile(fileno(myFile));
270  myLockSucceeded = false;
271  }
272 
273  fclose(myFile);
274  myFile = nullptr;
275  }
276  }
277 
278  /// Get the file pointer for this locked file.
279  FILE *getFile() const
280  {
281  return myFile;
282  }
283 
284  /// Return whether the file is actually locked.
285  bool isLocked() const
286  {
287  return myLockSucceeded;
288  }
289 
290 private:
291  FILE *myFile = nullptr;
292  bool myLockSucceeded = false;
293 };
294 
295 #endif
296 
static bool unlockFile(int fd)
GLbitfield flags
Definition: glcorearb.h:1596
GT_API const UT_StringHolder filename
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
#define UT_API
Definition: UT_API.h:14
void lock(const char *filename, bool exclusive)
Definition: UT_FileUtil.h:236
**But if you need a result
Definition: thread.h:613
bool isLocked() const
Return whether the file is actually locked.
Definition: UT_FileUtil.h:285
< returns > If no error
Definition: snippets.dox:2
UT_AutoFileLock(UT_EmptyFileLock)
Construct without lock. Use lock() with filename to acquire one.
Definition: UT_FileUtil.h:210
long long int64
Definition: SYS_Types.h:116
#define SYS_NO_DISCARD_RESULT
Definition: SYS_Compiler.h:93
GLenum GLenum severity
Definition: glcorearb.h:2539
GLsizei levels
Definition: glcorearb.h:2224
FILE * getFile() const
Get the file pointer for this locked file.
Definition: UT_FileUtil.h:279
GLenum mode
Definition: glcorearb.h:99
GLint GLint GLsizei GLsizei GLsizei depth
Definition: glcorearb.h:476
static bool writeLockFile(int fd)
LeafData & operator=(const LeafData &)=delete
UT_AutoFileLock(const char *filename)
Open and lock a file for exclusive reading and writing.
Definition: UT_FileUtil.h:215
static bool readLockFile(int fd)
#define UT_ASSERT(ZZ)
Definition: UT_Assert.h:156
UT_AutoFileLock(const char *filename, bool exclusive)
Definition: UT_FileUtil.h:223
GLuint64 GLenum GLint fd
Definition: RE_OGL.h:262
virtual ~UT_FileUtil()
Definition: UT_FileUtil.h:48