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   /// Open the specified file as a MemoryBuffer, returning a new MemoryBuffer
78   /// if successful, otherwise returning null.
79   ///
80   /// \param IsText Set to true to indicate that the file should be read in
81   /// text mode.
82   ///
83   /// \param IsVolatile Set to true to indicate that the contents of the file
84   /// can change outside the user's control, e.g. when libclang tries to parse
85   /// while the user is editing/updating the file or if the file is on an NFS.
86   static ErrorOr<std::unique_ptr<MemoryBuffer>>
87   getFile(const Twine &Filename, bool IsText = false,
88           bool RequiresNullTerminator = true, bool IsVolatile = false);
89 
90   /// Read all of the specified file into a MemoryBuffer as a stream
91   /// (i.e. until EOF reached). This is useful for special files that
92   /// look like a regular file but have 0 size (e.g. /proc/cpuinfo on Linux).
93   static ErrorOr<std::unique_ptr<MemoryBuffer>>
94   getFileAsStream(const Twine &Filename);
95 
96   /// Given an already-open file descriptor, map some slice of it into a
97   /// MemoryBuffer. The slice is specified by an \p Offset and \p MapSize.
98   /// Since this is in the middle of a file, the buffer is not null terminated.
99   static ErrorOr<std::unique_ptr<MemoryBuffer>>
100   getOpenFileSlice(sys::fs::file_t FD, const Twine &Filename, uint64_t MapSize,
101                    int64_t Offset, bool IsVolatile = false);
102 
103   /// Given an already-open file descriptor, read the file and return a
104   /// MemoryBuffer.
105   ///
106   /// \param IsVolatile Set to true to indicate that the contents of the file
107   /// can change outside the user's control, e.g. when libclang tries to parse
108   /// while the user is editing/updating the file or if the file is on an NFS.
109   static ErrorOr<std::unique_ptr<MemoryBuffer>>
110   getOpenFile(sys::fs::file_t FD, const Twine &Filename, uint64_t FileSize,
111               bool RequiresNullTerminator = true, bool IsVolatile = false);
112 
113   /// Open the specified memory range as a MemoryBuffer. Note that InputData
114   /// must be null terminated if RequiresNullTerminator is true.
115   static std::unique_ptr<MemoryBuffer>
116   getMemBuffer(StringRef InputData, StringRef BufferName = "",
117                bool RequiresNullTerminator = true);
118 
119   static std::unique_ptr<MemoryBuffer>
120   getMemBuffer(MemoryBufferRef Ref, bool RequiresNullTerminator = true);
121 
122   /// Open the specified memory range as a MemoryBuffer, copying the contents
123   /// and taking ownership of it. InputData does not have to be null terminated.
124   static std::unique_ptr<MemoryBuffer>
125   getMemBufferCopy(StringRef InputData, const Twine &BufferName = "");
126 
127   /// Read all of stdin into a file buffer, and return it.
128   static ErrorOr<std::unique_ptr<MemoryBuffer>> getSTDIN();
129 
130   /// Open the specified file as a MemoryBuffer, or open stdin if the Filename
131   /// is "-".
132   static ErrorOr<std::unique_ptr<MemoryBuffer>>
133   getFileOrSTDIN(const Twine &Filename, bool IsText = false,
134                  bool RequiresNullTerminator = true);
135 
136   /// Map a subrange of the specified file as a MemoryBuffer.
137   static ErrorOr<std::unique_ptr<MemoryBuffer>>
138   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
139                bool IsVolatile = false);
140 
141   //===--------------------------------------------------------------------===//
142   // Provided for performance analysis.
143   //===--------------------------------------------------------------------===//
144 
145   /// The kind of memory backing used to support the MemoryBuffer.
146   enum BufferKind {
147     MemoryBuffer_Malloc,
148     MemoryBuffer_MMap
149   };
150 
151   /// Return information on the memory mechanism used to support the
152   /// MemoryBuffer.
153   virtual BufferKind getBufferKind() const = 0;
154 
155   MemoryBufferRef getMemBufferRef() const;
156 };
157 
158 /// This class is an extension of MemoryBuffer, which allows copy-on-write
159 /// access to the underlying contents.  It only supports creation methods that
160 /// are guaranteed to produce a writable buffer.  For example, mapping a file
161 /// read-only is not supported.
162 class WritableMemoryBuffer : public MemoryBuffer {
163 protected:
164   WritableMemoryBuffer() = default;
165 
166 public:
167   using MemoryBuffer::getBuffer;
168   using MemoryBuffer::getBufferEnd;
169   using MemoryBuffer::getBufferStart;
170 
171   // const_cast is well-defined here, because the underlying buffer is
172   // guaranteed to have been initialized with a mutable buffer.
173   char *getBufferStart() {
174     return const_cast<char *>(MemoryBuffer::getBufferStart());
175   }
176   char *getBufferEnd() {
177     return const_cast<char *>(MemoryBuffer::getBufferEnd());
178   }
179   MutableArrayRef<char> getBuffer() {
180     return {getBufferStart(), getBufferEnd()};
181   }
182 
183   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
184   getFile(const Twine &Filename, bool IsVolatile = false);
185 
186   /// Map a subrange of the specified file as a WritableMemoryBuffer.
187   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
188   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
189                bool IsVolatile = false);
190 
191   /// Allocate a new MemoryBuffer of the specified size that is not initialized.
192   /// Note that the caller should initialize the memory allocated by this
193   /// method. The memory is owned by the MemoryBuffer object.
194   static std::unique_ptr<WritableMemoryBuffer>
195   getNewUninitMemBuffer(size_t Size, const Twine &BufferName = "");
196 
197   /// Allocate a new zero-initialized MemoryBuffer of the specified size. Note
198   /// that the caller need not initialize the memory allocated by this method.
199   /// The memory is owned by the MemoryBuffer object.
200   static std::unique_ptr<WritableMemoryBuffer>
201   getNewMemBuffer(size_t Size, const Twine &BufferName = "");
202 
203 private:
204   // Hide these base class factory function so one can't write
205   //   WritableMemoryBuffer::getXXX()
206   // and be surprised that he got a read-only Buffer.
207   using MemoryBuffer::getFileAsStream;
208   using MemoryBuffer::getFileOrSTDIN;
209   using MemoryBuffer::getMemBuffer;
210   using MemoryBuffer::getMemBufferCopy;
211   using MemoryBuffer::getOpenFile;
212   using MemoryBuffer::getOpenFileSlice;
213   using MemoryBuffer::getSTDIN;
214 };
215 
216 /// This class is an extension of MemoryBuffer, which allows write access to
217 /// the underlying contents and committing those changes to the original source.
218 /// It only supports creation methods that are guaranteed to produce a writable
219 /// buffer.  For example, mapping a file read-only is not supported.
220 class WriteThroughMemoryBuffer : public MemoryBuffer {
221 protected:
222   WriteThroughMemoryBuffer() = default;
223 
224 public:
225   using MemoryBuffer::getBuffer;
226   using MemoryBuffer::getBufferEnd;
227   using MemoryBuffer::getBufferStart;
228 
229   // const_cast is well-defined here, because the underlying buffer is
230   // guaranteed to have been initialized with a mutable buffer.
231   char *getBufferStart() {
232     return const_cast<char *>(MemoryBuffer::getBufferStart());
233   }
234   char *getBufferEnd() {
235     return const_cast<char *>(MemoryBuffer::getBufferEnd());
236   }
237   MutableArrayRef<char> getBuffer() {
238     return {getBufferStart(), getBufferEnd()};
239   }
240 
241   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
242   getFile(const Twine &Filename, int64_t FileSize = -1);
243 
244   /// Map a subrange of the specified file as a ReadWriteMemoryBuffer.
245   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
246   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset);
247 
248 private:
249   // Hide these base class factory function so one can't write
250   //   WritableMemoryBuffer::getXXX()
251   // and be surprised that he got a read-only Buffer.
252   using MemoryBuffer::getFileAsStream;
253   using MemoryBuffer::getFileOrSTDIN;
254   using MemoryBuffer::getMemBuffer;
255   using MemoryBuffer::getMemBufferCopy;
256   using MemoryBuffer::getOpenFile;
257   using MemoryBuffer::getOpenFileSlice;
258   using MemoryBuffer::getSTDIN;
259 };
260 
261 // Create wrappers for C Binding types (see CBindingWrapping.h).
262 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(MemoryBuffer, LLVMMemoryBufferRef)
263 
264 } // end namespace llvm
265 
266 #endif // LLVM_SUPPORT_MEMORYBUFFER_H
267