Struct Object

pub struct Object<'a> {

    format: BinaryFormat,
    architecture: Architecture,
    sub_architecture: Option<SubArchitecture>,
    endian: Endianness,
    sections: Vec<Section<'a>>,
    standard_sections: HashMap<StandardSection, SectionId>,
    symbols: Vec<Symbol>,
    symbol_map: HashMap<Vec<u8>, SymbolId>,
    comdats: Vec<Comdat>,
    pub flags: FileFlags,
    pub mangling: Mangling,
    stub_symbols: HashMap<SymbolId, SymbolId>,
    tlv_bootstrap: Option<SymbolId>,
    macho_cpu_subtype: Option<u32>,
    macho_build_version: Option<MachOBuildVersion>,
    macho_subsections_via_symbols: bool,
}

A writable relocatable object file.

Fields

format: BinaryFormat

architecture: Architecture

sub_architecture: Option<SubArchitecture>

endian: Endianness

sections: Vec<Section<'a>>

standard_sections: HashMap<StandardSection, SectionId>

symbols: Vec<Symbol>

symbol_map: HashMap<Vec<u8>, SymbolId>

comdats: Vec<Comdat>

flags: FileFlags

File flags that are specific to each file format.

mangling: Mangling

The symbol name mangling scheme.

stub_symbols: HashMap<SymbolId, SymbolId>

tlv_bootstrap: Option<SymbolId>

macho_cpu_subtype: Option<u32>

macho_build_version: Option<MachOBuildVersion>

macho_subsections_via_symbols: bool

Implementations

impl<'a> Object<'a>

pub fn add_coff_exports(&mut self, style: CoffExportStyle)

Appends linker directives to the .drectve section to tell the linker to export all symbols with SymbolScope::Dynamic.

This must be called after all symbols have been defined.

impl<'a> Object<'a>

pub fn add_elf_gnu_property_u32(&mut self, property: u32, value: u32)

Add a property with a u32 value to the ELF “.note.gnu.property” section.

Requires feature = "elf".

impl<'a> Object<'a>

pub fn set_macho_cpu_subtype(&mut self, cpu_subtype: u32)

Specify the Mach-O CPU subtype.

Requires feature = "macho".

pub fn set_macho_build_version(&mut self, info: MachOBuildVersion)

Specify information for a Mach-O LC_BUILD_VERSION command.

Requires feature = "macho".

impl<'a> Object<'a>

pub fn new( format: BinaryFormat, architecture: Architecture, endian: Endianness, ) -> Object<'a>

Create an empty object file.

pub fn format(&self) -> BinaryFormat

Return the file format.

pub fn architecture(&self) -> Architecture

Return the architecture.

pub fn sub_architecture(&self) -> Option<SubArchitecture>

Return the sub-architecture.

pub fn set_sub_architecture( &mut self, sub_architecture: Option<SubArchitecture>, )

Specify the sub-architecture.

pub fn mangling(&self) -> Mangling

Return the current mangling setting.

pub fn set_mangling(&mut self, mangling: Mangling)

Specify the mangling setting.

pub fn segment_name(&self, segment: StandardSegment) -> &'static [u8]

Return the name for a standard segment.

This will vary based on the file format.

pub fn section(&self, section: SectionId) -> &Section<'a>

Get the section with the given SectionId.

pub fn section_mut(&mut self, section: SectionId) -> &mut Section<'a>

Mutably get the section with the given SectionId.

pub fn set_section_data<T>(&mut self, section: SectionId, data: T, align: u64)

where T: Into<Cow<'a, [u8]>>,

Set the data for an existing section.

Must not be called for sections that already have data, or that contain uninitialized data. align must be a power of two.

pub fn append_section_data( &mut self, section: SectionId, data: &[u8], align: u64, ) -> u64

Append data to an existing section. Returns the section offset of the data.

Must not be called for sections that contain uninitialized data. align must be a power of two.

pub fn append_section_bss( &mut self, section: SectionId, size: u64, align: u64, ) -> u64

Append zero-initialized data to an existing section. Returns the section offset of the data.

Must not be called for sections that contain initialized data. align must be a power of two.

pub fn section_id(&mut self, section: StandardSection) -> SectionId

Return the SectionId of a standard section.

If the section doesn’t already exist then it is created.

pub fn add_section( &mut self, segment: Vec<u8>, name: Vec<u8>, kind: SectionKind, ) -> SectionId

Add a new section and return its SectionId.

This also creates a section symbol.

pub fn add_subsection( &mut self, section: StandardSection, name: &[u8], ) -> SectionId

Add a subsection. Returns the SectionId and section offset of the data.

For Mach-O, this does not create a subsection, and instead uses the section from Self::section_id. Use Self::set_subsections_via_symbols to enable subsections via symbols.

pub fn set_subsections_via_symbols(&mut self)

Enable subsections via symbols if supported.

This should be called before adding any subsections or symbols.

For Mach-O, this sets the MH_SUBSECTIONS_VIA_SYMBOLS flag. For other formats, this does nothing.

pub fn default_section_flags(&self, section: &Section<'_>) -> SectionFlags

Return the default flags for a section.

The default flags are the section flags that will be written if the section flags are set to SectionFlags::None. These flags are determined by the file format and fields in the section such as the section kind.

This may return SectionFlags::None if the file format does not support the section kind.

pub fn section_flags(&self, section: &Section<'_>) -> SectionFlags

Return the flags for a section.

If section.flags is SectionFlags::None, then returns Self::default_section_flags. Otherwise, section.flags is returned as is.

pub fn section_flags_mut(&mut self, section_id: SectionId) -> &mut SectionFlags

Mutably get the flags for a section.

If section.flags is SectionFlags::None, then replace it with Self::default_section_flags first. Otherwise, &mut section.flags is returned as is.

pub fn comdat(&self, comdat: ComdatId) -> &Comdat

Get the COMDAT section group with the given ComdatId.

pub fn comdat_mut(&mut self, comdat: ComdatId) -> &mut Comdat

Mutably get the COMDAT section group with the given ComdatId.

pub fn add_comdat(&mut self, comdat: Comdat) -> ComdatId

Add a new COMDAT section group and return its ComdatId.

pub fn symbol_id(&self, name: &[u8]) -> Option<SymbolId>

Get the SymbolId of the symbol with the given name.

pub fn symbol(&self, symbol: SymbolId) -> &Symbol

Get the symbol with the given SymbolId.

pub fn symbol_mut(&mut self, symbol: SymbolId) -> &mut Symbol

Mutably get the symbol with the given SymbolId.

pub fn add_symbol(&mut self, symbol: Symbol) -> SymbolId

Add a new symbol and return its SymbolId.

If the symbol is a section symbol that is already defined, it will update the flags of the existing section symbol instead of creating adding a new symbol.

The symbol name will be modified to include the global prefix if the mangling scheme has one.

pub fn default_symbol_flags( &self, symbol: &Symbol, ) -> SymbolFlags<SectionId, SymbolId>

Return the default flags for a symbol.

The default flags are the symbol flags that will be written if the symbol flags are set to SymbolFlags::None. These flags are determined by the file format and fields in the symbol such as the symbol kind and scope. Therefore you should call this function after the symbol has been fully defined.

This may return SymbolFlags::None if the file format does not support symbol flags, or does not support the symbol kind or scope.

pub fn symbol_flags(&self, symbol: &Symbol) -> SymbolFlags<SectionId, SymbolId>

Return the flags for a symbol.

If symbol.flags is SymbolFlags::None, then returns Self::default_symbol_flags. Otherwise, symbol.flags is returned as is.

pub fn symbol_flags_mut( &mut self, symbol_id: SymbolId, ) -> &mut SymbolFlags<SectionId, SymbolId>

Mutably get the flags for a symbol.

If symbol.flags is SymbolFlags::None, then replace it with Self::default_symbol_flags. Otherwise, &mut symbol.flags is returned as is.

pub fn has_uninitialized_tls(&self) -> bool

Return true if the file format supports StandardSection::UninitializedTls.

pub fn has_common(&self) -> bool

Return true if the file format supports StandardSection::Common.

pub fn add_common_symbol( &mut self, symbol: Symbol, size: u64, align: u64, ) -> SymbolId

Add a new common symbol and return its SymbolId.

For Mach-O, this appends the symbol to the __common section.

align must be a power of two.

pub fn add_file_symbol(&mut self, name: Vec<u8>) -> SymbolId

Add a new file symbol and return its SymbolId.

pub fn section_symbol(&mut self, section_id: SectionId) -> SymbolId

Get the symbol for a section.

pub fn add_symbol_data( &mut self, symbol_id: SymbolId, section: SectionId, data: &[u8], align: u64, ) -> u64

Append data to an existing section, and update a symbol to refer to it.

For Mach-O, this also creates a __thread_vars entry for TLS symbols, and the symbol will indirectly point to the added data via the __thread_vars entry.

For Mach-O, if Self::set_subsections_via_symbols is enabled, this will automatically ensure the data size is at least 1.

Returns the section offset of the data.

Must not be called for sections that contain uninitialized data. align must be a power of two.

pub fn add_symbol_bss( &mut self, symbol_id: SymbolId, section: SectionId, size: u64, align: u64, ) -> u64

Append zero-initialized data to an existing section, and update a symbol to refer to it.

For Mach-O, this also creates a __thread_vars entry for TLS symbols, and the symbol will indirectly point to the added data via the __thread_vars entry.

For Mach-O, if Self::set_subsections_via_symbols is enabled, this will automatically ensure the data size is at least 1.

Returns the section offset of the data.

Must not be called for sections that contain initialized data. align must be a power of two.

pub fn set_symbol_data( &mut self, symbol_id: SymbolId, section: SectionId, offset: u64, size: u64, )

Update a symbol to refer to the given data within a section.

For Mach-O, this also creates a __thread_vars entry for TLS symbols, and the symbol will indirectly point to the data via the __thread_vars entry.

pub fn symbol_section_and_offset( &mut self, symbol_id: SymbolId, ) -> Option<(SymbolId, u64)>

Convert a symbol to a section symbol and offset.

Returns None if the symbol does not have a section.

pub fn add_relocation( &mut self, section: SectionId, relocation: Relocation, ) -> Result<(), Error>

Add a relocation to a section.

Relocations must only be added after the referenced symbols have been added and defined (if applicable).

pub fn write(&self) -> Result<Vec<u8>, Error>

Write the object to a Vec.

pub fn write_stream<W>(&self, w: W) -> Result<(), Box<dyn Error>>

where W: Write,

Write the object to a Write implementation.

Also flushes the writer.

It is advisable to use a buffered writer like BufWriter instead of an unbuffered writer like File.

pub fn emit(&self, buffer: &mut dyn WritableBuffer) -> Result<(), Error>

Write the object to a WritableBuffer.

Trait Implementations

impl<'a> Debug for Object<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.