1 //===- VirtualFileSystem.h - Virtual File System Layer ----------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 /// \brief Defines the virtual file system interface vfs::FileSystem.
11 //===----------------------------------------------------------------------===//
13 #ifndef LLVM_CLANG_BASIC_VIRTUAL_FILE_SYSTEM_H
14 #define LLVM_CLANG_BASIC_VIRTUAL_FILE_SYSTEM_H
16 #include "clang/Basic/LLVM.h"
17 #include "llvm/ADT/IntrusiveRefCntPtr.h"
18 #include "llvm/ADT/Optional.h"
19 #include "llvm/Support/ErrorOr.h"
20 #include "llvm/Support/FileSystem.h"
21 #include "llvm/Support/raw_ostream.h"
22 #include "llvm/Support/SourceMgr.h"
31 /// \brief The result of a \p status operation.
34 llvm::sys::fs::UniqueID UID;
35 llvm::sys::TimeValue MTime;
39 llvm::sys::fs::file_type Type;
40 llvm::sys::fs::perms Perms;
43 bool IsVFSMapped; // FIXME: remove when files support multiple names
46 Status() : Type(llvm::sys::fs::file_type::status_error) {}
47 Status(const llvm::sys::fs::file_status &Status);
48 Status(StringRef Name, StringRef RealName, llvm::sys::fs::UniqueID UID,
49 llvm::sys::TimeValue MTime, uint32_t User, uint32_t Group,
50 uint64_t Size, llvm::sys::fs::file_type Type,
51 llvm::sys::fs::perms Perms);
53 /// \brief Returns the name that should be used for this file or directory.
54 StringRef getName() const { return Name; }
55 void setName(StringRef N) { Name = N; }
57 /// @name Status interface from llvm::sys::fs
59 llvm::sys::fs::file_type getType() const { return Type; }
60 llvm::sys::fs::perms getPermissions() const { return Perms; }
61 llvm::sys::TimeValue getLastModificationTime() const { return MTime; }
62 llvm::sys::fs::UniqueID getUniqueID() const { return UID; }
63 uint32_t getUser() const { return User; }
64 uint32_t getGroup() const { return Group; }
65 uint64_t getSize() const { return Size; }
66 void setType(llvm::sys::fs::file_type v) { Type = v; }
67 void setPermissions(llvm::sys::fs::perms p) { Perms = p; }
69 /// @name Status queries
70 /// These are static queries in llvm::sys::fs.
72 bool equivalent(const Status &Other) const;
73 bool isDirectory() const;
74 bool isRegularFile() const;
76 bool isSymlink() const;
77 bool isStatusKnown() const;
82 /// \brief Represents an open file.
85 /// \brief Destroy the file after closing it (if open).
86 /// Sub-classes should generally call close() inside their destructors. We
87 /// cannot do that from the base class, since close is virtual.
89 /// \brief Get the status of the file.
90 virtual llvm::ErrorOr<Status> status() = 0;
91 /// \brief Get the contents of the file as a \p MemoryBuffer.
92 virtual std::error_code getBuffer(const Twine &Name,
93 std::unique_ptr<llvm::MemoryBuffer> &Result,
94 int64_t FileSize = -1,
95 bool RequiresNullTerminator = true,
96 bool IsVolatile = false) = 0;
97 /// \brief Closes the file.
98 virtual std::error_code close() = 0;
99 /// \brief Sets the name to use for this file.
100 virtual void setName(StringRef Name) = 0;
104 /// \brief An interface for virtual file systems to provide an iterator over the
105 /// (non-recursive) contents of a directory.
107 virtual ~DirIterImpl();
108 /// \brief Sets \c CurrentEntry to the next entry in the directory on success,
109 /// or returns a system-defined \c error_code.
110 virtual std::error_code increment() = 0;
113 } // end namespace detail
115 /// \brief An input iterator over the entries in a virtual path, similar to
116 /// llvm::sys::fs::directory_iterator.
117 class directory_iterator {
118 std::shared_ptr<detail::DirIterImpl> Impl; // Input iterator semantics on copy
121 directory_iterator(std::shared_ptr<detail::DirIterImpl> I) : Impl(I) {
122 assert(Impl.get() != nullptr && "requires non-null implementation");
123 if (!Impl->CurrentEntry.isStatusKnown())
124 Impl.reset(); // Normalize the end iterator to Impl == nullptr.
127 /// \brief Construct an 'end' iterator.
128 directory_iterator() { }
130 /// \brief Equivalent to operator++, with an error code.
131 directory_iterator &increment(std::error_code &EC) {
132 assert(Impl && "attempting to increment past end");
133 EC = Impl->increment();
134 if (EC || !Impl->CurrentEntry.isStatusKnown())
135 Impl.reset(); // Normalize the end iterator to Impl == nullptr.
139 const Status &operator*() const { return Impl->CurrentEntry; }
140 const Status *operator->() const { return &Impl->CurrentEntry; }
142 bool operator==(const directory_iterator &RHS) const {
143 if (Impl && RHS.Impl)
144 return Impl->CurrentEntry.equivalent(RHS.Impl->CurrentEntry);
145 return !Impl && !RHS.Impl;
147 bool operator!=(const directory_iterator &RHS) const {
148 return !(*this == RHS);
151 /// For testing only. Directory iteration does not always succeed!
152 directory_iterator &operator++() {
156 llvm::report_fatal_error("directory iteration failed!");
161 /// \brief The virtual file system interface.
162 class FileSystem : public llvm::ThreadSafeRefCountedBase<FileSystem> {
164 virtual ~FileSystem();
166 /// \brief Get the status of the entry at \p Path, if one exists.
167 virtual llvm::ErrorOr<Status> status(const Twine &Path) = 0;
168 /// \brief Get a \p File object for the file at \p Path, if one exists.
169 virtual std::error_code openFileForRead(const Twine &Path,
170 std::unique_ptr<File> &Result) = 0;
172 /// This is a convenience method that opens a file, gets its content and then
174 std::error_code getBufferForFile(const Twine &Name,
175 std::unique_ptr<llvm::MemoryBuffer> &Result,
176 int64_t FileSize = -1,
177 bool RequiresNullTerminator = true,
178 bool IsVolatile = false);
180 /// \brief Get a directory_iterator for \p Dir.
181 /// \note The 'end' iterator is directory_iterator()
182 virtual directory_iterator dir_begin(const Twine &Dir,
183 std::error_code &EC) = 0;
185 // TODO: recursive directory iterators
188 /// \brief Gets an \p vfs::FileSystem for the 'real' file system, as seen by
189 /// the operating system.
190 IntrusiveRefCntPtr<FileSystem> getRealFileSystem();
192 /// \brief A file system that allows overlaying one \p AbstractFileSystem on top
195 /// Consists of a stack of >=1 \p FileSystem objects, which are treated as being
196 /// one merged file system. When there is a directory that exists in more than
197 /// one file system, the \p OverlayFileSystem contains a directory containing
198 /// the union of their contents. The attributes (permissions, etc.) of the
199 /// top-most (most recently added) directory are used. When there is a file
200 /// that exists in more than one file system, the file in the top-most file
201 /// system overrides the other(s).
202 class OverlayFileSystem : public FileSystem {
203 typedef SmallVector<IntrusiveRefCntPtr<FileSystem>, 1> FileSystemList;
204 /// \brief The stack of file systems, implemented as a list in order of
206 FileSystemList FSList;
209 OverlayFileSystem(IntrusiveRefCntPtr<FileSystem> Base);
210 /// \brief Pushes a file system on top of the stack.
211 void pushOverlay(IntrusiveRefCntPtr<FileSystem> FS);
213 llvm::ErrorOr<Status> status(const Twine &Path) override;
214 std::error_code openFileForRead(const Twine &Path,
215 std::unique_ptr<File> &Result) override;
216 directory_iterator dir_begin(const Twine &Dir, std::error_code &EC) override;
218 typedef FileSystemList::reverse_iterator iterator;
220 /// \brief Get an iterator pointing to the most recently added file system.
221 iterator overlays_begin() { return FSList.rbegin(); }
223 /// \brief Get an iterator pointing one-past the least recently added file
225 iterator overlays_end() { return FSList.rend(); }
228 /// \brief Get a globally unique ID for a virtual file or directory.
229 llvm::sys::fs::UniqueID getNextVirtualUniqueID();
231 /// \brief Gets a \p FileSystem for a virtual file system described in YAML
234 /// Takes ownership of \p Buffer.
235 IntrusiveRefCntPtr<FileSystem>
236 getVFSFromYAML(llvm::MemoryBuffer *Buffer,
237 llvm::SourceMgr::DiagHandlerTy DiagHandler,
238 void *DiagContext = nullptr,
239 IntrusiveRefCntPtr<FileSystem> ExternalFS = getRealFileSystem());
241 struct YAMLVFSEntry {
242 template <typename T1, typename T2> YAMLVFSEntry(T1 &&VPath, T2 &&RPath)
243 : VPath(std::forward<T1>(VPath)), RPath(std::forward<T2>(RPath)) {}
248 class YAMLVFSWriter {
249 std::vector<YAMLVFSEntry> Mappings;
250 Optional<bool> IsCaseSensitive;
254 void addFileMapping(StringRef VirtualPath, StringRef RealPath);
255 void setCaseSensitivity(bool CaseSensitive) {
256 IsCaseSensitive = CaseSensitive;
258 void write(llvm::raw_ostream &OS);
261 } // end namespace vfs
262 } // end namespace clang
263 #endif // LLVM_CLANG_BASIC_VIRTUAL_FILE_SYSTEM_H