Line data Source code
1 : //! # LIEF
2 : //!
3 : //! 
4 : //!
5 : //! This package provides Rust bindings for [LIEF](https://lief.re). It exposes most of the
6 : //! LIEF API to **read** these formats:
7 : //! - ELF
8 : //! - PE
9 : //! - Mach-O
10 : //!
11 : //! The bindings require at least Rust version **1.74.0** with the 2021 edition and support:
12 : //! - Windows x86-64 (support `/MT` and `/MD` linking)
13 : //! - Linux x86-64/aarch64/musl (Ubuntu 19.10, Almalinux 8, Debian 10, Fedora 29)
14 : //! - macOS (`x86-64` and `aarch64` with at least OSX Big Sur: 11.0)
15 : //! - iOS (`aarch64`)
16 : //!
17 : //! ## Getting Started
18 : //!
19 : //! ```toml
20 : //! [package]
21 : //! name = "my-awesome-project"
22 : //! version = "0.0.1"
23 : //! edition = "2021"
24 : //!
25 : //! [dependencies]
26 : //! # For nightly
27 : //! lief = { git = "https://github.com/lief-project/LIEF", branch = "main" }
28 : //! # For releases
29 : //! lief = 0.17.0
30 : //! ```
31 : //!
32 : //! ```rust
33 : //! fn main() {
34 : //! let path = std::env::args().last().unwrap();
35 : //! let mut file = std::fs::File::open(path).expect("Can't open the file");
36 : //! match lief::Binary::from(&mut file) {
37 : //! Some(lief::Binary::ELF(elf)) => {
38 : //! // Process ELF file
39 : //! },
40 : //! Some(lief::Binary::PE(pe)) => {
41 : //! // Process PE file
42 : //! },
43 : //! Some(lief::Binary::MachO(macho)) => {
44 : //! // Process Mach-O file (including FatMachO)
45 : //! },
46 : //! Some(lief::Binary::COFF(coff)) => {
47 : //! // Process coff file
48 : //! },
49 : //! None => {
50 : //! // Parsing error
51 : //! }
52 : //! }
53 : //! return;
54 : //! }
55 : //! ```
56 : //!
57 : //! Note that the [`generic`] module implements the different traits shared by different structure
58 : //! of executable formats (symbols, relocations, ...)
59 : //!
60 : //! ## Additional Information
61 : //!
62 : //! For more details about the install procedure and the configuration, please check:
63 : //! <https://lief.re/doc/latest/api/rust/index.html>
64 :
65 : #![doc(html_no_source)]
66 :
67 : pub mod elf;
68 :
69 : /// Executable formats generic traits (LIEF's abstract layer)
70 : pub mod generic;
71 :
72 : pub mod macho;
73 :
74 : pub mod pe;
75 :
76 : pub mod coff;
77 :
78 : pub mod pdb;
79 :
80 : pub mod dwarf;
81 :
82 : pub mod objc;
83 :
84 : pub mod dsc;
85 :
86 : pub mod debug_info;
87 :
88 : pub mod assembly;
89 : mod range;
90 :
91 : /// Module for LIEF's error
92 : pub mod error;
93 :
94 : pub mod logging;
95 :
96 : mod binary;
97 : mod common;
98 :
99 : mod debug_location;
100 :
101 : #[doc(inline)]
102 : pub use binary::Binary;
103 :
104 : #[doc(inline)]
105 : pub use generic::{Relocation, Function};
106 :
107 : #[doc(inline)]
108 : pub use error::Error;
109 :
110 : #[doc(inline)]
111 : pub use debug_info::DebugInfo;
112 :
113 : #[doc(inline)]
114 : pub use range::Range;
115 :
116 : #[doc(inline)]
117 : pub use debug_location::DebugLocation;
118 :
119 : pub struct Version {
120 : pub major: u64,
121 : pub minor: u64,
122 : pub patch: u64,
123 : pub id: u64,
124 : }
125 :
126 : impl std::fmt::Display for Version {
127 0 : fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
128 0 : write!(f, "{}.{}.{}.{}", self.major, self.minor, self.patch, self.id)
129 0 : }
130 : }
131 :
132 : /// Whether it is an extended version of LIEF
133 178416 : pub fn is_extended() -> bool {
134 178416 : lief_ffi::is_extended()
135 178416 : }
136 :
137 : /// Return details about the extended version
138 0 : pub fn extended_version_info() -> String {
139 0 : lief_ffi::extended_version_info().to_string()
140 0 : }
141 :
142 : /// Return the extended version
143 0 : pub fn extended_version() -> Version {
144 0 : let ffi_version = lief_ffi::extended_version();
145 0 : Version {
146 0 : major: ffi_version.major, minor: ffi_version.minor,
147 0 : patch: ffi_version.patch, id: ffi_version.id
148 0 : }
149 0 : }
150 :
151 : /// Return the current version
152 0 : pub fn version() -> Version {
153 0 : let ffi_version = lief_ffi::version();
154 0 : Version {
155 0 : major: ffi_version.major, minor: ffi_version.minor,
156 0 : patch: ffi_version.patch, id: ffi_version.id
157 0 : }
158 0 : }
159 :
160 : /// Try to demangle the given input.
161 : ///
162 : /// This function requires the extended version of LIEF
163 0 : pub fn demangle(mangled: &str) -> Result<String, Error> {
164 0 : to_conv_result!(
165 : lief_ffi::demangle,
166 : *mangled,
167 0 : |e: cxx::UniquePtr<cxx::String>| { e.to_string() }
168 : );
169 0 : }
170 :
171 : /// Hexdump the provided buffer.
172 : ///
173 : /// For instance:
174 : ///
175 : /// ```text
176 : /// +---------------------------------------------------------------------+
177 : /// | 88 56 05 00 00 00 00 00 00 00 00 00 22 58 05 00 | .V.........."X.. |
178 : /// | 10 71 02 00 78 55 05 00 00 00 00 00 00 00 00 00 | .q..xU.......... |
179 : /// | 68 5c 05 00 00 70 02 00 00 00 00 00 00 00 00 00 | h\...p.......... |
180 : /// | 00 00 00 00 00 00 00 00 00 00 00 00 | ............ |
181 : /// +---------------------------------------------------------------------+
182 : /// ```
183 0 : pub fn dump(buffer: &[u8]) -> String {
184 0 : unsafe {
185 0 : lief_ffi::dump(buffer.as_ptr(), buffer.len()).to_string()
186 0 : }
187 0 : }
188 :
189 : /// Same as [`dump`] but with a limit on the number of bytes to dump
190 0 : pub fn dump_with_limit(buffer: &[u8], limit: u64) -> String {
191 0 : unsafe {
192 0 : lief_ffi::dump_with_limit(buffer.as_ptr(), buffer.len(), limit).to_string()
193 0 : }
194 0 : }
|
