LLVM  4.0.0
DataExtractor.h
Go to the documentation of this file.
1 //===-- DataExtractor.h -----------------------------------------*- 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 #ifndef LLVM_SUPPORT_DATAEXTRACTOR_H
11 #define LLVM_SUPPORT_DATAEXTRACTOR_H
12 
13 #include "llvm/ADT/StringRef.h"
14 #include "llvm/Support/DataTypes.h"
15 
16 namespace llvm {
18  StringRef Data;
19  uint8_t IsLittleEndian;
20  uint8_t AddressSize;
21 public:
22  /// Construct with a buffer that is owned by the caller.
23  ///
24  /// This constructor allows us to use data that is owned by the
25  /// caller. The data must stay around as long as this object is
26  /// valid.
27  DataExtractor(StringRef Data, bool IsLittleEndian, uint8_t AddressSize)
28  : Data(Data), IsLittleEndian(IsLittleEndian), AddressSize(AddressSize) {}
29 
30  /// \brief Get the data pointed to by this extractor.
31  StringRef getData() const { return Data; }
32  /// \brief Get the endianness for this extractor.
33  bool isLittleEndian() const { return IsLittleEndian; }
34  /// \brief Get the address size for this extractor.
35  uint8_t getAddressSize() const { return AddressSize; }
36  /// \brief Set the address size for this extractor.
37  void setAddressSize(uint8_t Size) { AddressSize = Size; }
38 
39  /// Extract a C string from \a *offset_ptr.
40  ///
41  /// Returns a pointer to a C String from the data at the offset
42  /// pointed to by \a offset_ptr. A variable length NULL terminated C
43  /// string will be extracted and the \a offset_ptr will be
44  /// updated with the offset of the byte that follows the NULL
45  /// terminator byte.
46  ///
47  /// @param[in,out] offset_ptr
48  /// A pointer to an offset within the data that will be advanced
49  /// by the appropriate number of bytes if the value is extracted
50  /// correctly. If the offset is out of bounds or there are not
51  /// enough bytes to extract this value, the offset will be left
52  /// unmodified.
53  ///
54  /// @return
55  /// A pointer to the C string value in the data. If the offset
56  /// pointed to by \a offset_ptr is out of bounds, or if the
57  /// offset plus the length of the C string is out of bounds,
58  /// NULL will be returned.
59  const char *getCStr(uint32_t *offset_ptr) const;
60 
61  /// Extract an unsigned integer of size \a byte_size from \a
62  /// *offset_ptr.
63  ///
64  /// Extract a single unsigned integer value and update the offset
65  /// pointed to by \a offset_ptr. The size of the extracted integer
66  /// is specified by the \a byte_size argument. \a byte_size should
67  /// have a value greater than or equal to one and less than or equal
68  /// to eight since the return value is 64 bits wide. Any
69  /// \a byte_size values less than 1 or greater than 8 will result in
70  /// nothing being extracted, and zero being returned.
71  ///
72  /// @param[in,out] offset_ptr
73  /// A pointer to an offset within the data that will be advanced
74  /// by the appropriate number of bytes if the value is extracted
75  /// correctly. If the offset is out of bounds or there are not
76  /// enough bytes to extract this value, the offset will be left
77  /// unmodified.
78  ///
79  /// @param[in] byte_size
80  /// The size in byte of the integer to extract.
81  ///
82  /// @return
83  /// The unsigned integer value that was extracted, or zero on
84  /// failure.
85  uint64_t getUnsigned(uint32_t *offset_ptr, uint32_t byte_size) const;
86 
87  /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
88  ///
89  /// Extract a single signed integer value (sign extending if required)
90  /// and update the offset pointed to by \a offset_ptr. The size of
91  /// the extracted integer is specified by the \a byte_size argument.
92  /// \a byte_size should have a value greater than or equal to one
93  /// and less than or equal to eight since the return value is 64
94  /// bits wide. Any \a byte_size values less than 1 or greater than
95  /// 8 will result in nothing being extracted, and zero being returned.
96  ///
97  /// @param[in,out] offset_ptr
98  /// A pointer to an offset within the data that will be advanced
99  /// by the appropriate number of bytes if the value is extracted
100  /// correctly. If the offset is out of bounds or there are not
101  /// enough bytes to extract this value, the offset will be left
102  /// unmodified.
103  ///
104  /// @param[in] size
105  /// The size in bytes of the integer to extract.
106  ///
107  /// @return
108  /// The sign extended signed integer value that was extracted,
109  /// or zero on failure.
110  int64_t getSigned(uint32_t *offset_ptr, uint32_t size) const;
111 
112  //------------------------------------------------------------------
113  /// Extract an pointer from \a *offset_ptr.
114  ///
115  /// Extract a single pointer from the data and update the offset
116  /// pointed to by \a offset_ptr. The size of the extracted pointer
117  /// is \a getAddressSize(), so the address size has to be
118  /// set correctly prior to extracting any pointer values.
119  ///
120  /// @param[in,out] offset_ptr
121  /// A pointer to an offset within the data that will be advanced
122  /// by the appropriate number of bytes if the value is extracted
123  /// correctly. If the offset is out of bounds or there are not
124  /// enough bytes to extract this value, the offset will be left
125  /// unmodified.
126  ///
127  /// @return
128  /// The extracted pointer value as a 64 integer.
129  uint64_t getAddress(uint32_t *offset_ptr) const {
130  return getUnsigned(offset_ptr, AddressSize);
131  }
132 
133  /// Extract a uint8_t value from \a *offset_ptr.
134  ///
135  /// Extract a single uint8_t from the binary data at the offset
136  /// pointed to by \a offset_ptr, and advance the offset on success.
137  ///
138  /// @param[in,out] offset_ptr
139  /// A pointer to an offset within the data that will be advanced
140  /// by the appropriate number of bytes if the value is extracted
141  /// correctly. If the offset is out of bounds or there are not
142  /// enough bytes to extract this value, the offset will be left
143  /// unmodified.
144  ///
145  /// @return
146  /// The extracted uint8_t value.
147  uint8_t getU8(uint32_t *offset_ptr) const;
148 
149  /// Extract \a count uint8_t values from \a *offset_ptr.
150  ///
151  /// Extract \a count uint8_t values from the binary data at the
152  /// offset pointed to by \a offset_ptr, and advance the offset on
153  /// success. The extracted values are copied into \a dst.
154  ///
155  /// @param[in,out] offset_ptr
156  /// A pointer to an offset within the data that will be advanced
157  /// by the appropriate number of bytes if the value is extracted
158  /// correctly. If the offset is out of bounds or there are not
159  /// enough bytes to extract this value, the offset will be left
160  /// unmodified.
161  ///
162  /// @param[out] dst
163  /// A buffer to copy \a count uint8_t values into. \a dst must
164  /// be large enough to hold all requested data.
165  ///
166  /// @param[in] count
167  /// The number of uint8_t values to extract.
168  ///
169  /// @return
170  /// \a dst if all values were properly extracted and copied,
171  /// NULL otherise.
172  uint8_t *getU8(uint32_t *offset_ptr, uint8_t *dst, uint32_t count) const;
173 
174  //------------------------------------------------------------------
175  /// Extract a uint16_t value from \a *offset_ptr.
176  ///
177  /// Extract a single uint16_t from the binary data at the offset
178  /// pointed to by \a offset_ptr, and update the offset on success.
179  ///
180  /// @param[in,out] offset_ptr
181  /// A pointer to an offset within the data that will be advanced
182  /// by the appropriate number of bytes if the value is extracted
183  /// correctly. If the offset is out of bounds or there are not
184  /// enough bytes to extract this value, the offset will be left
185  /// unmodified.
186  ///
187  /// @return
188  /// The extracted uint16_t value.
189  //------------------------------------------------------------------
190  uint16_t getU16(uint32_t *offset_ptr) const;
191 
192  /// Extract \a count uint16_t values from \a *offset_ptr.
193  ///
194  /// Extract \a count uint16_t values from the binary data at the
195  /// offset pointed to by \a offset_ptr, and advance the offset on
196  /// success. The extracted values are copied into \a dst.
197  ///
198  /// @param[in,out] offset_ptr
199  /// A pointer to an offset within the data that will be advanced
200  /// by the appropriate number of bytes if the value is extracted
201  /// correctly. If the offset is out of bounds or there are not
202  /// enough bytes to extract this value, the offset will be left
203  /// unmodified.
204  ///
205  /// @param[out] dst
206  /// A buffer to copy \a count uint16_t values into. \a dst must
207  /// be large enough to hold all requested data.
208  ///
209  /// @param[in] count
210  /// The number of uint16_t values to extract.
211  ///
212  /// @return
213  /// \a dst if all values were properly extracted and copied,
214  /// NULL otherise.
215  uint16_t *getU16(uint32_t *offset_ptr, uint16_t *dst, uint32_t count) const;
216 
217  /// Extract a uint32_t value from \a *offset_ptr.
218  ///
219  /// Extract a single uint32_t from the binary data at the offset
220  /// pointed to by \a offset_ptr, and update the offset on success.
221  ///
222  /// @param[in,out] offset_ptr
223  /// A pointer to an offset within the data that will be advanced
224  /// by the appropriate number of bytes if the value is extracted
225  /// correctly. If the offset is out of bounds or there are not
226  /// enough bytes to extract this value, the offset will be left
227  /// unmodified.
228  ///
229  /// @return
230  /// The extracted uint32_t value.
231  uint32_t getU32(uint32_t *offset_ptr) const;
232 
233  /// Extract \a count uint32_t values from \a *offset_ptr.
234  ///
235  /// Extract \a count uint32_t values from the binary data at the
236  /// offset pointed to by \a offset_ptr, and advance the offset on
237  /// success. The extracted values are copied into \a dst.
238  ///
239  /// @param[in,out] offset_ptr
240  /// A pointer to an offset within the data that will be advanced
241  /// by the appropriate number of bytes if the value is extracted
242  /// correctly. If the offset is out of bounds or there are not
243  /// enough bytes to extract this value, the offset will be left
244  /// unmodified.
245  ///
246  /// @param[out] dst
247  /// A buffer to copy \a count uint32_t values into. \a dst must
248  /// be large enough to hold all requested data.
249  ///
250  /// @param[in] count
251  /// The number of uint32_t values to extract.
252  ///
253  /// @return
254  /// \a dst if all values were properly extracted and copied,
255  /// NULL otherise.
256  uint32_t *getU32(uint32_t *offset_ptr, uint32_t *dst, uint32_t count) const;
257 
258  /// Extract a uint64_t value from \a *offset_ptr.
259  ///
260  /// Extract a single uint64_t from the binary data at the offset
261  /// pointed to by \a offset_ptr, and update the offset on success.
262  ///
263  /// @param[in,out] offset_ptr
264  /// A pointer to an offset within the data that will be advanced
265  /// by the appropriate number of bytes if the value is extracted
266  /// correctly. If the offset is out of bounds or there are not
267  /// enough bytes to extract this value, the offset will be left
268  /// unmodified.
269  ///
270  /// @return
271  /// The extracted uint64_t value.
272  uint64_t getU64(uint32_t *offset_ptr) const;
273 
274  /// Extract \a count uint64_t values from \a *offset_ptr.
275  ///
276  /// Extract \a count uint64_t values from the binary data at the
277  /// offset pointed to by \a offset_ptr, and advance the offset on
278  /// success. The extracted values are copied into \a dst.
279  ///
280  /// @param[in,out] offset_ptr
281  /// A pointer to an offset within the data that will be advanced
282  /// by the appropriate number of bytes if the value is extracted
283  /// correctly. If the offset is out of bounds or there are not
284  /// enough bytes to extract this value, the offset will be left
285  /// unmodified.
286  ///
287  /// @param[out] dst
288  /// A buffer to copy \a count uint64_t values into. \a dst must
289  /// be large enough to hold all requested data.
290  ///
291  /// @param[in] count
292  /// The number of uint64_t values to extract.
293  ///
294  /// @return
295  /// \a dst if all values were properly extracted and copied,
296  /// NULL otherise.
297  uint64_t *getU64(uint32_t *offset_ptr, uint64_t *dst, uint32_t count) const;
298 
299  /// Extract a signed LEB128 value from \a *offset_ptr.
300  ///
301  /// Extracts an signed LEB128 number from this object's data
302  /// starting at the offset pointed to by \a offset_ptr. The offset
303  /// pointed to by \a offset_ptr will be updated with the offset of
304  /// the byte following the last extracted byte.
305  ///
306  /// @param[in,out] offset_ptr
307  /// A pointer to an offset within the data that will be advanced
308  /// by the appropriate number of bytes if the value is extracted
309  /// correctly. If the offset is out of bounds or there are not
310  /// enough bytes to extract this value, the offset will be left
311  /// unmodified.
312  ///
313  /// @return
314  /// The extracted signed integer value.
315  int64_t getSLEB128(uint32_t *offset_ptr) const;
316 
317  /// Extract a unsigned LEB128 value from \a *offset_ptr.
318  ///
319  /// Extracts an unsigned LEB128 number from this object's data
320  /// starting at the offset pointed to by \a offset_ptr. The offset
321  /// pointed to by \a offset_ptr will be updated with the offset of
322  /// the byte following the last extracted byte.
323  ///
324  /// @param[in,out] offset_ptr
325  /// A pointer to an offset within the data that will be advanced
326  /// by the appropriate number of bytes if the value is extracted
327  /// correctly. If the offset is out of bounds or there are not
328  /// enough bytes to extract this value, the offset will be left
329  /// unmodified.
330  ///
331  /// @return
332  /// The extracted unsigned integer value.
333  uint64_t getULEB128(uint32_t *offset_ptr) const;
334 
335  /// Test the validity of \a offset.
336  ///
337  /// @return
338  /// \b true if \a offset is a valid offset into the data in this
339  /// object, \b false otherwise.
340  bool isValidOffset(uint32_t offset) const { return Data.size() > offset; }
341 
342  /// Test the availability of \a length bytes of data from \a offset.
343  ///
344  /// @return
345  /// \b true if \a offset is a valid offset and there are \a
346  /// length bytes available at that offset, \b false otherwise.
347  bool isValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const {
348  return offset + length >= offset && isValidOffset(offset + length - 1);
349  }
350 
351  /// Test the availability of enough bytes of data for a pointer from
352  /// \a offset. The size of a pointer is \a getAddressSize().
353  ///
354  /// @return
355  /// \b true if \a offset is a valid offset and there are enough
356  /// bytes for a pointer available at that offset, \b false
357  /// otherwise.
358  bool isValidOffsetForAddress(uint32_t offset) const {
359  return isValidOffsetForDataOfSize(offset, AddressSize);
360  }
361 };
362 
363 } // namespace llvm
364 
365 #endif
StringRef getData() const
Get the data pointed to by this extractor.
Definition: DataExtractor.h:31
bool isLittleEndian() const
Get the endianness for this extractor.
Definition: DataExtractor.h:33
uint8_t getAddressSize() const
Get the address size for this extractor.
Definition: DataExtractor.h:35
int64_t getSigned(uint32_t *offset_ptr, uint32_t size) const
Extract an signed integer of size byte_size from *offset_ptr.
bool isValidOffset(uint32_t offset) const
Test the validity of offset.
uint32_t getU32(uint32_t *offset_ptr) const
Extract a uint32_t value from *offset_ptr.
bool isValidOffsetForDataOfSize(uint32_t offset, uint32_t length) const
Test the availability of length bytes of data from offset.
auto count(R &&Range, const E &Element) -> typename std::iterator_traits< decltype(std::begin(Range))>::difference_type
Wrapper function around std::count to count the number of times an element Element occurs in the give...
Definition: STLExtras.h:791
LLVM_NODISCARD LLVM_ATTRIBUTE_ALWAYS_INLINE size_t size() const
size - Get the string size.
Definition: StringRef.h:135
const char * getCStr(uint32_t *offset_ptr) const
Extract a C string from *offset_ptr.
uint8_t getU8(uint32_t *offset_ptr) const
Extract a uint8_t value from *offset_ptr.
DataExtractor(StringRef Data, bool IsLittleEndian, uint8_t AddressSize)
Construct with a buffer that is owned by the caller.
Definition: DataExtractor.h:27
uint64_t getULEB128(uint32_t *offset_ptr) const
Extract a unsigned LEB128 value from *offset_ptr.
uint64_t getU64(uint32_t *offset_ptr) const
Extract a uint64_t value from *offset_ptr.
uint16_t getU16(uint32_t *offset_ptr) const
Extract a uint16_t value from *offset_ptr.
void setAddressSize(uint8_t Size)
Set the address size for this extractor.
Definition: DataExtractor.h:37
uint64_t getAddress(uint32_t *offset_ptr) const
Extract an pointer from *offset_ptr.
bool isValidOffsetForAddress(uint32_t offset) const
Test the availability of enough bytes of data for a pointer from offset.
uint64_t getUnsigned(uint32_t *offset_ptr, uint32_t byte_size) const
Extract an unsigned integer of size byte_size from *offset_ptr.
int64_t getSLEB128(uint32_t *offset_ptr) const
Extract a signed LEB128 value from *offset_ptr.
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:47