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::{Relocation, Function};
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!(f, "{}.{}.{}.{}", self.major, self.minor, self.patch, self.id)
134 0 : }
135 : }
136 :
137 : /// Whether it is an extended version of LIEF
138 178416 : pub fn is_extended() -> bool {
139 178416 : lief_ffi::is_extended()
140 178416 : }
141 :
142 : /// Return details about the extended version
143 0 : pub fn extended_version_info() -> String {
144 0 : lief_ffi::extended_version_info().to_string()
145 0 : }
146 :
147 : /// Return the extended version
148 0 : pub fn extended_version() -> Version {
149 0 : let ffi_version = lief_ffi::extended_version();
150 0 : Version {
151 0 : major: ffi_version.major, minor: ffi_version.minor,
152 0 : patch: ffi_version.patch, id: ffi_version.id
153 0 : }
154 0 : }
155 :
156 : /// Return the current version
157 0 : pub fn version() -> Version {
158 0 : let ffi_version = lief_ffi::version();
159 0 : Version {
160 0 : major: ffi_version.major, minor: ffi_version.minor,
161 0 : patch: ffi_version.patch, id: ffi_version.id
162 0 : }
163 0 : }
164 :
165 : /// Try to demangle the given input.
166 : ///
167 : /// This function requires the extended version of LIEF
168 : pub fn demangle(mangled: &str) -> Result<String, Error> {
169 : to_conv_result!(
170 : lief_ffi::demangle,
171 : *mangled,
172 0 : |e: cxx::UniquePtr<cxx::String>| { e.to_string() }
173 : );
174 0 : }
175 :
176 : /// Hexdump the provided buffer.
177 : ///
178 : /// For instance:
179 : ///
180 : /// ```text
181 : /// +---------------------------------------------------------------------+
182 : /// | 88 56 05 00 00 00 00 00 00 00 00 00 22 58 05 00 | .V.........."X.. |
183 : /// | 10 71 02 00 78 55 05 00 00 00 00 00 00 00 00 00 | .q..xU.......... |
184 : /// | 68 5c 05 00 00 70 02 00 00 00 00 00 00 00 00 00 | h\...p.......... |
185 : /// | 00 00 00 00 00 00 00 00 00 00 00 00 | ............ |
186 : /// +---------------------------------------------------------------------+
187 : /// ```
188 0 : pub fn dump(buffer: &[u8]) -> String {
189 0 : unsafe {
190 0 : lief_ffi::dump(buffer.as_ptr(), buffer.len()).to_string()
191 0 : }
192 0 : }
193 :
194 : /// Same as [`dump`] but with a limit on the number of bytes to dump
195 0 : pub fn dump_with_limit(buffer: &[u8], limit: u64) -> String {
196 0 : unsafe {
197 0 : lief_ffi::dump_with_limit(buffer.as_ptr(), buffer.len(), limit).to_string()
198 0 : }
199 0 : }
|
