• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 //===- llvm/Support/PathV1.h - Path Operating System Concept ----*- C++ -*-===//
2 //
3 //                     The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 //
10 // This file declares the llvm::sys::Path class.
11 //
12 //===----------------------------------------------------------------------===//
13 
14 #ifndef LLVM_SYSTEM_PATH_H
15 #define LLVM_SYSTEM_PATH_H
16 
17 #include "llvm/ADT/StringRef.h"
18 #include "llvm/Support/Compiler.h"
19 #include "llvm/Support/TimeValue.h"
20 #include <set>
21 #include <string>
22 #include <vector>
23 
24 #define LLVM_PATH_DEPRECATED_MSG(replacement) \
25   "PathV1 has been deprecated and will be removed as soon as all LLVM and" \
26   " Clang clients have been moved over to PathV2. Please use `" #replacement \
27   "` from PathV2 instead."
28 
29 namespace llvm {
30 namespace sys {
31 
32   /// This structure provides basic file system information about a file. It
33   /// is patterned after the stat(2) Unix operating system call but made
34   /// platform independent and eliminates many of the unix-specific fields.
35   /// However, to support llvm-ar, the mode, user, and group fields are
36   /// retained. These pertain to unix security and may not have a meaningful
37   /// value on non-Unix platforms. However, the other fields should
38   /// always be applicable on all platforms.  The structure is filled in by
39   /// the PathWithStatus class.
40   /// @brief File status structure
41   class FileStatus {
42   public:
43     uint64_t    fileSize;   ///< Size of the file in bytes
44     TimeValue   modTime;    ///< Time of file's modification
45     uint32_t    mode;       ///< Mode of the file, if applicable
46     uint32_t    user;       ///< User ID of owner, if applicable
47     uint32_t    group;      ///< Group ID of owner, if applicable
48     uint64_t    uniqueID;   ///< A number to uniquely ID this file
49     bool        isDir  : 1; ///< True if this is a directory.
50     bool        isFile : 1; ///< True if this is a file.
51 
FileStatus()52     FileStatus() : fileSize(0), modTime(0,0), mode(0777), user(999),
53                    group(999), uniqueID(0), isDir(false), isFile(false) { }
54 
getTimestamp()55     TimeValue getTimestamp() const { return modTime; }
getSize()56     uint64_t getSize() const { return fileSize; }
getMode()57     uint32_t getMode() const { return mode; }
getUser()58     uint32_t getUser() const { return user; }
getGroup()59     uint32_t getGroup() const { return group; }
getUniqueID()60     uint64_t getUniqueID() const { return uniqueID; }
61   };
62 
63   /// This class provides an abstraction for the path to a file or directory
64   /// in the operating system's filesystem and provides various basic operations
65   /// on it.  Note that this class only represents the name of a path to a file
66   /// or directory which may or may not be valid for a given machine's file
67   /// system. The class is patterned after the java.io.File class with various
68   /// extensions and several omissions (not relevant to LLVM).  A Path object
69   /// ensures that the path it encapsulates is syntactically valid for the
70   /// operating system it is running on but does not ensure correctness for
71   /// any particular file system. That is, a syntactically valid path might
72   /// specify path components that do not exist in the file system and using
73   /// such a Path to act on the file system could produce errors. There is one
74   /// invalid Path value which is permitted: the empty path.  The class should
75   /// never allow a syntactically invalid non-empty path name to be assigned.
76   /// Empty paths are required in order to indicate an error result in some
77   /// situations. If the path is empty, the isValid operation will return
78   /// false. All operations will fail if isValid is false. Operations that
79   /// change the path will either return false if it would cause a syntactically
80   /// invalid path name (in which case the Path object is left unchanged) or
81   /// throw an std::string exception indicating the error. The methods are
82   /// grouped into four basic categories: Path Accessors (provide information
83   /// about the path without accessing disk), Disk Accessors (provide
84   /// information about the underlying file or directory), Path Mutators
85   /// (change the path information, not the disk), and Disk Mutators (change
86   /// the disk file/directory referenced by the path). The Disk Mutator methods
87   /// all have the word "disk" embedded in their method name to reinforce the
88   /// notion that the operation modifies the file system.
89   /// @since 1.4
90   /// @brief An abstraction for operating system paths.
91   class Path {
92     /// @name Constructors
93     /// @{
94     public:
95       /// Construct a path to the root directory of the file system. The root
96       /// directory is a top level directory above which there are no more
97       /// directories. For example, on UNIX, the root directory is /. On Windows
98       /// it is file:///. Other operating systems may have different notions of
99       /// what the root directory is or none at all. In that case, a consistent
100       /// default root directory will be used.
101       LLVM_ATTRIBUTE_DEPRECATED(static Path GetRootDirectory(),
102         LLVM_PATH_DEPRECATED_MSG(NOTHING));
103 
104       /// Construct a path to a unique temporary directory that is created in
105       /// a "standard" place for the operating system. The directory is
106       /// guaranteed to be created on exit from this function. If the directory
107       /// cannot be created, the function will throw an exception.
108       /// @returns an invalid path (empty) on error
109       /// @param ErrMsg Optional place for an error message if an error occurs
110       /// @brief Construct a path to an new, unique, existing temporary
111       /// directory.
112       static Path GetTemporaryDirectory(std::string* ErrMsg = 0);
113 
114       /// Construct a vector of sys::Path that contains the "standard" system
115       /// library paths suitable for linking into programs.
116       /// @brief Construct a path to the system library directory
117       static void GetSystemLibraryPaths(std::vector<sys::Path>& Paths);
118 
119       /// Construct a vector of sys::Path that contains the "standard" bitcode
120       /// library paths suitable for linking into an llvm program. This function
121       /// *must* return the value of LLVM_LIB_SEARCH_PATH as well as the value
122       /// of LLVM_LIBDIR. It also must provide the System library paths as
123       /// returned by GetSystemLibraryPaths.
124       /// @see GetSystemLibraryPaths
125       /// @brief Construct a list of directories in which bitcode could be
126       /// found.
127       static void GetBitcodeLibraryPaths(std::vector<sys::Path>& Paths);
128 
129       /// Find the path to a library using its short name. Use the system
130       /// dependent library paths to locate the library.
131       /// @brief Find a library.
132       static Path FindLibrary(std::string& short_name);
133 
134       /// Construct a path to the default LLVM configuration directory. The
135       /// implementation must ensure that this is a well-known (same on many
136       /// systems) directory in which llvm configuration files exist. For
137       /// example, on Unix, the /etc/llvm directory has been selected.
138       /// @brief Construct a path to the default LLVM configuration directory
139       static Path GetLLVMDefaultConfigDir();
140 
141       /// Construct a path to the LLVM installed configuration directory. The
142       /// implementation must ensure that this refers to the "etc" directory of
143       /// the LLVM installation. This is the location where configuration files
144       /// will be located for a particular installation of LLVM on a machine.
145       /// @brief Construct a path to the LLVM installed configuration directory
146       static Path GetLLVMConfigDir();
147 
148       /// Construct a path to the current user's home directory. The
149       /// implementation must use an operating system specific mechanism for
150       /// determining the user's home directory. For example, the environment
151       /// variable "HOME" could be used on Unix. If a given operating system
152       /// does not have the concept of a user's home directory, this static
153       /// constructor must provide the same result as GetRootDirectory.
154       /// @brief Construct a path to the current user's "home" directory
155       static Path GetUserHomeDirectory();
156 
157       /// Construct a path to the current directory for the current process.
158       /// @returns The current working directory.
159       /// @brief Returns the current working directory.
160       static Path GetCurrentDirectory();
161 
162       /// Return the suffix commonly used on file names that contain an
163       /// executable.
164       /// @returns The executable file suffix for the current platform.
165       /// @brief Return the executable file suffix.
166       static StringRef GetEXESuffix();
167 
168       /// Return the suffix commonly used on file names that contain a shared
169       /// object, shared archive, or dynamic link library. Such files are
170       /// linked at runtime into a process and their code images are shared
171       /// between processes.
172       /// @returns The dynamic link library suffix for the current platform.
173       /// @brief Return the dynamic link library suffix.
174       static StringRef GetDLLSuffix();
175 
176       /// GetMainExecutable - Return the path to the main executable, given the
177       /// value of argv[0] from program startup and the address of main itself.
178       /// In extremis, this function may fail and return an empty path.
179       static Path GetMainExecutable(const char *argv0, void *MainAddr);
180 
181       /// This is one of the very few ways in which a path can be constructed
182       /// with a syntactically invalid name. The only *legal* invalid name is an
183       /// empty one. Other invalid names are not permitted. Empty paths are
184       /// provided so that they can be used to indicate null or error results in
185       /// other lib/System functionality.
186       /// @brief Construct an empty (and invalid) path.
Path()187       Path() : path() {}
Path(const Path & that)188       Path(const Path &that) : path(that.path) {}
189 
190       /// This constructor will accept a char* or std::string as a path. No
191       /// checking is done on this path to determine if it is valid. To
192       /// determine validity of the path, use the isValid method.
193       /// @param p The path to assign.
194       /// @brief Construct a Path from a string.
195       explicit Path(StringRef p);
196 
197       /// This constructor will accept a character range as a path.  No checking
198       /// is done on this path to determine if it is valid.  To determine
199       /// validity of the path, use the isValid method.
200       /// @param StrStart A pointer to the first character of the path name
201       /// @param StrLen The length of the path name at StrStart
202       /// @brief Construct a Path from a string.
203       Path(const char *StrStart, unsigned StrLen);
204 
205     /// @}
206     /// @name Operators
207     /// @{
208     public:
209       /// Makes a copy of \p that to \p this.
210       /// @returns \p this
211       /// @brief Assignment Operator
212       Path &operator=(const Path &that) {
213         path = that.path;
214         return *this;
215       }
216 
217       /// Makes a copy of \p that to \p this.
218       /// @param that A StringRef denoting the path
219       /// @returns \p this
220       /// @brief Assignment Operator
221       Path &operator=(StringRef that);
222 
223       /// Compares \p this Path with \p that Path for equality.
224       /// @returns true if \p this and \p that refer to the same thing.
225       /// @brief Equality Operator
226       bool operator==(const Path &that) const;
227 
228       /// Compares \p this Path with \p that Path for inequality.
229       /// @returns true if \p this and \p that refer to different things.
230       /// @brief Inequality Operator
231       bool operator!=(const Path &that) const { return !(*this == that); }
232 
233       /// Determines if \p this Path is less than \p that Path. This is required
234       /// so that Path objects can be placed into ordered collections (e.g.
235       /// std::map). The comparison is done lexicographically as defined by
236       /// the std::string::compare method.
237       /// @returns true if \p this path is lexicographically less than \p that.
238       /// @brief Less Than Operator
239       bool operator<(const Path& that) const;
240 
241     /// @}
242     /// @name Path Accessors
243     /// @{
244     public:
245       /// This function will use an operating system specific algorithm to
246       /// determine if the current value of \p this is a syntactically valid
247       /// path name for the operating system. The path name does not need to
248       /// exist, validity is simply syntactical. Empty paths are always invalid.
249       /// @returns true iff the path name is syntactically legal for the
250       /// host operating system.
251       /// @brief Determine if a path is syntactically valid or not.
252       bool isValid() const;
253 
254       /// This function determines if the contents of the path name are empty.
255       /// That is, the path name has a zero length. This does NOT determine if
256       /// if the file is empty. To get the length of the file itself, Use the
257       /// PathWithStatus::getFileStatus() method and then the getSize() method
258       /// on the returned FileStatus object.
259       /// @returns true iff the path is empty.
260       /// @brief Determines if the path name is empty (invalid).
isEmpty()261       bool isEmpty() const { return path.empty(); }
262 
263        /// This function returns the last component of the path name. The last
264       /// component is the file or directory name occurring after the last
265       /// directory separator. If no directory separator is present, the entire
266       /// path name is returned (i.e. same as toString).
267       /// @returns StringRef containing the last component of the path name.
268       /// @brief Returns the last component of the path name.
269       LLVM_ATTRIBUTE_DEPRECATED(
270         StringRef getLast() const,
271         LLVM_PATH_DEPRECATED_MSG(path::filename));
272 
273       /// This function strips off the path and suffix of the file or directory
274       /// name and returns just the basename. For example /a/foo.bar would cause
275       /// this function to return "foo".
276       /// @returns StringRef containing the basename of the path
277       /// @brief Get the base name of the path
278       LLVM_ATTRIBUTE_DEPRECATED(StringRef getBasename() const,
279         LLVM_PATH_DEPRECATED_MSG(path::stem));
280 
281       /// This function strips off the suffix of the path beginning with the
282       /// path separator ('/' on Unix, '\' on Windows) and returns the result.
283       LLVM_ATTRIBUTE_DEPRECATED(StringRef getDirname() const,
284         LLVM_PATH_DEPRECATED_MSG(path::parent_path));
285 
286       /// This function strips off the path and basename(up to and
287       /// including the last dot) of the file or directory name and
288       /// returns just the suffix. For example /a/foo.bar would cause
289       /// this function to return "bar".
290       /// @returns StringRef containing the suffix of the path
291       /// @brief Get the suffix of the path
292       LLVM_ATTRIBUTE_DEPRECATED(StringRef getSuffix() const,
293         LLVM_PATH_DEPRECATED_MSG(path::extension));
294 
295       /// Obtain a 'C' string for the path name.
296       /// @returns a 'C' string containing the path name.
297       /// @brief Returns the path as a C string.
c_str()298       const char *c_str() const { return path.c_str(); }
str()299       const std::string &str() const { return path; }
300 
301 
302       /// size - Return the length in bytes of this path name.
size()303       size_t size() const { return path.size(); }
304 
305       /// empty - Returns true if the path is empty.
empty()306       unsigned empty() const { return path.empty(); }
307 
308     /// @}
309     /// @name Disk Accessors
310     /// @{
311     public:
312       /// This function determines if the path name is absolute, as opposed to
313       /// relative.
314       /// @brief Determine if the path is absolute.
315       LLVM_ATTRIBUTE_DEPRECATED(
316         bool isAbsolute() const,
317         LLVM_PATH_DEPRECATED_MSG(path::is_absolute));
318 
319       /// This function determines if the path name is absolute, as opposed to
320       /// relative.
321       /// @brief Determine if the path is absolute.
322       LLVM_ATTRIBUTE_DEPRECATED(
323         static bool isAbsolute(const char *NameStart, unsigned NameLen),
324         LLVM_PATH_DEPRECATED_MSG(path::is_absolute));
325 
326       /// This function opens the file associated with the path name provided by
327       /// the Path object and reads its magic number. If the magic number at the
328       /// start of the file matches \p magic, true is returned. In all other
329       /// cases (file not found, file not accessible, etc.) it returns false.
330       /// @returns true if the magic number of the file matches \p magic.
331       /// @brief Determine if file has a specific magic number
332       LLVM_ATTRIBUTE_DEPRECATED(bool hasMagicNumber(StringRef magic) const,
333         LLVM_PATH_DEPRECATED_MSG(fs::has_magic));
334 
335       /// This function retrieves the first \p len bytes of the file associated
336       /// with \p this. These bytes are returned as the "magic number" in the
337       /// \p Magic parameter.
338       /// @returns true if the Path is a file and the magic number is retrieved,
339       /// false otherwise.
340       /// @brief Get the file's magic number.
341       bool getMagicNumber(std::string& Magic, unsigned len) const;
342 
343       /// This function determines if the path name in the object references an
344       /// archive file by looking at its magic number.
345       /// @returns true if the file starts with the magic number for an archive
346       /// file.
347       /// @brief Determine if the path references an archive file.
348       bool isArchive() const;
349 
350       /// This function determines if the path name in the object references an
351       /// LLVM Bitcode file by looking at its magic number.
352       /// @returns true if the file starts with the magic number for LLVM
353       /// bitcode files.
354       /// @brief Determine if the path references a bitcode file.
355       bool isBitcodeFile() const;
356 
357       /// This function determines if the path name in the object references a
358       /// native Dynamic Library (shared library, shared object) by looking at
359       /// the file's magic number. The Path object must reference a file, not a
360       /// directory.
361       /// @returns true if the file starts with the magic number for a native
362       /// shared library.
363       /// @brief Determine if the path references a dynamic library.
364       bool isDynamicLibrary() const;
365 
366       /// This function determines if the path name in the object references a
367       /// native object file by looking at it's magic number. The term object
368       /// file is defined as "an organized collection of separate, named
369       /// sequences of binary data." This covers the obvious file formats such
370       /// as COFF and ELF, but it also includes llvm ir bitcode, archives,
371       /// libraries, etc...
372       /// @returns true if the file starts with the magic number for an object
373       /// file.
374       /// @brief Determine if the path references an object file.
375       bool isObjectFile() const;
376 
377       /// This function determines if the path name references an existing file
378       /// or directory in the file system.
379       /// @returns true if the pathname references an existing file or
380       /// directory.
381       /// @brief Determines if the path is a file or directory in
382       /// the file system.
383       LLVM_ATTRIBUTE_DEPRECATED(bool exists() const,
384         LLVM_PATH_DEPRECATED_MSG(fs::exists));
385 
386       /// This function determines if the path name references an
387       /// existing directory.
388       /// @returns true if the pathname references an existing directory.
389       /// @brief Determines if the path is a directory in the file system.
390       LLVM_ATTRIBUTE_DEPRECATED(bool isDirectory() const,
391         LLVM_PATH_DEPRECATED_MSG(fs::is_directory));
392 
393       /// This function determines if the path name references an
394       /// existing symbolic link.
395       /// @returns true if the pathname references an existing symlink.
396       /// @brief Determines if the path is a symlink in the file system.
397       LLVM_ATTRIBUTE_DEPRECATED(bool isSymLink() const,
398         LLVM_PATH_DEPRECATED_MSG(fs::is_symlink));
399 
400       /// This function determines if the path name references a readable file
401       /// or directory in the file system. This function checks for
402       /// the existence and readability (by the current program) of the file
403       /// or directory.
404       /// @returns true if the pathname references a readable file.
405       /// @brief Determines if the path is a readable file or directory
406       /// in the file system.
407       bool canRead() const;
408 
409       /// This function determines if the path name references a writable file
410       /// or directory in the file system. This function checks for the
411       /// existence and writability (by the current program) of the file or
412       /// directory.
413       /// @returns true if the pathname references a writable file.
414       /// @brief Determines if the path is a writable file or directory
415       /// in the file system.
416       bool canWrite() const;
417 
418       /// This function checks that what we're trying to work only on a regular
419       /// file. Check for things like /dev/null, any block special file, or
420       /// other things that aren't "regular" regular files.
421       /// @returns true if the file is S_ISREG.
422       /// @brief Determines if the file is a regular file
423       bool isRegularFile() const;
424 
425       /// This function determines if the path name references an executable
426       /// file in the file system. This function checks for the existence and
427       /// executability (by the current program) of the file.
428       /// @returns true if the pathname references an executable file.
429       /// @brief Determines if the path is an executable file in the file
430       /// system.
431       bool canExecute() const;
432 
433       /// This function builds a list of paths that are the names of the
434       /// files and directories in a directory.
435       /// @returns true if an error occurs, true otherwise
436       /// @brief Build a list of directory's contents.
437       bool getDirectoryContents(
438         std::set<Path> &paths, ///< The resulting list of file & directory names
439         std::string* ErrMsg    ///< Optional place to return an error message.
440       ) const;
441 
442     /// @}
443     /// @name Path Mutators
444     /// @{
445     public:
446       /// The path name is cleared and becomes empty. This is an invalid
447       /// path name but is the *only* invalid path name. This is provided
448       /// so that path objects can be used to indicate the lack of a
449       /// valid path being found.
450       /// @brief Make the path empty.
clear()451       void clear() { path.clear(); }
452 
453       /// This method sets the Path object to \p unverified_path. This can fail
454       /// if the \p unverified_path does not pass the syntactic checks of the
455       /// isValid() method. If verification fails, the Path object remains
456       /// unchanged and false is returned. Otherwise true is returned and the
457       /// Path object takes on the path value of \p unverified_path
458       /// @returns true if the path was set, false otherwise.
459       /// @param unverified_path The path to be set in Path object.
460       /// @brief Set a full path from a StringRef
461       bool set(StringRef unverified_path);
462 
463       /// One path component is removed from the Path. If only one component is
464       /// present in the path, the Path object becomes empty. If the Path object
465       /// is empty, no change is made.
466       /// @returns false if the path component could not be removed.
467       /// @brief Removes the last directory component of the Path.
468       bool eraseComponent();
469 
470       /// The \p component is added to the end of the Path if it is a legal
471       /// name for the operating system. A directory separator will be added if
472       /// needed.
473       /// @returns false if the path component could not be added.
474       /// @brief Appends one path component to the Path.
475       bool appendComponent(StringRef component);
476 
477       /// A period and the \p suffix are appended to the end of the pathname.
478       /// When the \p suffix is empty, no action is performed.
479       /// @brief Adds a period and the \p suffix to the end of the pathname.
480       void appendSuffix(StringRef suffix);
481 
482       /// The suffix of the filename is erased. The suffix begins with and
483       /// includes the last . character in the filename after the last directory
484       /// separator and extends until the end of the name. If no . character is
485       /// after the last directory separator, then the file name is left
486       /// unchanged (i.e. it was already without a suffix) but the function
487       /// returns false.
488       /// @returns false if there was no suffix to remove, true otherwise.
489       /// @brief Remove the suffix from a path name.
490       bool eraseSuffix();
491 
492       /// The current Path name is made unique in the file system. Upon return,
493       /// the Path will have been changed to make a unique file in the file
494       /// system or it will not have been changed if the current path name is
495       /// already unique.
496       /// @throws std::string if an unrecoverable error occurs.
497       /// @brief Make the current path name unique in the file system.
498       bool makeUnique( bool reuse_current /*= true*/, std::string* ErrMsg );
499 
500       /// The current Path name is made absolute by prepending the
501       /// current working directory if necessary.
502       LLVM_ATTRIBUTE_DEPRECATED(
503         void makeAbsolute(),
504         LLVM_PATH_DEPRECATED_MSG(fs::make_absolute));
505 
506     /// @}
507     /// @name Disk Mutators
508     /// @{
509     public:
510       /// This method attempts to make the file referenced by the Path object
511       /// available for reading so that the canRead() method will return true.
512       /// @brief Make the file readable;
513       bool makeReadableOnDisk(std::string* ErrMsg = 0);
514 
515       /// This method attempts to make the file referenced by the Path object
516       /// available for writing so that the canWrite() method will return true.
517       /// @brief Make the file writable;
518       bool makeWriteableOnDisk(std::string* ErrMsg = 0);
519 
520       /// This method attempts to make the file referenced by the Path object
521       /// available for execution so that the canExecute() method will return
522       /// true.
523       /// @brief Make the file readable;
524       bool makeExecutableOnDisk(std::string* ErrMsg = 0);
525 
526       /// This method allows the last modified time stamp and permission bits
527       /// to be set on the disk object referenced by the Path.
528       /// @throws std::string if an error occurs.
529       /// @returns true on error.
530       /// @brief Set the status information.
531       bool setStatusInfoOnDisk(const FileStatus &SI,
532                                std::string *ErrStr = 0) const;
533 
534       /// This method attempts to create a directory in the file system with the
535       /// same name as the Path object. The \p create_parents parameter controls
536       /// whether intermediate directories are created or not. if \p
537       /// create_parents is true, then an attempt will be made to create all
538       /// intermediate directories, as needed. If \p create_parents is false,
539       /// then only the final directory component of the Path name will be
540       /// created. The created directory will have no entries.
541       /// @returns true if the directory could not be created, false otherwise
542       /// @brief Create the directory this Path refers to.
543       bool createDirectoryOnDisk(
544         bool create_parents = false, ///<  Determines whether non-existent
545            ///< directory components other than the last one (the "parents")
546            ///< are created or not.
547         std::string* ErrMsg = 0 ///< Optional place to put error messages.
548       );
549 
550       /// This method attempts to create a file in the file system with the same
551       /// name as the Path object. The intermediate directories must all exist
552       /// at the time this method is called. Use createDirectoriesOnDisk to
553       /// accomplish that. The created file will be empty upon return from this
554       /// function.
555       /// @returns true if the file could not be created, false otherwise.
556       /// @brief Create the file this Path refers to.
557       bool createFileOnDisk(
558         std::string* ErrMsg = 0 ///< Optional place to put error messages.
559       );
560 
561       /// This is like createFile except that it creates a temporary file. A
562       /// unique temporary file name is generated based on the contents of
563       /// \p this before the call. The new name is assigned to \p this and the
564       /// file is created.  Note that this will both change the Path object
565       /// *and* create the corresponding file. This function will ensure that
566       /// the newly generated temporary file name is unique in the file system.
567       /// @returns true if the file couldn't be created, false otherwise.
568       /// @brief Create a unique temporary file
569       bool createTemporaryFileOnDisk(
570         bool reuse_current = false, ///< When set to true, this parameter
571           ///< indicates that if the current file name does not exist then
572           ///< it will be used without modification.
573         std::string* ErrMsg = 0 ///< Optional place to put error messages
574       );
575 
576       /// This method renames the file referenced by \p this as \p newName. The
577       /// file referenced by \p this must exist. The file referenced by
578       /// \p newName does not need to exist.
579       /// @returns true on error, false otherwise
580       /// @brief Rename one file as another.
581       bool renamePathOnDisk(const Path& newName, std::string* ErrMsg);
582 
583       /// This method attempts to destroy the file or directory named by the
584       /// last component of the Path. If the Path refers to a directory and the
585       /// \p destroy_contents is false, an attempt will be made to remove just
586       /// the directory (the final Path component). If \p destroy_contents is
587       /// true, an attempt will be made to remove the entire contents of the
588       /// directory, recursively. If the Path refers to a file, the
589       /// \p destroy_contents parameter is ignored.
590       /// @param destroy_contents Indicates whether the contents of a destroyed
591       /// @param Err An optional string to receive an error message.
592       /// directory should also be destroyed (recursively).
593       /// @returns false if the file/directory was destroyed, true on error.
594       /// @brief Removes the file or directory from the filesystem.
595       bool eraseFromDisk(bool destroy_contents = false,
596                          std::string *Err = 0) const;
597 
598 
599       /// MapInFilePages - This is a low level system API to map in the file
600       /// that is currently opened as FD into the current processes' address
601       /// space for read only access.  This function may return null on failure
602       /// or if the system cannot provide the following constraints:
603       ///  1) The pages must be valid after the FD is closed, until
604       ///     UnMapFilePages is called.
605       ///  2) Any padding after the end of the file must be zero filled, if
606       ///     present.
607       ///  3) The pages must be contiguous.
608       ///
609       /// This API is not intended for general use, clients should use
610       /// MemoryBuffer::getFile instead.
611       static const char *MapInFilePages(int FD, size_t FileSize,
612                                         off_t Offset);
613 
614       /// UnMapFilePages - Free pages mapped into the current process by
615       /// MapInFilePages.
616       ///
617       /// This API is not intended for general use, clients should use
618       /// MemoryBuffer::getFile instead.
619       static void UnMapFilePages(const char *Base, size_t FileSize);
620 
621     /// @}
622     /// @name Data
623     /// @{
624     protected:
625       // Our win32 implementation relies on this string being mutable.
626       mutable std::string path;   ///< Storage for the path name.
627 
628 
629     /// @}
630   };
631 
632   /// This class is identical to Path class except it allows you to obtain the
633   /// file status of the Path as well. The reason for the distinction is one of
634   /// efficiency. First, the file status requires additional space and the space
635   /// is incorporated directly into PathWithStatus without an additional malloc.
636   /// Second, obtaining status information is an expensive operation on most
637   /// operating systems so we want to be careful and explicit about where we
638   /// allow this operation in LLVM.
639   /// @brief Path with file status class.
640   class PathWithStatus : public Path {
641     /// @name Constructors
642     /// @{
643     public:
644       /// @brief Default constructor
PathWithStatus()645       PathWithStatus() : Path(), status(), fsIsValid(false) {}
646 
647       /// @brief Copy constructor
PathWithStatus(const PathWithStatus & that)648       PathWithStatus(const PathWithStatus &that)
649         : Path(static_cast<const Path&>(that)), status(that.status),
650            fsIsValid(that.fsIsValid) {}
651 
652       /// This constructor allows construction from a Path object
653       /// @brief Path constructor
PathWithStatus(const Path & other)654       PathWithStatus(const Path &other)
655         : Path(other), status(), fsIsValid(false) {}
656 
657       /// This constructor will accept a char* or std::string as a path. No
658       /// checking is done on this path to determine if it is valid. To
659       /// determine validity of the path, use the isValid method.
660       /// @brief Construct a Path from a string.
PathWithStatus(StringRef p)661       explicit PathWithStatus(
662         StringRef p ///< The path to assign.
663       ) : Path(p), status(), fsIsValid(false) {}
664 
665       /// This constructor will accept a character range as a path.  No checking
666       /// is done on this path to determine if it is valid.  To determine
667       /// validity of the path, use the isValid method.
668       /// @brief Construct a Path from a string.
PathWithStatus(const char * StrStart,unsigned StrLen)669       explicit PathWithStatus(
670         const char *StrStart,  ///< Pointer to the first character of the path
671         unsigned StrLen        ///< Length of the path.
672       ) : Path(StrStart, StrLen), status(), fsIsValid(false) {}
673 
674       /// Makes a copy of \p that to \p this.
675       /// @returns \p this
676       /// @brief Assignment Operator
677       PathWithStatus &operator=(const PathWithStatus &that) {
678         static_cast<Path&>(*this) = static_cast<const Path&>(that);
679         status = that.status;
680         fsIsValid = that.fsIsValid;
681         return *this;
682       }
683 
684       /// Makes a copy of \p that to \p this.
685       /// @returns \p this
686       /// @brief Assignment Operator
687       PathWithStatus &operator=(const Path &that) {
688         static_cast<Path&>(*this) = static_cast<const Path&>(that);
689         fsIsValid = false;
690         return *this;
691       }
692 
693     /// @}
694     /// @name Methods
695     /// @{
696     public:
697       /// This function returns status information about the file. The type of
698       /// path (file or directory) is updated to reflect the actual contents
699       /// of the file system.
700       /// @returns 0 on failure, with Error explaining why (if non-zero)
701       /// @returns a pointer to a FileStatus structure on success.
702       /// @brief Get file status.
703       const FileStatus *getFileStatus(
704         bool forceUpdate = false, ///< Force an update from the file system
705         std::string *Error = 0    ///< Optional place to return an error msg.
706       ) const;
707 
708     /// @}
709     /// @name Data
710     /// @{
711     private:
712       mutable FileStatus status; ///< Status information.
713       mutable bool fsIsValid;    ///< Whether we've obtained it or not
714 
715     /// @}
716   };
717 
718   /// This enumeration delineates the kinds of files that LLVM knows about.
719   enum LLVMFileType {
720     Unknown_FileType = 0,              ///< Unrecognized file
721     Bitcode_FileType,                  ///< Bitcode file
722     Archive_FileType,                  ///< ar style archive file
723     ELF_Relocatable_FileType,          ///< ELF Relocatable object file
724     ELF_Executable_FileType,           ///< ELF Executable image
725     ELF_SharedObject_FileType,         ///< ELF dynamically linked shared lib
726     ELF_Core_FileType,                 ///< ELF core image
727     Mach_O_Object_FileType,            ///< Mach-O Object file
728     Mach_O_Executable_FileType,        ///< Mach-O Executable
729     Mach_O_FixedVirtualMemorySharedLib_FileType, ///< Mach-O Shared Lib, FVM
730     Mach_O_Core_FileType,              ///< Mach-O Core File
731     Mach_O_PreloadExecutable_FileType, ///< Mach-O Preloaded Executable
732     Mach_O_DynamicallyLinkedSharedLib_FileType, ///< Mach-O dynlinked shared lib
733     Mach_O_DynamicLinker_FileType,     ///< The Mach-O dynamic linker
734     Mach_O_Bundle_FileType,            ///< Mach-O Bundle file
735     Mach_O_DynamicallyLinkedSharedLibStub_FileType, ///< Mach-O Shared lib stub
736     Mach_O_DSYMCompanion_FileType,     ///< Mach-O dSYM companion file
737     COFF_FileType                      ///< COFF object file or lib
738   };
739 
740   /// This utility function allows any memory block to be examined in order
741   /// to determine its file type.
742   LLVMFileType IdentifyFileType(const char*magic, unsigned length);
743 
744   /// This function can be used to copy the file specified by Src to the
745   /// file specified by Dest. If an error occurs, Dest is removed.
746   /// @returns true if an error occurs, false otherwise
747   /// @brief Copy one file to another.
748   bool CopyFile(const Path& Dest, const Path& Src, std::string* ErrMsg);
749 
750   /// This is the OS-specific path separator: a colon on Unix or a semicolon
751   /// on Windows.
752   extern const char PathSeparator;
753 }
754 
755 }
756 
757 #endif
758