1//===-- DataExtractor.h -----------------------------------------*- 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#ifndef LLVM_SUPPORT_DATAEXTRACTOR_H
10#define LLVM_SUPPORT_DATAEXTRACTOR_H
11
12#include "llvm/ADT/StringRef.h"
13#include "llvm/Support/DataTypes.h"
14#include "llvm/Support/Error.h"
15
16namespace llvm {
17
18/// An auxiliary type to facilitate extraction of 3-byte entities.
19struct Uint24 {
20 uint8_t Bytes[3];
21 Uint24(uint8_t U) {
22 Bytes[0] = Bytes[1] = Bytes[2] = U;
23 }
24 Uint24(uint8_t U0, uint8_t U1, uint8_t U2) {
25 Bytes[0] = U0; Bytes[1] = U1; Bytes[2] = U2;
26 }
27 uint32_t getAsUint32(bool IsLittleEndian) const {
28 int LoIx = IsLittleEndian ? 0 : 2;
29 return Bytes[LoIx] + (Bytes[1] << 8) + (Bytes[2-LoIx] << 16);
30 }
31};
32
33using uint24_t = Uint24;
34static_assert(sizeof(uint24_t) == 3, "sizeof(uint24_t) != 3");
35
36/// Needed by swapByteOrder().
37inline uint24_t getSwappedBytes(uint24_t C) {
38 return uint24_t(C.Bytes[2], C.Bytes[1], C.Bytes[0]);
39}
40
41class DataExtractor {
42 StringRef Data;
43 uint8_t IsLittleEndian;
44 uint8_t AddressSize;
45public:
46 /// A class representing a position in a DataExtractor, as well as any error
47 /// encountered during extraction. It enables one to extract a sequence of
48 /// values without error-checking and then checking for errors in bulk at the
49 /// end. The class holds an Error object, so failing to check the result of
50 /// the parse will result in a runtime error. The error flag is sticky and
51 /// will cause all subsequent extraction functions to fail without even
52 /// attempting to parse and without updating the Cursor offset. After clearing
53 /// the error flag, one can again use the Cursor object for parsing.
54 class Cursor {
55 uint64_t Offset;
56 Error Err;
57
58 friend class DataExtractor;
59
60 public:
61 /// Construct a cursor for extraction from the given offset.
62 explicit Cursor(uint64_t Offset) : Offset(Offset), Err(Error::success()) {}
63
64 /// Checks whether the cursor is valid (i.e. no errors were encountered). In
65 /// case of errors, this does not clear the error flag -- one must call
66 /// takeError() instead.
67 explicit operator bool() { return !Err; }
68
69 /// Return the current position of this Cursor. In the error state this is
70 /// the position of the Cursor before the first error was encountered.
71 uint64_t tell() const { return Offset; }
72
73 /// Set the cursor to the new offset. This does not impact the error state.
74 void seek(uint64_t NewOffSet) { Offset = NewOffSet; }
75
76 /// Return error contained inside this Cursor, if any. Clears the internal
77 /// Cursor state.
78 Error takeError() { return std::move(Err); }
79 };
80
81 /// Construct with a buffer that is owned by the caller.
82 ///
83 /// This constructor allows us to use data that is owned by the
84 /// caller. The data must stay around as long as this object is
85 /// valid.
86 DataExtractor(StringRef Data, bool IsLittleEndian, uint8_t AddressSize)
87 : Data(Data), IsLittleEndian(IsLittleEndian), AddressSize(AddressSize) {}
88 DataExtractor(ArrayRef<uint8_t> Data, bool IsLittleEndian,
89 uint8_t AddressSize)
90 : Data(StringRef(reinterpret_cast<const char *>(Data.data()),
91 Data.size())),
92 IsLittleEndian(IsLittleEndian), AddressSize(AddressSize) {}
93
94 /// Get the data pointed to by this extractor.
95 StringRef getData() const { return Data; }
96 /// Get the endianness for this extractor.
97 bool isLittleEndian() const { return IsLittleEndian; }
98 /// Get the address size for this extractor.
99 uint8_t getAddressSize() const { return AddressSize; }
100 /// Set the address size for this extractor.
101 void setAddressSize(uint8_t Size) { AddressSize = Size; }
102
103 /// Extract a C string from \a *offset_ptr.
104 ///
105 /// Returns a pointer to a C String from the data at the offset
106 /// pointed to by \a offset_ptr. A variable length NULL terminated C
107 /// string will be extracted and the \a offset_ptr will be
108 /// updated with the offset of the byte that follows the NULL
109 /// terminator byte.
110 ///
111 /// @param[in,out] OffsetPtr
112 /// A pointer to an offset within the data that will be advanced
113 /// by the appropriate number of bytes if the value is extracted
114 /// correctly. If the offset is out of bounds or there are not
115 /// enough bytes to extract this value, the offset will be left
116 /// unmodified.
117 ///
118 /// @param[in,out] Err
119 /// A pointer to an Error object. Upon return the Error object is set to
120 /// indicate the result (success/failure) of the function. If the Error
121 /// object is already set when calling this function, no extraction is
122 /// performed.
123 ///
124 /// @return
125 /// A pointer to the C string value in the data. If the offset
126 /// pointed to by \a offset_ptr is out of bounds, or if the
127 /// offset plus the length of the C string is out of bounds,
128 /// NULL will be returned.
129 const char *getCStr(uint64_t *OffsetPtr, Error *Err = nullptr) const {
130 return getCStrRef(OffsetPtr, Err).data();
131 }
132
133 /// Extract a C string from the location given by the cursor. In case of an
134 /// extraction error, or if the cursor is already in an error state, a
135 /// nullptr is returned.
136 const char *getCStr(Cursor &C) const { return getCStrRef(C).data(); }
137
138 /// Extract a C string from \a *offset_ptr.
139 ///
140 /// Returns a StringRef for the C String from the data at the offset
141 /// pointed to by \a offset_ptr. A variable length NULL terminated C
142 /// string will be extracted and the \a offset_ptr will be
143 /// updated with the offset of the byte that follows the NULL
144 /// terminator byte.
145 ///
146 /// \param[in,out] OffsetPtr
147 /// A pointer to an offset within the data that will be advanced
148 /// by the appropriate number of bytes if the value is extracted
149 /// correctly. If the offset is out of bounds or there are not
150 /// enough bytes to extract this value, the offset will be left
151 /// unmodified.
152 ///
153 /// @param[in,out] Err
154 /// A pointer to an Error object. Upon return the Error object is set to
155 /// indicate the result (success/failure) of the function. If the Error
156 /// object is already set when calling this function, no extraction is
157 /// performed.
158 ///
159 /// \return
160 /// A StringRef for the C string value in the data. If the offset
161 /// pointed to by \a offset_ptr is out of bounds, or if the
162 /// offset plus the length of the C string is out of bounds,
163 /// a default-initialized StringRef will be returned.
164 StringRef getCStrRef(uint64_t *OffsetPtr, Error *Err = nullptr) const;
165
166 /// Extract a C string (as a StringRef) from the location given by the cursor.
167 /// In case of an extraction error, or if the cursor is already in an error
168 /// state, a default-initialized StringRef is returned.
169 StringRef getCStrRef(Cursor &C) const {
170 return getCStrRef(OffsetPtr: &C.Offset, Err: &C.Err);
171 }
172
173 /// Extract a fixed length string from \a *OffsetPtr and consume \a Length
174 /// bytes.
175 ///
176 /// Returns a StringRef for the string from the data at the offset
177 /// pointed to by \a OffsetPtr. A fixed length C string will be extracted
178 /// and the \a OffsetPtr will be advanced by \a Length bytes.
179 ///
180 /// \param[in,out] OffsetPtr
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 /// \param[in] Length
188 /// The length of the fixed length string to extract. If there are not
189 /// enough bytes in the data to extract the full string, the offset will
190 /// be left unmodified.
191 ///
192 /// \param[in] TrimChars
193 /// A set of characters to trim from the end of the string. Fixed length
194 /// strings are commonly either NULL terminated by one or more zero
195 /// bytes. Some clients have one or more spaces at the end of the string,
196 /// but a good default is to trim the NULL characters.
197 ///
198 /// \return
199 /// A StringRef for the C string value in the data. If the offset
200 /// pointed to by \a OffsetPtr is out of bounds, or if the
201 /// offset plus the length of the C string is out of bounds,
202 /// a default-initialized StringRef will be returned.
203 StringRef getFixedLengthString(uint64_t *OffsetPtr,
204 uint64_t Length, StringRef TrimChars = {"\0", 1}) const;
205
206 /// Extract a fixed number of bytes from the specified offset.
207 ///
208 /// Returns a StringRef for the bytes from the data at the offset
209 /// pointed to by \a OffsetPtr. A fixed length C string will be extracted
210 /// and the \a OffsetPtr will be advanced by \a Length bytes.
211 ///
212 /// \param[in,out] OffsetPtr
213 /// A pointer to an offset within the data that will be advanced
214 /// by the appropriate number of bytes if the value is extracted
215 /// correctly. If the offset is out of bounds or there are not
216 /// enough bytes to extract this value, the offset will be left
217 /// unmodified.
218 ///
219 /// \param[in] Length
220 /// The number of bytes to extract. If there are not enough bytes in the
221 /// data to extract all of the bytes, the offset will be left unmodified.
222 ///
223 /// @param[in,out] Err
224 /// A pointer to an Error object. Upon return the Error object is set to
225 /// indicate the result (success/failure) of the function. If the Error
226 /// object is already set when calling this function, no extraction is
227 /// performed.
228 ///
229 /// \return
230 /// A StringRef for the extracted bytes. If the offset pointed to by
231 /// \a OffsetPtr is out of bounds, or if the offset plus the length
232 /// is out of bounds, a default-initialized StringRef will be returned.
233 StringRef getBytes(uint64_t *OffsetPtr, uint64_t Length,
234 Error *Err = nullptr) const;
235
236 /// Extract a fixed number of bytes from the location given by the cursor. In
237 /// case of an extraction error, or if the cursor is already in an error
238 /// state, a default-initialized StringRef is returned.
239 StringRef getBytes(Cursor &C, uint64_t Length) {
240 return getBytes(OffsetPtr: &C.Offset, Length, Err: &C.Err);
241 }
242
243 /// Extract an unsigned integer of size \a byte_size from \a
244 /// *offset_ptr.
245 ///
246 /// Extract a single unsigned integer value and update the offset
247 /// pointed to by \a offset_ptr. The size of the extracted integer
248 /// is specified by the \a byte_size argument. \a byte_size should
249 /// have a value greater than or equal to one and less than or equal
250 /// to eight since the return value is 64 bits wide. Any
251 /// \a byte_size values less than 1 or greater than 8 will result in
252 /// nothing being extracted, and zero being returned.
253 ///
254 /// @param[in,out] offset_ptr
255 /// A pointer to an offset within the data that will be advanced
256 /// by the appropriate number of bytes if the value is extracted
257 /// correctly. If the offset is out of bounds or there are not
258 /// enough bytes to extract this value, the offset will be left
259 /// unmodified.
260 ///
261 /// @param[in] byte_size
262 /// The size in byte of the integer to extract.
263 ///
264 /// @param[in,out] Err
265 /// A pointer to an Error object. Upon return the Error object is set to
266 /// indicate the result (success/failure) of the function. If the Error
267 /// object is already set when calling this function, no extraction is
268 /// performed.
269 ///
270 /// @return
271 /// The unsigned integer value that was extracted, or zero on
272 /// failure.
273 uint64_t getUnsigned(uint64_t *offset_ptr, uint32_t byte_size,
274 Error *Err = nullptr) const;
275
276 /// Extract an unsigned integer of the given size from the location given by
277 /// the cursor. In case of an extraction error, or if the cursor is already in
278 /// an error state, zero is returned.
279 uint64_t getUnsigned(Cursor &C, uint32_t Size) const {
280 return getUnsigned(offset_ptr: &C.Offset, byte_size: Size, Err: &C.Err);
281 }
282
283 /// Extract an signed integer of size \a byte_size from \a *offset_ptr.
284 ///
285 /// Extract a single signed integer value (sign extending if required)
286 /// and update the offset pointed to by \a offset_ptr. The size of
287 /// the extracted integer is specified by the \a byte_size argument.
288 /// \a byte_size should have a value greater than or equal to one
289 /// and less than or equal to eight since the return value is 64
290 /// bits wide. Any \a byte_size values less than 1 or greater than
291 /// 8 will result in nothing being extracted, and zero being returned.
292 ///
293 /// @param[in,out] offset_ptr
294 /// A pointer to an offset within the data that will be advanced
295 /// by the appropriate number of bytes if the value is extracted
296 /// correctly. If the offset is out of bounds or there are not
297 /// enough bytes to extract this value, the offset will be left
298 /// unmodified.
299 ///
300 /// @param[in] size
301 /// The size in bytes of the integer to extract.
302 ///
303 /// @return
304 /// The sign extended signed integer value that was extracted,
305 /// or zero on failure.
306 int64_t getSigned(uint64_t *offset_ptr, uint32_t size) const;
307
308 //------------------------------------------------------------------
309 /// Extract an pointer from \a *offset_ptr.
310 ///
311 /// Extract a single pointer from the data and update the offset
312 /// pointed to by \a offset_ptr. The size of the extracted pointer
313 /// is \a getAddressSize(), so the address size has to be
314 /// set correctly prior to extracting any pointer values.
315 ///
316 /// @param[in,out] offset_ptr
317 /// A pointer to an offset within the data that will be advanced
318 /// by the appropriate number of bytes if the value is extracted
319 /// correctly. If the offset is out of bounds or there are not
320 /// enough bytes to extract this value, the offset will be left
321 /// unmodified.
322 ///
323 /// @return
324 /// The extracted pointer value as a 64 integer.
325 uint64_t getAddress(uint64_t *offset_ptr) const {
326 return getUnsigned(offset_ptr, byte_size: AddressSize);
327 }
328
329 /// Extract a pointer-sized unsigned integer from the location given by the
330 /// cursor. In case of an extraction error, or if the cursor is already in
331 /// an error state, zero is returned.
332 uint64_t getAddress(Cursor &C) const { return getUnsigned(C, Size: AddressSize); }
333
334 /// Extract a uint8_t value from \a *offset_ptr.
335 ///
336 /// Extract a single uint8_t from the binary data at the offset
337 /// pointed to by \a offset_ptr, and advance the offset on success.
338 ///
339 /// @param[in,out] offset_ptr
340 /// A pointer to an offset within the data that will be advanced
341 /// by the appropriate number of bytes if the value is extracted
342 /// correctly. If the offset is out of bounds or there are not
343 /// enough bytes to extract this value, the offset will be left
344 /// unmodified.
345 ///
346 /// @param[in,out] Err
347 /// A pointer to an Error object. Upon return the Error object is set to
348 /// indicate the result (success/failure) of the function. If the Error
349 /// object is already set when calling this function, no extraction is
350 /// performed.
351 ///
352 /// @return
353 /// The extracted uint8_t value.
354 uint8_t getU8(uint64_t *offset_ptr, Error *Err = nullptr) const;
355
356 /// Extract a single uint8_t value from the location given by the cursor. In
357 /// case of an extraction error, or if the cursor is already in an error
358 /// state, zero is returned.
359 uint8_t getU8(Cursor &C) const { return getU8(offset_ptr: &C.Offset, Err: &C.Err); }
360
361 /// Extract \a count uint8_t values from \a *offset_ptr.
362 ///
363 /// Extract \a count uint8_t values from the binary data at the
364 /// offset pointed to by \a offset_ptr, and advance the offset on
365 /// success. The extracted values are copied into \a dst.
366 ///
367 /// @param[in,out] offset_ptr
368 /// A pointer to an offset within the data that will be advanced
369 /// by the appropriate number of bytes if the value is extracted
370 /// correctly. If the offset is out of bounds or there are not
371 /// enough bytes to extract this value, the offset will be left
372 /// unmodified.
373 ///
374 /// @param[out] dst
375 /// A buffer to copy \a count uint8_t values into. \a dst must
376 /// be large enough to hold all requested data.
377 ///
378 /// @param[in] count
379 /// The number of uint8_t values to extract.
380 ///
381 /// @return
382 /// \a dst if all values were properly extracted and copied,
383 /// NULL otherise.
384 uint8_t *getU8(uint64_t *offset_ptr, uint8_t *dst, uint32_t count) const;
385
386 /// Extract \a Count uint8_t values from the location given by the cursor and
387 /// store them into the destination buffer. In case of an extraction error, or
388 /// if the cursor is already in an error state, a nullptr is returned and the
389 /// destination buffer is left unchanged.
390 uint8_t *getU8(Cursor &C, uint8_t *Dst, uint32_t Count) const;
391
392 /// Extract \a Count uint8_t values from the location given by the cursor and
393 /// store them into the destination vector. The vector is resized to fit the
394 /// extracted data. In case of an extraction error, or if the cursor is
395 /// already in an error state, the destination vector is left unchanged and
396 /// cursor is placed into an error state.
397 void getU8(Cursor &C, SmallVectorImpl<uint8_t> &Dst, uint32_t Count) const {
398 if (isValidOffsetForDataOfSize(offset: C.Offset, length: Count))
399 Dst.resize(N: Count);
400
401 // This relies on the fact that getU8 will not attempt to write to the
402 // buffer if isValidOffsetForDataOfSize(C.Offset, Count) is false.
403 getU8(C, Dst: Dst.data(), Count);
404 }
405
406 //------------------------------------------------------------------
407 /// Extract a uint16_t value from \a *offset_ptr.
408 ///
409 /// Extract a single uint16_t from the binary data at the offset
410 /// pointed to by \a offset_ptr, and update the offset on success.
411 ///
412 /// @param[in,out] offset_ptr
413 /// A pointer to an offset within the data that will be advanced
414 /// by the appropriate number of bytes if the value is extracted
415 /// correctly. If the offset is out of bounds or there are not
416 /// enough bytes to extract this value, the offset will be left
417 /// unmodified.
418 ///
419 /// @param[in,out] Err
420 /// A pointer to an Error object. Upon return the Error object is set to
421 /// indicate the result (success/failure) of the function. If the Error
422 /// object is already set when calling this function, no extraction is
423 /// performed.
424 ///
425 /// @return
426 /// The extracted uint16_t value.
427 //------------------------------------------------------------------
428 uint16_t getU16(uint64_t *offset_ptr, Error *Err = nullptr) const;
429
430 /// Extract a single uint16_t value from the location given by the cursor. In
431 /// case of an extraction error, or if the cursor is already in an error
432 /// state, zero is returned.
433 uint16_t getU16(Cursor &C) const { return getU16(offset_ptr: &C.Offset, Err: &C.Err); }
434
435 /// Extract \a count uint16_t values from \a *offset_ptr.
436 ///
437 /// Extract \a count uint16_t values from the binary data at the
438 /// offset pointed to by \a offset_ptr, and advance the offset on
439 /// success. The extracted values are copied into \a dst.
440 ///
441 /// @param[in,out] offset_ptr
442 /// A pointer to an offset within the data that will be advanced
443 /// by the appropriate number of bytes if the value is extracted
444 /// correctly. If the offset is out of bounds or there are not
445 /// enough bytes to extract this value, the offset will be left
446 /// unmodified.
447 ///
448 /// @param[out] dst
449 /// A buffer to copy \a count uint16_t values into. \a dst must
450 /// be large enough to hold all requested data.
451 ///
452 /// @param[in] count
453 /// The number of uint16_t values to extract.
454 ///
455 /// @return
456 /// \a dst if all values were properly extracted and copied,
457 /// NULL otherise.
458 uint16_t *getU16(uint64_t *offset_ptr, uint16_t *dst, uint32_t count) const;
459
460 /// Extract a 24-bit unsigned value from \a *offset_ptr and return it
461 /// in a uint32_t.
462 ///
463 /// Extract 3 bytes from the binary data at the offset pointed to by
464 /// \a offset_ptr, construct a uint32_t from them and update the offset
465 /// on success.
466 ///
467 /// @param[in,out] OffsetPtr
468 /// A pointer to an offset within the data that will be advanced
469 /// by the 3 bytes if the value is extracted correctly. If the offset
470 /// is out of bounds or there are not enough bytes to extract this value,
471 /// the offset will be left unmodified.
472 ///
473 /// @param[in,out] Err
474 /// A pointer to an Error object. Upon return the Error object is set to
475 /// indicate the result (success/failure) of the function. If the Error
476 /// object is already set when calling this function, no extraction is
477 /// performed.
478 ///
479 /// @return
480 /// The extracted 24-bit value represented in a uint32_t.
481 uint32_t getU24(uint64_t *OffsetPtr, Error *Err = nullptr) const;
482
483 /// Extract a single 24-bit unsigned value from the location given by the
484 /// cursor. In case of an extraction error, or if the cursor is already in an
485 /// error state, zero is returned.
486 uint32_t getU24(Cursor &C) const { return getU24(OffsetPtr: &C.Offset, Err: &C.Err); }
487
488 /// Extract a uint32_t value from \a *offset_ptr.
489 ///
490 /// Extract a single uint32_t from the binary data at the offset
491 /// pointed to by \a offset_ptr, and update the offset on success.
492 ///
493 /// @param[in,out] offset_ptr
494 /// A pointer to an offset within the data that will be advanced
495 /// by the appropriate number of bytes if the value is extracted
496 /// correctly. If the offset is out of bounds or there are not
497 /// enough bytes to extract this value, the offset will be left
498 /// unmodified.
499 ///
500 /// @param[in,out] Err
501 /// A pointer to an Error object. Upon return the Error object is set to
502 /// indicate the result (success/failure) of the function. If the Error
503 /// object is already set when calling this function, no extraction is
504 /// performed.
505 ///
506 /// @return
507 /// The extracted uint32_t value.
508 uint32_t getU32(uint64_t *offset_ptr, Error *Err = nullptr) const;
509
510 /// Extract a single uint32_t value from the location given by the cursor. In
511 /// case of an extraction error, or if the cursor is already in an error
512 /// state, zero is returned.
513 uint32_t getU32(Cursor &C) const { return getU32(offset_ptr: &C.Offset, Err: &C.Err); }
514
515 /// Extract \a count uint32_t values from \a *offset_ptr.
516 ///
517 /// Extract \a count uint32_t values from the binary data at the
518 /// offset pointed to by \a offset_ptr, and advance the offset on
519 /// success. The extracted values are copied into \a dst.
520 ///
521 /// @param[in,out] offset_ptr
522 /// A pointer to an offset within the data that will be advanced
523 /// by the appropriate number of bytes if the value is extracted
524 /// correctly. If the offset is out of bounds or there are not
525 /// enough bytes to extract this value, the offset will be left
526 /// unmodified.
527 ///
528 /// @param[out] dst
529 /// A buffer to copy \a count uint32_t values into. \a dst must
530 /// be large enough to hold all requested data.
531 ///
532 /// @param[in] count
533 /// The number of uint32_t values to extract.
534 ///
535 /// @return
536 /// \a dst if all values were properly extracted and copied,
537 /// NULL otherise.
538 uint32_t *getU32(uint64_t *offset_ptr, uint32_t *dst, uint32_t count) const;
539
540 /// Extract a uint64_t value from \a *offset_ptr.
541 ///
542 /// Extract a single uint64_t from the binary data at the offset
543 /// pointed to by \a offset_ptr, and update the offset on success.
544 ///
545 /// @param[in,out] offset_ptr
546 /// A pointer to an offset within the data that will be advanced
547 /// by the appropriate number of bytes if the value is extracted
548 /// correctly. If the offset is out of bounds or there are not
549 /// enough bytes to extract this value, the offset will be left
550 /// unmodified.
551 ///
552 /// @param[in,out] Err
553 /// A pointer to an Error object. Upon return the Error object is set to
554 /// indicate the result (success/failure) of the function. If the Error
555 /// object is already set when calling this function, no extraction is
556 /// performed.
557 ///
558 /// @return
559 /// The extracted uint64_t value.
560 uint64_t getU64(uint64_t *offset_ptr, Error *Err = nullptr) const;
561
562 /// Extract a single uint64_t value from the location given by the cursor. In
563 /// case of an extraction error, or if the cursor is already in an error
564 /// state, zero is returned.
565 uint64_t getU64(Cursor &C) const { return getU64(offset_ptr: &C.Offset, Err: &C.Err); }
566
567 /// Extract \a count uint64_t values from \a *offset_ptr.
568 ///
569 /// Extract \a count uint64_t values from the binary data at the
570 /// offset pointed to by \a offset_ptr, and advance the offset on
571 /// success. The extracted values are copied into \a dst.
572 ///
573 /// @param[in,out] offset_ptr
574 /// A pointer to an offset within the data that will be advanced
575 /// by the appropriate number of bytes if the value is extracted
576 /// correctly. If the offset is out of bounds or there are not
577 /// enough bytes to extract this value, the offset will be left
578 /// unmodified.
579 ///
580 /// @param[out] dst
581 /// A buffer to copy \a count uint64_t values into. \a dst must
582 /// be large enough to hold all requested data.
583 ///
584 /// @param[in] count
585 /// The number of uint64_t values to extract.
586 ///
587 /// @return
588 /// \a dst if all values were properly extracted and copied,
589 /// NULL otherise.
590 uint64_t *getU64(uint64_t *offset_ptr, uint64_t *dst, uint32_t count) const;
591
592 /// Extract a signed LEB128 value from \a *offset_ptr.
593 ///
594 /// Extracts an signed LEB128 number from this object's data
595 /// starting at the offset pointed to by \a offset_ptr. The offset
596 /// pointed to by \a offset_ptr will be updated with the offset of
597 /// the byte following the last extracted byte.
598 ///
599 /// @param[in,out] OffsetPtr
600 /// A pointer to an offset within the data that will be advanced
601 /// by the appropriate number of bytes if the value is extracted
602 /// correctly. If the offset is out of bounds or there are not
603 /// enough bytes to extract this value, the offset will be left
604 /// unmodified.
605 ///
606 /// @param[in,out] Err
607 /// A pointer to an Error object. Upon return the Error object is set to
608 /// indicate the result (success/failure) of the function. If the Error
609 /// object is already set when calling this function, no extraction is
610 /// performed.
611 ///
612 /// @return
613 /// The extracted signed integer value.
614 int64_t getSLEB128(uint64_t *OffsetPtr, Error *Err = nullptr) const;
615
616 /// Extract an signed LEB128 value from the location given by the cursor.
617 /// In case of an extraction error, or if the cursor is already in an error
618 /// state, zero is returned.
619 int64_t getSLEB128(Cursor &C) const { return getSLEB128(OffsetPtr: &C.Offset, Err: &C.Err); }
620
621 /// Extract a unsigned LEB128 value from \a *offset_ptr.
622 ///
623 /// Extracts an unsigned LEB128 number from this object's data
624 /// starting at the offset pointed to by \a offset_ptr. The offset
625 /// pointed to by \a offset_ptr will be updated with the offset of
626 /// the byte following the last extracted byte.
627 ///
628 /// @param[in,out] offset_ptr
629 /// A pointer to an offset within the data that will be advanced
630 /// by the appropriate number of bytes if the value is extracted
631 /// correctly. If the offset is out of bounds or there are not
632 /// enough bytes to extract this value, the offset will be left
633 /// unmodified.
634 ///
635 /// @param[in,out] Err
636 /// A pointer to an Error object. Upon return the Error object is set to
637 /// indicate the result (success/failure) of the function. If the Error
638 /// object is already set when calling this function, no extraction is
639 /// performed.
640 ///
641 /// @return
642 /// The extracted unsigned integer value.
643 uint64_t getULEB128(uint64_t *offset_ptr, llvm::Error *Err = nullptr) const;
644
645 /// Extract an unsigned LEB128 value from the location given by the cursor.
646 /// In case of an extraction error, or if the cursor is already in an error
647 /// state, zero is returned.
648 uint64_t getULEB128(Cursor &C) const { return getULEB128(offset_ptr: &C.Offset, Err: &C.Err); }
649
650 /// Advance the Cursor position by the given number of bytes. No-op if the
651 /// cursor is in an error state.
652 void skip(Cursor &C, uint64_t Length) const;
653
654 /// Return true iff the cursor is at the end of the buffer, regardless of the
655 /// error state of the cursor. The only way both eof and error states can be
656 /// true is if one attempts a read while the cursor is at the very end of the
657 /// data buffer.
658 bool eof(const Cursor &C) const { return size() == C.Offset; }
659
660 /// Test the validity of \a offset.
661 ///
662 /// @return
663 /// \b true if \a offset is a valid offset into the data in this
664 /// object, \b false otherwise.
665 bool isValidOffset(uint64_t offset) const { return size() > offset; }
666
667 /// Test the availability of \a length bytes of data from \a offset.
668 ///
669 /// @return
670 /// \b true if \a offset is a valid offset and there are \a
671 /// length bytes available at that offset, \b false otherwise.
672 bool isValidOffsetForDataOfSize(uint64_t offset, uint64_t length) const {
673 return offset + length >= offset && isValidOffset(offset: offset + length - 1);
674 }
675
676 /// Test the availability of enough bytes of data for a pointer from
677 /// \a offset. The size of a pointer is \a getAddressSize().
678 ///
679 /// @return
680 /// \b true if \a offset is a valid offset and there are enough
681 /// bytes for a pointer available at that offset, \b false
682 /// otherwise.
683 bool isValidOffsetForAddress(uint64_t offset) const {
684 return isValidOffsetForDataOfSize(offset, length: AddressSize);
685 }
686
687 /// Return the number of bytes in the underlying buffer.
688 size_t size() const { return Data.size(); }
689
690protected:
691 // Make it possible for subclasses to access these fields without making them
692 // public.
693 static uint64_t &getOffset(Cursor &C) { return C.Offset; }
694 static Error &getError(Cursor &C) { return C.Err; }
695
696private:
697 /// If it is possible to read \a Size bytes at offset \a Offset, returns \b
698 /// true. Otherwise, returns \b false. If \a E is not nullptr, also sets the
699 /// error object to indicate an error.
700 bool prepareRead(uint64_t Offset, uint64_t Size, Error *E) const;
701
702 template <typename T> T getU(uint64_t *OffsetPtr, Error *Err) const;
703 template <typename T>
704 T *getUs(uint64_t *OffsetPtr, T *Dst, uint32_t Count, Error *Err) const;
705};
706
707} // namespace llvm
708
709#endif
710

source code of llvm/include/llvm/Support/DataExtractor.h