[−]Trait symbolic::debuginfo::dwarf::gimli::Reader
A trait for reading the data from a DWARF section.
All read operations advance the section offset of the reader unless specified otherwise.
Choosing a Reader
Implementation
gimli
comes with a few different Reader
implementations and lets you
choose the one that is right for your use case. A Reader
is essentially a
view into the raw bytes that make up some DWARF, but this view might borrow
the underlying data or use reference counting ownership, and it might be
thread safe or not.
Implementation | Ownership | Thread Safe | Notes |
---|---|---|---|
EndianSlice | Borrowed | Yes | Fastest, but requires that all of your code work with borrows. |
EndianRcSlice | Reference counted | No | Shared ownership via reference counting, which alleviates the borrow restrictions of EndianSlice but imposes reference counting increments and decrements. Cannot be sent across threads, because the reference count is not atomic. |
EndianArcSlice | Reference counted | Yes | The same as EndianRcSlice , but uses atomic reference counting, and therefore reference counting operations are slower but EndianArcSlice s may be sent across threads. |
EndianReader<T> | Same as T | Same as T | Escape hatch for easily defining your own type of Reader . |
Associated Types
type Endian: Endianity
The endianity of bytes that are read.
type Offset: ReaderOffset
The type used for offsets and lengths.
Required methods
pub fn endian(&self) -> Self::Endian
Return the endianity of bytes that are read.
pub fn len(&self) -> Self::Offset
Return the number of bytes remaining.
pub fn empty(&mut self)
Set the number of bytes remaining to zero.
pub fn truncate(&mut self, len: Self::Offset) -> Result<(), Error>
Set the number of bytes remaining to the specified length.
pub fn offset_from(&self, base: &Self) -> Self::Offset
Return the offset of this reader's data relative to the start of the given base reader's data.
May panic if this reader's data is not contained within the given base reader's data.
pub fn offset_id(&self) -> ReaderOffsetId
Return an identifier for the current reader offset.
pub fn lookup_offset_id(&self, id: ReaderOffsetId) -> Option<Self::Offset>
Return the offset corresponding to the given id
if
it is associated with this reader.
pub fn find(&self, byte: u8) -> Result<Self::Offset, Error>
Find the index of the first occurence of the given byte. The offset of the reader is not changed.
pub fn skip(&mut self, len: Self::Offset) -> Result<(), Error>
Discard the specified number of bytes.
pub fn split(&mut self, len: Self::Offset) -> Result<Self, Error>
Split a reader in two.
A new reader is returned that can be used to read the next
len
bytes, and self
is advanced so that it reads the remainder.
pub fn to_slice(&self) -> Result<Cow<'_, [u8]>, Error>
Return all remaining data as a clone-on-write slice.
The slice will be borrowed where possible, but some readers may always return an owned vector.
Does not advance the reader.
pub fn to_string(&self) -> Result<Cow<'_, str>, Error>
Convert all remaining data to a clone-on-write string.
The string will be borrowed where possible, but some readers may always return an owned string.
Does not advance the reader.
Returns an error if the data contains invalid characters.
pub fn to_string_lossy(&self) -> Result<Cow<'_, str>, Error>
Convert all remaining data to a clone-on-write string, including invalid characters.
The string will be borrowed where possible, but some readers may always return an owned string.
Does not advance the reader.
pub fn read_slice(&mut self, buf: &mut [u8]) -> Result<(), Error>
Read exactly buf.len()
bytes into buf
.
Provided methods
pub fn read_u8_array<A>(&mut self) -> Result<A, Error> where
A: Default + AsMut<[u8]>,
A: Default + AsMut<[u8]>,
Read a u8 array.
pub fn is_empty(&self) -> bool
Return true if the number of bytes remaining is zero.
pub fn read_u8(&mut self) -> Result<u8, Error>
Read a u8.
pub fn read_i8(&mut self) -> Result<i8, Error>
Read an i8.
pub fn read_u16(&mut self) -> Result<u16, Error>
Read a u16.
pub fn read_i16(&mut self) -> Result<i16, Error>
Read an i16.
pub fn read_u32(&mut self) -> Result<u32, Error>
Read a u32.
pub fn read_i32(&mut self) -> Result<i32, Error>
Read an i32.
pub fn read_u64(&mut self) -> Result<u64, Error>
Read a u64.
pub fn read_i64(&mut self) -> Result<i64, Error>
Read an i64.
pub fn read_f32(&mut self) -> Result<f32, Error>
Read a f32.
pub fn read_f64(&mut self) -> Result<f64, Error>
Read a f64.
pub fn read_uint(&mut self, n: usize) -> Result<u64, Error>
pub fn read_null_terminated_slice(&mut self) -> Result<Self, Error>
Read a null-terminated slice, and return it (excluding the null).
pub fn read_uleb128(&mut self) -> Result<u64, Error>
Read an unsigned LEB128 encoded integer.
pub fn read_uleb128_u16(&mut self) -> Result<u16, Error>
Read an unsigned LEB128 encoded u16.
pub fn read_sleb128(&mut self) -> Result<i64, Error>
Read a signed LEB128 encoded integer.
pub fn read_initial_length(&mut self) -> Result<(Self::Offset, Format), Error>
Read an initial length field.
This field is encoded as either a 32-bit length or
a 64-bit length, and the returned Format
indicates which.
pub fn read_address(&mut self, address_size: u8) -> Result<u64, Error>
Read an address-sized integer, and return it as a u64
.
pub fn read_word(&mut self, format: Format) -> Result<Self::Offset, Error>
Parse a word-sized integer according to the DWARF format.
These are always used to encode section offsets or lengths,
and so have a type of Self::Offset
.
pub fn read_length(&mut self, format: Format) -> Result<Self::Offset, Error>
Parse a word-sized section length according to the DWARF format.
pub fn read_offset(&mut self, format: Format) -> Result<Self::Offset, Error>
Parse a word-sized section offset according to the DWARF format.
pub fn read_sized_offset(&mut self, size: u8) -> Result<Self::Offset, Error>
Parse a section offset of the given size.
This is used for DW_FORM_ref_addr
values in DWARF version 2.
Implementors
impl<'input, Endian> Reader for EndianSlice<'input, Endian> where
Endian: Endianity,
Endian: Endianity,
type Endian = Endian
type Offset = usize
pub fn endian(&self) -> Endian
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool
pub fn empty(&mut self)
pub fn truncate(&mut self, len: usize) -> Result<(), Error>
pub fn offset_from(&self, base: &EndianSlice<'input, Endian>) -> usize
pub fn offset_id(&self) -> ReaderOffsetId
pub fn lookup_offset_id(
&self,
id: ReaderOffsetId
) -> Option<<EndianSlice<'input, Endian> as Reader>::Offset>
&self,
id: ReaderOffsetId
) -> Option<<EndianSlice<'input, Endian> as Reader>::Offset>
pub fn find(&self, byte: u8) -> Result<usize, Error>
pub fn skip(&mut self, len: usize) -> Result<(), Error>
pub fn split(
&mut self,
len: usize
) -> Result<EndianSlice<'input, Endian>, Error>
&mut self,
len: usize
) -> Result<EndianSlice<'input, Endian>, Error>