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 = 1.0.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 : mod decl_opt;
102 :
103 : #[doc(inline)]
104 : pub use binary::Binary;
105 :
106 : #[doc(inline)]
107 : pub use generic::{Function, Relocation};
108 :
109 : #[doc(inline)]
110 : pub use error::Error;
111 :
112 : #[doc(inline)]
113 : pub use debug_info::DebugInfo;
114 :
115 : #[doc(inline)]
116 : pub use range::Range;
117 :
118 : #[doc(inline)]
119 : pub use debug_location::DebugLocation;
120 :
121 : #[doc(inline)]
122 : pub use decl_opt::DeclOpt;
123 :
124 : pub struct Version {
125 : pub major: u64,
126 : pub minor: u64,
127 : pub patch: u64,
128 : pub id: u64,
129 : }
130 :
131 : impl std::fmt::Display for Version {
132 0 : fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
133 0 : write!(
134 0 : f,
135 0 : "{}.{}.{}.{}",
136 0 : self.major, self.minor, self.patch, self.id
137 0 : )
138 0 : }
139 : }
140 :
141 : /// Whether it is an extended version of LIEF
142 193284 : pub fn is_extended() -> bool {
143 193284 : lief_ffi::is_extended()
144 193284 : }
145 :
146 : /// Return details about the extended version
147 0 : pub fn extended_version_info() -> String {
148 0 : lief_ffi::extended_version_info().to_string()
149 0 : }
150 :
151 : /// Return the extended version
152 0 : pub fn extended_version() -> Version {
153 0 : let ffi_version = lief_ffi::extended_version();
154 0 : Version {
155 0 : major: ffi_version.major,
156 0 : minor: ffi_version.minor,
157 0 : patch: ffi_version.patch,
158 0 : id: ffi_version.id,
159 0 : }
160 0 : }
161 :
162 : /// Return the current version
163 0 : pub fn version() -> Version {
164 0 : let ffi_version = lief_ffi::version();
165 0 : Version {
166 0 : major: ffi_version.major,
167 0 : minor: ffi_version.minor,
168 0 : patch: ffi_version.patch,
169 0 : id: ffi_version.id,
170 0 : }
171 0 : }
172 :
173 : /// Try to demangle the given input.
174 : ///
175 : /// This function requires the extended version of LIEF
176 0 : pub fn demangle(mangled: &str) -> Result<String, Error> {
177 0 : to_conv_result!(lief_ffi::demangle, mangled, |e: cxx::UniquePtr<
178 0 : cxx::String,
179 0 : >| { e.to_string() });
180 0 : }
181 :
182 : /// Hexdump the provided buffer.
183 : ///
184 : /// For instance:
185 : ///
186 : /// ```text
187 : /// +---------------------------------------------------------------------+
188 : /// | 88 56 05 00 00 00 00 00 00 00 00 00 22 58 05 00 | .V.........."X.. |
189 : /// | 10 71 02 00 78 55 05 00 00 00 00 00 00 00 00 00 | .q..xU.......... |
190 : /// | 68 5c 05 00 00 70 02 00 00 00 00 00 00 00 00 00 | h\...p.......... |
191 : /// | 00 00 00 00 00 00 00 00 00 00 00 00 | ............ |
192 : /// +---------------------------------------------------------------------+
193 : /// ```
194 0 : pub fn dump(buffer: &[u8]) -> String {
195 0 : unsafe { lief_ffi::dump(buffer.as_ptr(), buffer.len()).to_string() }
196 0 : }
197 :
198 : /// Same as [`dump`] but with a limit on the number of bytes to dump
199 0 : pub fn dump_with_limit(buffer: &[u8], limit: u64) -> String {
200 0 : unsafe { lief_ffi::dump_with_limit(buffer.as_ptr(), buffer.len(), limit).to_string() }
201 0 : }
|
