Struct Symbol 

#[non_exhaustive]
pub struct Symbol {
    pub name: String,
    pub kind: SymbolKind,
    pub binding: Binding,
    pub visibility: Visibility,
    pub section: SymbolSection,
    pub value: u64,
    pub size: u64,
}

One symbol: a name, what it names, where it is defined, and who can see it.

value is an offset within the symbol’s section in a relocatable object, and an address in an executable. For a Common symbol it is the required alignment. size is the size in bytes of what the symbol names, or zero when unknown.

The fields are public; the constructors cover the common shapes. The struct is #[non_exhaustive], so build one with a constructor and adjust fields or chain the with_* methods.

Examples

use object_lang::{
    Architecture, Binding, Object, Section, SectionKind, Symbol, SymbolKind, Visibility,
};

let mut obj = Object::relocatable(Architecture::X86_64);
let text = obj.add_section(Section::new(".text", SectionKind::Text).with_data(vec![0xc3; 8]));
let helper = Symbol::function("helper", text, 4, 4)
    .with_binding(Binding::Local);
let api = Symbol::function("api", text, 0, 4).with_visibility(Visibility::Protected);
obj.add_symbol(helper);
obj.add_symbol(api);
assert!(obj.validate().is_ok());
assert_eq!(obj.symbols()[0].kind, SymbolKind::Function);

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: String

The symbol’s name. Must not contain a NUL byte.

kind: SymbolKind

What the symbol names.

binding: Binding

Who can see the symbol.

visibility: Visibility

How far a non-local symbol is exported.

section: SymbolSection

Where the symbol is defined.

value: u64

The offset in the section (relocatable), the address (executable), or the alignment (Common).

size: u64

The size in bytes of what the symbol names, or zero.

Implementations

impl Symbol

pub fn new( name: impl Into<String>, kind: SymbolKind, binding: Binding, section: SymbolSection, value: u64, size: u64, ) -> Self

A symbol with every property given; the other constructors are shorthands. Visibility is Default.

Examples

use object_lang::{Binding, Symbol, SymbolKind, SymbolSection};

let sym = Symbol::new("x", SymbolKind::Data, Binding::Weak, SymbolSection::Undefined, 0, 0);
assert_eq!(sym.binding, Binding::Weak);

pub fn function( name: impl Into<String>, section: SectionId, value: u64, size: u64, ) -> Self

A global function defined at value in section, size bytes long.

Examples

use object_lang::{Architecture, Object, Section, SectionKind, Symbol, SymbolKind};

let mut obj = Object::relocatable(Architecture::X86_64);
let text = obj.add_section(Section::new(".text", SectionKind::Text).with_data(vec![0xc3]));
let main = Symbol::function("main", text, 0, 1);
assert_eq!(main.kind, SymbolKind::Function);

pub fn data( name: impl Into<String>, section: SectionId, value: u64, size: u64, ) -> Self

A global data object defined at value in section, size bytes long.

Examples

use object_lang::{Architecture, Object, Section, SectionKind, Symbol, SymbolKind};

let mut obj = Object::relocatable(Architecture::X86_64);
let data = obj.add_section(Section::new(".data", SectionKind::Data).with_data(vec![0; 4]));
assert_eq!(Symbol::data("counter", data, 0, 4).kind, SymbolKind::Data);

pub fn undefined(name: impl Into<String>) -> Self

A global reference to a symbol another object defines.

Examples

use object_lang::{Symbol, SymbolSection};

assert_eq!(Symbol::undefined("malloc").section, SymbolSection::Undefined);

pub fn absolute(name: impl Into<String>, value: u64) -> Self

A global constant value that relocation does not change.

Examples

use object_lang::Symbol;

assert_eq!(Symbol::absolute("STACK_SIZE", 0x10_0000).value, 0x10_0000);

pub fn common(name: impl Into<String>, size: u64, align: u64) -> Self

A global common data symbol of size bytes aligned to align (a power of two).

Examples

use object_lang::{Symbol, SymbolSection};

let buffer = Symbol::common("buffer", 256, 16);
assert_eq!((buffer.section, buffer.value, buffer.size), (SymbolSection::Common, 16, 256));

pub fn file(name: impl Into<String>) -> Self

A File symbol naming the source file.

Examples

use object_lang::{Binding, Symbol, SymbolKind};

let file = Symbol::file("main.rs");
assert_eq!((file.kind, file.binding), (SymbolKind::File, Binding::Local));

pub fn with_binding(self, binding: Binding) -> Self

self with a different binding.

Examples

use object_lang::{Binding, Symbol};

assert_eq!(Symbol::undefined("f").with_binding(Binding::Weak).binding, Binding::Weak);

pub fn with_visibility(self, visibility: Visibility) -> Self

self with a different visibility.

Examples

use object_lang::{Symbol, Visibility};

let s = Symbol::undefined("f").with_visibility(Visibility::Hidden);
assert_eq!(s.visibility, Visibility::Hidden);

pub fn with_kind(self, kind: SymbolKind) -> Self

self with a different kind.

Examples

use object_lang::{Symbol, SymbolKind};

assert_eq!(Symbol::undefined("f").with_kind(SymbolKind::Function).kind, SymbolKind::Function);

Trait Implementations

impl Clone for Symbol

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 Symbol

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

Formats the value using the given formatter.

impl Eq for Symbol

impl Hash for Symbol

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Symbol

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Symbol