object 0.6.0

A unified interface for the target platform's object file format.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

use {Machine, Symbol};

/// An object file.
pub trait Object<'a>: Sized {
    /// A segment in the object file.
    type Segment: ObjectSegment<'a>;

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

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

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

    /// Parse the raw object file data.
    fn parse(data: &'a [u8]) -> Result<Self, &'static str>;

    /// Get the machine type of the file.
    fn machine(&self) -> Machine;

    /// Get an iterator over the segments in the file.
    // TODO: avoid 'a on self using Associated Type Constructor
    fn segments(&'a self) -> Self::SegmentIterator;

    /// Get the contents of 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.
    /// For example, if ".text" is requested for a Mach-O object file, then the actual
    /// section name that is searched for is "__text".
    ///
    /// For some object files, multiple segments may contain sections with the same
    /// name. In this case, the first matching section will be used.
    fn section_data_by_name(&self, section_name: &str) -> Option<&'a [u8]>;

    /// Get an iterator over the sections in the file.
    // TODO: avoid 'a on self using Associated Type Constructor
    fn sections(&'a self) -> Self::SectionIterator;

    /// Get a `Vec` of the symbols defined in the file.
    /// The symbols are unsorted and have the same order as the symbols in the file.
    fn symbols(&self) -> Vec<Symbol<'a>>;

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

/// 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<'a> {
    /// Returns the virtual address of the segment.
    fn address(&self) -> u64;

    /// Returns the size of the segment in memory.
    fn size(&self) -> 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) -> &'a [u8];

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

/// A section defined in an object file.
pub trait ObjectSection<'a> {
    /// Returns the address of the section.
    fn address(&self) -> u64;

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

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

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

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