1 //===--- MemoryBuffer.h - Memory Buffer Interface ---------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 //  This file defines the MemoryBuffer interface.
10 //
11 //===----------------------------------------------------------------------===//
12 
13 #ifndef LLVM_SUPPORT_MEMORYBUFFER_H
14 #define LLVM_SUPPORT_MEMORYBUFFER_H
15 
16 #include "llvm-c/Types.h"
17 #include "llvm/ADT/ArrayRef.h"
18 #include "llvm/ADT/StringRef.h"
19 #include "llvm/ADT/Twine.h"
20 #include "llvm/Support/CBindingWrapping.h"
21 #include "llvm/Support/ErrorOr.h"
22 #include "llvm/Support/MemoryBufferRef.h"
23 #include <cstddef>
24 #include <cstdint>
25 #include <memory>
26 
27 namespace llvm {
28 namespace sys {
29 namespace fs {
30 // Duplicated from FileSystem.h to avoid a dependency.
31 #if defined(_WIN32)
32 // A Win32 HANDLE is a typedef of void*
33 using file_t = void *;
34 #else
35 using file_t = int;
36 #endif
37 } // namespace fs
38 } // namespace sys
39 
40 /// This interface provides simple read-only access to a block of memory, and
41 /// provides simple methods for reading files and standard input into a memory
42 /// buffer.  In addition to basic access to the characters in the file, this
43 /// interface guarantees you can read one character past the end of the file,
44 /// and that this character will read as '\0'.
45 ///
46 /// The '\0' guarantee is needed to support an optimization -- it's intended to
47 /// be more efficient for clients which are reading all the data to stop
48 /// reading when they encounter a '\0' than to continually check the file
49 /// position to see if it has reached the end of the file.
50 class MemoryBuffer {
51   const char *BufferStart; // Start of the buffer.
52   const char *BufferEnd;   // End of the buffer.
53 
54 protected:
55   MemoryBuffer() = default;
56 
57   void init(const char *BufStart, const char *BufEnd,
58             bool RequiresNullTerminator);
59 
60 public:
61   MemoryBuffer(const MemoryBuffer &) = delete;
62   MemoryBuffer &operator=(const MemoryBuffer &) = delete;
63   virtual ~MemoryBuffer();
64 
65   const char *getBufferStart() const { return BufferStart; }
66   const char *getBufferEnd() const   { return BufferEnd; }
67   size_t getBufferSize() const { return BufferEnd-BufferStart; }
68 
69   StringRef getBuffer() const {
70     return StringRef(BufferStart, getBufferSize());
71   }
72 
73   /// Return an identifier for this buffer, typically the filename it was read
74   /// from.
75   virtual StringRef getBufferIdentifier() const { return "Unknown buffer"; }
76 
77   /// For read-only MemoryBuffer_MMap, mark the buffer as unused in the near
78   /// future and the kernel can free resources associated with it. Further
79   /// access is supported but may be expensive. This calls
80   /// madvise(MADV_DONTNEED) on read-only file mappings on *NIX systems. This
81   /// function should not be called on a writable buffer.
82   virtual void dontNeedIfMmap() {}
83 
84   /// Open the specified file as a MemoryBuffer, returning a new MemoryBuffer
85   /// if successful, otherwise returning null.
86   ///
87   /// \param IsText Set to true to indicate that the file should be read in
88   /// text mode.
89   ///
90   /// \param IsVolatile Set to true to indicate that the contents of the file
91   /// can change outside the user's control, e.g. when libclang tries to parse
92   /// while the user is editing/updating the file or if the file is on an NFS.
93   static ErrorOr<std::unique_ptr<MemoryBuffer>>
94   getFile(const Twine &Filename, bool IsText = false,
95           bool RequiresNullTerminator = true, bool IsVolatile = false);
96 
97   /// Read all of the specified file into a MemoryBuffer as a stream
98   /// (i.e. until EOF reached). This is useful for special files that
99   /// look like a regular file but have 0 size (e.g. /proc/cpuinfo on Linux).
100   static ErrorOr<std::unique_ptr<MemoryBuffer>>
101   getFileAsStream(const Twine &Filename);
102 
103   /// Given an already-open file descriptor, map some slice of it into a
104   /// MemoryBuffer. The slice is specified by an \p Offset and \p MapSize.
105   /// Since this is in the middle of a file, the buffer is not null terminated.
106   static ErrorOr<std::unique_ptr<MemoryBuffer>>
107   getOpenFileSlice(sys::fs::file_t FD, const Twine &Filename, uint64_t MapSize,
108                    int64_t Offset, bool IsVolatile = false);
109 
110   /// Given an already-open file descriptor, read the file and return a
111   /// MemoryBuffer.
112   ///
113   /// \param IsVolatile Set to true to indicate that the contents of the file
114   /// can change outside the user's control, e.g. when libclang tries to parse
115   /// while the user is editing/updating the file or if the file is on an NFS.
116   static ErrorOr<std::unique_ptr<MemoryBuffer>>
117   getOpenFile(sys::fs::file_t FD, const Twine &Filename, uint64_t FileSize,
118               bool RequiresNullTerminator = true, bool IsVolatile = false);
119 
120   /// Open the specified memory range as a MemoryBuffer. Note that InputData
121   /// must be null terminated if RequiresNullTerminator is true.
122   static std::unique_ptr<MemoryBuffer>
123   getMemBuffer(StringRef InputData, StringRef BufferName = "",
124                bool RequiresNullTerminator = true);
125 
126   static std::unique_ptr<MemoryBuffer>
127   getMemBuffer(MemoryBufferRef Ref, bool RequiresNullTerminator = true);
128 
129   /// Open the specified memory range as a MemoryBuffer, copying the contents
130   /// and taking ownership of it. InputData does not have to be null terminated.
131   static std::unique_ptr<MemoryBuffer>
132   getMemBufferCopy(StringRef InputData, const Twine &BufferName = "");
133 
134   /// Read all of stdin into a file buffer, and return it.
135   static ErrorOr<std::unique_ptr<MemoryBuffer>> getSTDIN();
136 
137   /// Open the specified file as a MemoryBuffer, or open stdin if the Filename
138   /// is "-".
139   static ErrorOr<std::unique_ptr<MemoryBuffer>>
140   getFileOrSTDIN(const Twine &Filename, bool IsText = false,
141                  bool RequiresNullTerminator = true);
142 
143   /// Map a subrange of the specified file as a MemoryBuffer.
144   static ErrorOr<std::unique_ptr<MemoryBuffer>>
145   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
146                bool IsVolatile = false);
147 
148   //===--------------------------------------------------------------------===//
149   // Provided for performance analysis.
150   //===--------------------------------------------------------------------===//
151 
152   /// The kind of memory backing used to support the MemoryBuffer.
153   enum BufferKind {
154     MemoryBuffer_Malloc,
155     MemoryBuffer_MMap
156   };
157 
158   /// Return information on the memory mechanism used to support the
159   /// MemoryBuffer.
160   virtual BufferKind getBufferKind() const = 0;
161 
162   MemoryBufferRef getMemBufferRef() const;
163 };
164 
165 /// This class is an extension of MemoryBuffer, which allows copy-on-write
166 /// access to the underlying contents.  It only supports creation methods that
167 /// are guaranteed to produce a writable buffer.  For example, mapping a file
168 /// read-only is not supported.
169 class WritableMemoryBuffer : public MemoryBuffer {
170 protected:
171   WritableMemoryBuffer() = default;
172 
173 public:
174   using MemoryBuffer::getBuffer;
175   using MemoryBuffer::getBufferEnd;
176   using MemoryBuffer::getBufferStart;
177 
178   // const_cast is well-defined here, because the underlying buffer is
179   // guaranteed to have been initialized with a mutable buffer.
180   char *getBufferStart() {
181     return const_cast<char *>(MemoryBuffer::getBufferStart());
182   }
183   char *getBufferEnd() {
184     return const_cast<char *>(MemoryBuffer::getBufferEnd());
185   }
186   MutableArrayRef<char> getBuffer() {
187     return {getBufferStart(), getBufferEnd()};
188   }
189 
190   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
191   getFile(const Twine &Filename, bool IsVolatile = false);
192 
193   /// Map a subrange of the specified file as a WritableMemoryBuffer.
194   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
195   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
196                bool IsVolatile = false);
197 
198   /// Allocate a new MemoryBuffer of the specified size that is not initialized.
199   /// Note that the caller should initialize the memory allocated by this
200   /// method. The memory is owned by the MemoryBuffer object.
201   static std::unique_ptr<WritableMemoryBuffer>
202   getNewUninitMemBuffer(size_t Size, const Twine &BufferName = "");
203 
204   /// Allocate a new zero-initialized MemoryBuffer of the specified size. Note
205   /// that the caller need not initialize the memory allocated by this method.
206   /// The memory is owned by the MemoryBuffer object.
207   static std::unique_ptr<WritableMemoryBuffer>
208   getNewMemBuffer(size_t Size, const Twine &BufferName = "");
209 
210 private:
211   // Hide these base class factory function so one can't write
212   //   WritableMemoryBuffer::getXXX()
213   // and be surprised that he got a read-only Buffer.
214   using MemoryBuffer::getFileAsStream;
215   using MemoryBuffer::getFileOrSTDIN;
216   using MemoryBuffer::getMemBuffer;
217   using MemoryBuffer::getMemBufferCopy;
218   using MemoryBuffer::getOpenFile;
219   using MemoryBuffer::getOpenFileSlice;
220   using MemoryBuffer::getSTDIN;
221 };
222 
223 /// This class is an extension of MemoryBuffer, which allows write access to
224 /// the underlying contents and committing those changes to the original source.
225 /// It only supports creation methods that are guaranteed to produce a writable
226 /// buffer.  For example, mapping a file read-only is not supported.
227 class WriteThroughMemoryBuffer : public MemoryBuffer {
228 protected:
229   WriteThroughMemoryBuffer() = default;
230 
231 public:
232   using MemoryBuffer::getBuffer;
233   using MemoryBuffer::getBufferEnd;
234   using MemoryBuffer::getBufferStart;
235 
236   // const_cast is well-defined here, because the underlying buffer is
237   // guaranteed to have been initialized with a mutable buffer.
238   char *getBufferStart() {
239     return const_cast<char *>(MemoryBuffer::getBufferStart());
240   }
241   char *getBufferEnd() {
242     return const_cast<char *>(MemoryBuffer::getBufferEnd());
243   }
244   MutableArrayRef<char> getBuffer() {
245     return {getBufferStart(), getBufferEnd()};
246   }
247 
248   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
249   getFile(const Twine &Filename, int64_t FileSize = -1);
250 
251   /// Map a subrange of the specified file as a ReadWriteMemoryBuffer.
252   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
253   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset);
254 
255 private:
256   // Hide these base class factory function so one can't write
257   //   WritableMemoryBuffer::getXXX()
258   // and be surprised that he got a read-only Buffer.
259   using MemoryBuffer::getFileAsStream;
260   using MemoryBuffer::getFileOrSTDIN;
261   using MemoryBuffer::getMemBuffer;
262   using MemoryBuffer::getMemBufferCopy;
263   using MemoryBuffer::getOpenFile;
264   using MemoryBuffer::getOpenFileSlice;
265   using MemoryBuffer::getSTDIN;
266 };
267 
268 // Create wrappers for C Binding types (see CBindingWrapping.h).
269 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(MemoryBuffer, LLVMMemoryBufferRef)
270 
271 } // end namespace llvm
272 
273 #endif // LLVM_SUPPORT_MEMORYBUFFER_H
274