Struct Section 

pub struct Section { /* private fields */ }

One section: a name, a kind, flags, an alignment, its contents (bytes, or for Bss only a size), an address, and the Relocations that patch it.

Build one with new and the with_* methods, or grow its contents in place with append and reserve, which handle padding and alignment.

In a relocatable object the address is normally zero and offsets within the section are what symbols and relocations refer to. In an executable, every loadable section has its final address.

Examples

use object_lang::{Section, SectionKind};

let mut rodata = Section::new(".rodata", SectionKind::ReadOnlyData);
let hello = rodata.append(b"hello\0", 1)?;
let table = rodata.append(&[1, 0, 0, 0, 2, 0, 0, 0], 8)?;
assert_eq!((hello, table), (0, 8)); // padded up to the table's alignment
assert_eq!(rodata.align(), 8);
assert_eq!(rodata.size(), 16);

Implementations

impl Section

pub fn new(name: impl Into<String>, kind: SectionKind) -> Self

An empty section of this kind, with the kind’s default flags, alignment 1, address 0, and no relocations.

Examples

use object_lang::{Section, SectionKind};

let text = Section::new(".text", SectionKind::Text);
assert_eq!(text.flags(), SectionKind::Text.default_flags());
assert_eq!((text.align(), text.size()), (1, 0));

pub fn with_flags(self, flags: SectionFlags) -> Self

Replaces the flags. validate checks that the kind allows them.

Examples

use object_lang::{Section, SectionFlags, SectionKind};

let tdata = Section::new(".tdata", SectionKind::Data)
    .with_flags(SectionKind::Data.default_flags() | SectionFlags::TLS);
assert!(tdata.flags().contains(SectionFlags::TLS));

pub fn with_align(self, align: u64) -> Self

Sets the alignment in bytes: a power of two, checked by validate.

Examples

use object_lang::{Section, SectionKind};

assert_eq!(Section::new(".text", SectionKind::Text).with_align(16).align(), 16);

pub fn with_entry_size(self, entry_size: u64) -> Self

Sets the size of each entry, for sections of fixed-size entries such as MERGE sections (zero otherwise).

Examples

use object_lang::{Section, SectionFlags, SectionKind};

let strings = Section::new(".rodata.str1.1", SectionKind::ReadOnlyData)
    .with_flags(SectionFlags::ALLOC | SectionFlags::MERGE | SectionFlags::STRINGS)
    .with_entry_size(1);
assert_eq!(strings.entry_size(), 1);

pub fn with_address(self, address: u64) -> Self

Sets the address: the final load address in an executable.

Examples

use object_lang::{Section, SectionKind};

let text = Section::new(".text", SectionKind::Text).with_address(0x40_1000);
assert_eq!(text.address(), 0x40_1000);

pub fn with_data(self, data: Vec<u8>) -> Self

Replaces the contents with data. Only for kinds that hold bytes; validate refuses data on a Bss section.

Examples

use object_lang::{Section, SectionKind};

let data = Section::new(".data", SectionKind::Data).with_data(vec![1, 2, 3]);
assert_eq!(data.data(), &[1, 2, 3]);

pub fn with_bss_size(self, size: u64) -> Self

Sets the size of a Bss section; validate refuses a size on other kinds, whose size is their data’s length.

Examples

use object_lang::{Section, SectionKind};

let bss = Section::new(".bss", SectionKind::Bss).with_bss_size(4096);
assert_eq!(bss.size(), 4096);
assert!(bss.data().is_empty());

pub fn append(&mut self, bytes: &[u8], align: u64) -> Result<u64, ModelError>

Appends bytes, first padding with zeros to a multiple of align, and returns the offset the bytes start at. Raises the section’s alignment to align if lower.

Errors

• ModelError::InvalidAlignment if align is not a power of two.
• ModelError::AppendToBss if the section is Bss, which holds no bytes; use reserve.
• ModelError::SizeOverflow if the section would outgrow memory.

Examples

use object_lang::{Section, SectionKind};

let mut text = Section::new(".text", SectionKind::Text);
assert_eq!(text.append(&[0x90], 1)?, 0);
assert_eq!(text.append(&[0xc3], 16)?, 16);
assert_eq!(text.size(), 17);

pub fn reserve(&mut self, size: u64, align: u64) -> Result<u64, ModelError>

Reserves size zero bytes at the next multiple of align and returns their offset. A Bss section only grows its size; any other kind appends zero bytes. Raises the section’s alignment to align if lower.

Errors

• ModelError::InvalidAlignment if align is not a power of two.
• ModelError::SizeOverflow if the size would overflow (or, for a section that holds bytes, not fit in memory).

Examples

use object_lang::{Section, SectionKind};

let mut bss = Section::new(".bss", SectionKind::Bss);
assert_eq!(bss.reserve(4, 4)?, 0);
assert_eq!(bss.reserve(8, 8)?, 8);
assert_eq!(bss.size(), 16);

pub fn add_relocation(&mut self, relocation: Relocation)

Adds a relocation that patches this section. Checked by validate.

Examples

use object_lang::{
    Architecture, Object, Relocation, RelocationTarget, Section, SectionKind, Symbol,
    X86_64Reloc,
};

let mut obj = Object::relocatable(Architecture::X86_64);
let target = obj.add_symbol(Symbol::undefined("table"));
let mut data = Section::new(".data", SectionKind::Data).with_data(vec![0; 8]);
data.add_relocation(Relocation::new(0, X86_64Reloc::Abs64, RelocationTarget::Symbol(target), 0));
obj.add_section(data);
assert!(obj.validate().is_ok());

pub fn name(&self) -> &str

The section’s name.

Examples

use object_lang::{Section, SectionKind};

assert_eq!(Section::new(".text", SectionKind::Text).name(), ".text");

pub const fn kind(&self) -> SectionKind

What the section holds.

Examples

use object_lang::{Section, SectionKind};

assert_eq!(Section::new(".bss", SectionKind::Bss).kind(), SectionKind::Bss);

pub const fn flags(&self) -> SectionFlags

The section’s flags.

Examples

use object_lang::{Section, SectionFlags, SectionKind};

assert!(Section::new(".text", SectionKind::Text).flags().contains(SectionFlags::EXEC));

pub const fn align(&self) -> u64

The alignment in bytes.

Examples

use object_lang::{Section, SectionKind};

assert_eq!(Section::new(".data", SectionKind::Data).with_align(8).align(), 8);

pub const fn entry_size(&self) -> u64

The size of each fixed-size entry, or zero.

Examples

use object_lang::{Section, SectionKind};

assert_eq!(Section::new(".data", SectionKind::Data).entry_size(), 0);

pub const fn address(&self) -> u64

The address: the load address in an executable, normally zero in a relocatable object.

Examples

use object_lang::{Section, SectionKind};

assert_eq!(Section::new(".text", SectionKind::Text).address(), 0);

pub fn data(&self) -> &[u8]

The section’s bytes; empty for Bss.

Examples

use object_lang::{Section, SectionKind};

let s = Section::new(".data", SectionKind::Data).with_data(vec![7]);
assert_eq!(s.data(), &[7]);

pub fn size(&self) -> u64

The size in memory: the length of the data, or a Bss section’s reserved size.

Examples

use object_lang::{Section, SectionKind};

assert_eq!(Section::new(".data", SectionKind::Data).with_data(vec![0; 3]).size(), 3);
assert_eq!(Section::new(".bss", SectionKind::Bss).with_bss_size(9).size(), 9);

pub fn relocations(&self) -> &[Relocation]

The relocations that patch this section, in the order added.

Examples

use object_lang::{Section, SectionKind};

assert!(Section::new(".text", SectionKind::Text).relocations().is_empty());

Trait Implementations

impl Clone for Section

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Section

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

Formats the value using the given formatter.

impl Eq for Section

impl PartialEq for Section

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Section