vendor/object/src/read/traits.rs - toolchain/rustc - Git at Google

 use alloc::borrow::Cow;

 use crate::read::{
     self, Architecture, CompressedData, FileFlags, Relocation, Result, SectionFlags, SectionIndex,
     SectionKind, Symbol, SymbolIndex, SymbolMap,
 };
 use crate::Endianness;

 /// An object file.
 pub trait Object<'data, 'file>: read::private::Sealed {
     /// A segment in the object file.
     type Segment: ObjectSegment<'data>;

     /// An iterator over the segments in the object file.
     type SegmentIterator: Iterator<Item = Self::Segment>;

     /// A section in the object file.
     type Section: ObjectSection<'data>;

     /// An iterator over the sections in the object file.
     type SectionIterator: Iterator<Item = Self::Section>;

     /// An iterator over the symbols in the object file.
     type SymbolIterator: Iterator<Item = (SymbolIndex, Symbol<'data>)>;

     /// Get the architecture type of the file.
     fn architecture(&self) -> Architecture;

     /// Get the endianness of the file.
     #[inline]
     fn endianness(&self) -> Endianness {
         if self.is_little_endian() {
             Endianness::Little
         } else {
             Endianness::Big
         }
     }

     /// Return true if the file is little endian, false if it is big endian.
     fn is_little_endian(&self) -> bool;

     /// Return true if the file can contain 64-bit addresses.
     fn is_64(&self) -> bool;

     /// Get an iterator over the segments in the file.
     fn segments(&'file self) -> Self::SegmentIterator;

     /// Get the entry point address of the binary
     fn entry(&'file self) -> u64;

     /// Get the section named `section_name`, if such a section exists.
     ///
     /// If `section_name` starts with a '.' then it is treated as a system section name,
     /// and is compared using the conventions specific to the object file format. This
     /// includes:
     /// - if ".text" is requested for a Mach-O object file, then the actual
     /// section name that is searched for is "__text".
     /// - if ".debug_info" is requested for an ELF object file, then
     /// ".zdebug_info" may be returned (and similarly for other debug sections).
     ///
     /// For some object files, multiple segments may contain sections with the same
     /// name. In this case, the first matching section will be used.
     ///
     /// This method skips over sections with invalid names.
     fn section_by_name(&'file self, section_name: &str) -> Option<Self::Section>;

     /// Get the section at the given index.
     ///
     /// The meaning of the index depends on the object file.
     ///
     /// For some object files, this requires iterating through all sections.
     ///
     /// Returns an error if the index is invalid.
     fn section_by_index(&'file self, index: SectionIndex) -> Result<Self::Section>;

     /// Get an iterator over the sections in the file.
     fn sections(&'file self) -> Self::SectionIterator;

     /// Get the debugging symbol at the given index.
     ///
     /// The meaning of the index depends on the object file.
     ///
     /// Returns an error if the index is invalid.
     fn symbol_by_index(&self, index: SymbolIndex) -> Result<Symbol<'data>>;

     /// Get an iterator over the debugging symbols in the file.
     ///
     /// This may skip over symbols that are malformed or unsupported.
     fn symbols(&'file self) -> Self::SymbolIterator;

     /// Get the data for the given symbol.
     ///
     /// This may iterate over segments.
     ///
     /// Returns `Ok(None)` for undefined symbols or if the data could not be found.
     fn symbol_data(&'file self, symbol: &Symbol<'data>) -> Result<Option<&'data [u8]>> {
         if symbol.is_undefined() {
             return Ok(None);
         }
         let address = symbol.address();
         let size = symbol.size();
         if let Some(index) = symbol.section_index() {
             let section = self.section_by_index(index)?;
             section.data_range(address, size)
         } else {
             for segment in self.segments() {
                 if let Some(data) = segment.data_range(address, size)? {
                     return Ok(Some(data));
                 }
             }
             Ok(None)
         }
     }

     /// Get an iterator over the dynamic linking symbols in the file.
     ///
     /// This may skip over symbols that are malformed or unsupported.
     fn dynamic_symbols(&'file self) -> Self::SymbolIterator;

     /// Construct a map from addresses to symbols.
     fn symbol_map(&self) -> SymbolMap<'data>;

     /// Return true if the file contains debug information sections, false if not.
     fn has_debug_symbols(&self) -> bool;

     /// The UUID from a Mach-O `LC_UUID` load command.
     #[inline]
     fn mach_uuid(&self) -> Result<Option<[u8; 16]>> {
         Ok(None)
     }

     /// The build ID from an ELF `NT_GNU_BUILD_ID` note.
     #[inline]
     fn build_id(&self) -> Result<Option<&'data [u8]>> {
         Ok(None)
     }

     /// The filename and CRC from a `.gnu_debuglink` section.
     #[inline]
     fn gnu_debuglink(&self) -> Result<Option<(&'data [u8], u32)>> {
         Ok(None)
     }

     /// File flags that are specific to each file format.
     fn flags(&self) -> FileFlags;
 }

 /// A loadable segment defined in an object file.
 ///
 /// For ELF, this is a program header with type `PT_LOAD`.
 /// For Mach-O, this is a load command with type `LC_SEGMENT` or `LC_SEGMENT_64`.
 pub trait ObjectSegment<'data>: read::private::Sealed {
     /// Returns the virtual address of the segment.
     fn address(&self) -> u64;

     /// Returns the size of the segment in memory.
     fn size(&self) -> u64;

     /// Returns the alignment of the segment in memory.
     fn align(&self) -> u64;

     /// Returns the offset and size of the segment in the file.
     fn file_range(&self) -> (u64, u64);

     /// Returns a reference to the file contents of the segment.
     ///
     /// The length of this data may be different from the size of the
     /// segment in memory.
     fn data(&self) -> Result<&'data [u8]>;

     /// Return the segment data in the given range.
     ///
     /// Returns `Ok(None)` if the segment does not contain the given range.
     fn data_range(&self, address: u64, size: u64) -> Result<Option<&'data [u8]>>;

     /// Returns the name of the segment.
     fn name(&self) -> Result<Option<&str>>;
 }

 /// A section defined in an object file.
 pub trait ObjectSection<'data>: read::private::Sealed {
     /// An iterator over the relocations for a section.
     ///
     /// The first field in the item tuple is the section offset
     /// that the relocation applies to.
     type RelocationIterator: Iterator<Item = (u64, Relocation)>;

     /// Returns the section index.
     fn index(&self) -> SectionIndex;

     /// Returns the address of the section.
     fn address(&self) -> u64;

     /// Returns the size of the section in memory.
     fn size(&self) -> u64;

     /// Returns the alignment of the section in memory.
     fn align(&self) -> u64;

     /// Returns offset and size of on-disk segment (if any).
     fn file_range(&self) -> Option<(u64, u64)>;

     /// Returns the raw contents of the section.
     ///
     /// The length of this data may be different from the size of the
     /// section in memory.
     ///
     /// This does not do any decompression.
     fn data(&self) -> Result<&'data [u8]>;

     /// Return the raw contents of the section data in the given range.
     ///
     /// This does not do any decompression.
     ///
     /// Returns `Ok(None)` if the section does not contain the given range.
     fn data_range(&self, address: u64, size: u64) -> Result<Option<&'data [u8]>>;

     /// Returns the potentially compressed contents of the section,
     /// along with information about the compression.
     fn compressed_data(&self) -> Result<CompressedData<'data>>;

     /// Returns the uncompressed contents of the section.
     ///
     /// The length of this data may be different from the size of the
     /// section in memory.
     ///
     /// If no compression is detected, then returns the data unchanged.
     /// Returns `Err` if decompression fails.
     fn uncompressed_data(&self) -> Result<Cow<'data, [u8]>> {
         self.compressed_data()?.decompress()
     }

     /// Returns the name of the section.
     fn name(&self) -> Result<&str>;

     /// Returns the name of the segment for this section.
     fn segment_name(&self) -> Result<Option<&str>>;

     /// Return the kind of this section.
     fn kind(&self) -> SectionKind;

     /// Get the relocations for this section.
     fn relocations(&self) -> Self::RelocationIterator;

     /// Section flags that are specific to each file format.
     fn flags(&self) -> SectionFlags;
 }
	use alloc::borrow::Cow;

	use crate::read::{
	self, Architecture, CompressedData, FileFlags, Relocation, Result, SectionFlags, SectionIndex,
	SectionKind, Symbol, SymbolIndex, SymbolMap,
	};
	use crate::Endianness;

	/// An object file.
	pub trait Object<'data, 'file>: read::private::Sealed {
	/// A segment in the object file.
	type Segment: ObjectSegment<'data>;

	/// An iterator over the segments in the object file.
	type SegmentIterator: Iterator<Item = Self::Segment>;

	/// A section in the object file.
	type Section: ObjectSection<'data>;

	/// An iterator over the sections in the object file.
	type SectionIterator: Iterator<Item = Self::Section>;

	/// An iterator over the symbols in the object file.
	type SymbolIterator: Iterator<Item = (SymbolIndex, Symbol<'data>)>;

	/// Get the architecture type of the file.
	fn architecture(&self) -> Architecture;

	/// Get the endianness of the file.
	#[inline]
	fn endianness(&self) -> Endianness {
	if self.is_little_endian() {
	Endianness::Little
	} else {
	Endianness::Big
	}
	}

	/// Return true if the file is little endian, false if it is big endian.
	fn is_little_endian(&self) -> bool;

	/// Return true if the file can contain 64-bit addresses.
	fn is_64(&self) -> bool;

	/// Get an iterator over the segments in the file.
	fn segments(&'file self) -> Self::SegmentIterator;

	/// Get the entry point address of the binary
	fn entry(&'file self) -> u64;

	/// Get the section named `section_name`, if such a section exists.
	///
	/// If `section_name` starts with a '.' then it is treated as a system section name,
	/// and is compared using the conventions specific to the object file format. This
	/// includes:
	/// - if ".text" is requested for a Mach-O object file, then the actual
	/// section name that is searched for is "__text".
	/// - if ".debug_info" is requested for an ELF object file, then
	/// ".zdebug_info" may be returned (and similarly for other debug sections).
	///
	/// For some object files, multiple segments may contain sections with the same
	/// name. In this case, the first matching section will be used.
	///
	/// This method skips over sections with invalid names.
	fn section_by_name(&'file self, section_name: &str) -> Option<Self::Section>;

	/// Get the section at the given index.
	///
	/// The meaning of the index depends on the object file.
	///
	/// For some object files, this requires iterating through all sections.
	///
	/// Returns an error if the index is invalid.
	fn section_by_index(&'file self, index: SectionIndex) -> Result<Self::Section>;

	/// Get an iterator over the sections in the file.
	fn sections(&'file self) -> Self::SectionIterator;

	/// Get the debugging symbol at the given index.
	///
	/// The meaning of the index depends on the object file.
	///
	/// Returns an error if the index is invalid.
	fn symbol_by_index(&self, index: SymbolIndex) -> Result<Symbol<'data>>;

	/// Get an iterator over the debugging symbols in the file.
	///
	/// This may skip over symbols that are malformed or unsupported.
	fn symbols(&'file self) -> Self::SymbolIterator;

	/// Get the data for the given symbol.
	///
	/// This may iterate over segments.
	///
	/// Returns `Ok(None)` for undefined symbols or if the data could not be found.
	fn symbol_data(&'file self, symbol: &Symbol<'data>) -> Result<Option<&'data [u8]>> {
	if symbol.is_undefined() {
	return Ok(None);
	}
	let address = symbol.address();
	let size = symbol.size();
	if let Some(index) = symbol.section_index() {
	let section = self.section_by_index(index)?;
	section.data_range(address, size)
	} else {
	for segment in self.segments() {
	if let Some(data) = segment.data_range(address, size)? {
	return Ok(Some(data));
	}
	}
	Ok(None)
	}
	}

	/// Get an iterator over the dynamic linking symbols in the file.
	///
	/// This may skip over symbols that are malformed or unsupported.
	fn dynamic_symbols(&'file self) -> Self::SymbolIterator;

	/// Construct a map from addresses to symbols.
	fn symbol_map(&self) -> SymbolMap<'data>;

	/// Return true if the file contains debug information sections, false if not.
	fn has_debug_symbols(&self) -> bool;

	/// The UUID from a Mach-O `LC_UUID` load command.
	#[inline]
	fn mach_uuid(&self) -> Result<Option<[u8; 16]>> {
	Ok(None)
	}

	/// The build ID from an ELF `NT_GNU_BUILD_ID` note.
	#[inline]
	fn build_id(&self) -> Result<Option<&'data [u8]>> {
	Ok(None)
	}

	/// The filename and CRC from a `.gnu_debuglink` section.
	#[inline]
	fn gnu_debuglink(&self) -> Result<Option<(&'data [u8], u32)>> {
	Ok(None)
	}

	/// File flags that are specific to each file format.
	fn flags(&self) -> FileFlags;
	}

	/// A loadable segment defined in an object file.
	///
	/// For ELF, this is a program header with type `PT_LOAD`.
	/// For Mach-O, this is a load command with type `LC_SEGMENT` or `LC_SEGMENT_64`.
	pub trait ObjectSegment<'data>: read::private::Sealed {
	/// Returns the virtual address of the segment.
	fn address(&self) -> u64;

	/// Returns the size of the segment in memory.
	fn size(&self) -> u64;

	/// Returns the alignment of the segment in memory.
	fn align(&self) -> u64;

	/// Returns the offset and size of the segment in the file.
	fn file_range(&self) -> (u64, u64);

	/// Returns a reference to the file contents of the segment.
	///
	/// The length of this data may be different from the size of the
	/// segment in memory.
	fn data(&self) -> Result<&'data [u8]>;

	/// Return the segment data in the given range.
	///
	/// Returns `Ok(None)` if the segment does not contain the given range.
	fn data_range(&self, address: u64, size: u64) -> Result<Option<&'data [u8]>>;

	/// Returns the name of the segment.
	fn name(&self) -> Result<Option<&str>>;
	}

	/// A section defined in an object file.
	pub trait ObjectSection<'data>: read::private::Sealed {
	/// An iterator over the relocations for a section.
	///
	/// The first field in the item tuple is the section offset
	/// that the relocation applies to.
	type RelocationIterator: Iterator<Item = (u64, Relocation)>;

	/// Returns the section index.
	fn index(&self) -> SectionIndex;

	/// Returns the address of the section.
	fn address(&self) -> u64;

	/// Returns the size of the section in memory.
	fn size(&self) -> u64;

	/// Returns the alignment of the section in memory.
	fn align(&self) -> u64;

	/// Returns offset and size of on-disk segment (if any).
	fn file_range(&self) -> Option<(u64, u64)>;

	/// Returns the raw contents of the section.
	///
	/// The length of this data may be different from the size of the
	/// section in memory.
	///
	/// This does not do any decompression.
	fn data(&self) -> Result<&'data [u8]>;

	/// Return the raw contents of the section data in the given range.
	///
	/// This does not do any decompression.
	///
	/// Returns `Ok(None)` if the section does not contain the given range.
	fn data_range(&self, address: u64, size: u64) -> Result<Option<&'data [u8]>>;

	/// Returns the potentially compressed contents of the section,
	/// along with information about the compression.
	fn compressed_data(&self) -> Result<CompressedData<'data>>;

	/// Returns the uncompressed contents of the section.
	///
	/// The length of this data may be different from the size of the
	/// section in memory.
	///
	/// If no compression is detected, then returns the data unchanged.
	/// Returns `Err` if decompression fails.
	fn uncompressed_data(&self) -> Result<Cow<'data, [u8]>> {
	self.compressed_data()?.decompress()
	}

	/// Returns the name of the section.
	fn name(&self) -> Result<&str>;

	/// Returns the name of the segment for this section.
	fn segment_name(&self) -> Result<Option<&str>>;

	/// Return the kind of this section.
	fn kind(&self) -> SectionKind;

	/// Get the relocations for this section.
	fn relocations(&self) -> Self::RelocationIterator;

	/// Section flags that are specific to each file format.
	fn flags(&self) -> SectionFlags;
	}