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
29namespace llvm {
30namespace 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
52    FileStatus() : fileSize(0), modTime(0,0), mode(0777), user(999),
53                   group(999), uniqueID(0), isDir(false), isFile(false) { }
54
55    TimeValue getTimestamp() const { return modTime; }
56    uint64_t getSize() const { return fileSize; }
57    uint32_t getMode() const { return mode; }
58    uint32_t getUser() const { return user; }
59    uint32_t getGroup() const { return group; }
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.
187      Path() : path() {}
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).
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.
298      const char *c_str() const { return path.c_str(); }
299      const std::string &str() const { return path; }
300
301
302      /// size - Return the length in bytes of this path name.
303      size_t size() const { return path.size(); }
304
305      /// empty - Returns true if the path is 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.
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
645      PathWithStatus() : Path(), status(), fsIsValid(false) {}
646
647      /// @brief Copy constructor
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
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.
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.
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