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 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270
//! # `findshlibs` //! //! Find the set of shared libraries currently loaded in this process with a //! cross platform API. //! //! The API entry point is the `TargetSharedLibrary` type and its //! `SharedLibrary::each` trait method implementation. //! //! ## Example //! //! Here is an example program that prints out each shared library that is //! loaded in the process and the addresses where each of its segments are //! mapped into memory. //! //! ``` //! extern crate findshlibs; //! use findshlibs::{Segment, SharedLibrary, TargetSharedLibrary}; //! //! fn main() { //! TargetSharedLibrary::each(|shlib| { //! println!("{}", shlib.name().to_string_lossy()); //! //! for seg in shlib.segments() { //! println!(" {}: segment {}", //! seg.actual_virtual_memory_address(shlib), //! seg.name().to_string_lossy()); //! } //! }); //! } //! ``` //! //! ## Supported OSes //! //! These are the OSes that `findshlibs` currently supports: //! //! * Linux //! * macOS //! //! Is your OS missing here? Send us a pull request! //! //! ## Addresses //! //! Shared libraries' addresses can be confusing. They are loaded somewhere in //! physical memory, but we generally don't care about physical memory //! addresses, because only the OS can see that address and in userspace we can //! only access memory through its virtual memory address. But even "virtual //! memory address" is ambiguous because it isn't clear whether this is the //! address before or after the loader maps the shared library into memory and //! performs relocation. //! //! To clarify between these different kinds of addresses, we borrow some //! terminology from [LUL][]: //! //! > * **SVMA** ("Stated Virtual Memory Address"): this is an address of a //! > symbol (etc) as it is stated in the symbol table, or other //! > metadata, of an object. Such values are typically small and //! > start from zero or thereabouts, unless the object has been //! > prelinked. //! > //! > * **AVMA** ("Actual Virtual Memory Address"): this is the address of a //! > symbol (etc) in a running process, that is, once the associated //! > object has been mapped into a process. Such values are typically //! > much larger than SVMAs, since objects can get mapped arbitrarily //! > far along the address space. //! > //! > * **"Bias"**: the difference between AVMA and SVMA for a given symbol //! > (specifically, AVMA - SVMA). The bias is always an integral //! > number of pages. Once we know the bias for a given object's //! > text section (for example), we can compute the AVMAs of all of //! > its text symbols by adding the bias to their SVMAs. //! //! [LUL]: http://searchfox.org/mozilla-central/rev/13148faaa91a1c823a7d68563d9995480e714979/tools/profiler/lul/LulMain.h#17-51 #![deny(missing_docs)] #[macro_use] extern crate cfg_if; #[cfg(target_os = "macos")] #[macro_use] extern crate lazy_static; use std::ffi::CStr; use std::fmt::{self, Debug}; use std::ptr; cfg_if!( if #[cfg(target_os = "linux")] { pub mod linux; /// The [`SharedLibrary` trait](./trait.SharedLibrary.html) /// implementation for the target operating system. pub type TargetSharedLibrary<'a> = linux::SharedLibrary<'a>; } else if #[cfg(target_os = "macos")] { pub mod macos; /// The [`SharedLibrary` trait](./trait.SharedLibrary.html) /// implementation for the target operating system. pub type TargetSharedLibrary<'a> = macos::SharedLibrary<'a>; } else { // No implementation for this platform :( } ); macro_rules! simple_newtypes { ( $( $(#[$attr:meta])* type $name:ident = $oldty:ty where default = $default:expr , display = $format:expr ; )* ) => { $( $(#[$attr])* #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)] pub struct $name(pub $oldty); impl Default for $name { #[inline] fn default() -> Self { $name( $default ) } } impl From<$oldty> for $name { fn from(x: $oldty) -> $name { $name(x) } } impl From<$name> for $oldty { fn from($name(x): $name) -> $oldty { x } } impl fmt::Display for $name { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { write!(f, $format, self.0) } } )* } } simple_newtypes! { /// Stated virtual memory address. /// /// See the module documentation for details. type Svma = *const u8 where default = ptr::null(), display = "{:p}"; /// Actual virtual memory address. /// /// See the module documentation for details. type Avma = *const u8 where default = ptr::null(), display = "{:p}"; /// Virtual memory bias. /// /// See the module documentation for details. type Bias = isize where default = 0, display = "{:#x}"; } /// A mapped segment in a shared library. pub trait Segment: Sized + Debug { /// The associated shared library type for this segment. type SharedLibrary: SharedLibrary<Segment = Self>; /// Get this segment's name. fn name(&self) -> &CStr; /// Get this segment's stated virtual address of this segment. /// /// This is the virtual memory address without the bias applied. See the /// module documentation for details. fn stated_virtual_memory_address(&self) -> Svma; /// Get the length of this segment in memory (in bytes). fn len(&self) -> usize; // Provided methods. /// Get this segment's actual virtual memory address. /// /// This is the virtual memory address with the bias applied. See the module /// documentation for details. #[inline] fn actual_virtual_memory_address(&self, shlib: &Self::SharedLibrary) -> Avma { let svma = self.stated_virtual_memory_address(); let bias = shlib.virtual_memory_bias(); Avma(unsafe { svma.0.offset(bias.0) }) } /// Does this segment contain the given address? #[inline] fn contains_svma(&self, address: Svma) -> bool { let start = self.stated_virtual_memory_address().0 as usize; let end = start + self.len(); let address = address.0 as usize; start <= address && address < end } /// Does this segment contain the given address? #[inline] fn contains_avma(&self, shlib: &Self::SharedLibrary, address: Avma) -> bool { let start = self.actual_virtual_memory_address(shlib).0 as usize; let end = start + self.len(); let address = address.0 as usize; start <= address && address < end } } /// A trait representing a shared library that is loaded in this process. pub trait SharedLibrary: Sized + Debug { /// The associated segment type for this shared library. type Segment: Segment<SharedLibrary = Self>; /// An iterator over a shared library's segments. type SegmentIter: Debug + Iterator<Item = Self::Segment>; /// Get the name of this shared library. fn name(&self) -> &CStr; /// Iterate over this shared library's segments. fn segments(&self) -> Self::SegmentIter; /// Get the bias of this shared library. /// /// See the module documentation for details. fn virtual_memory_bias(&self) -> Bias; /// Find all shared libraries in this process and invoke `f` with each one. fn each<F, C>(f: F) where F: FnMut(&Self) -> C, C: Into<IterationControl>; } /// Control whether iteration over shared libraries should continue or stop. #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum IterationControl { /// Stop iteration. Break, /// Continue iteration. Continue, } impl From<()> for IterationControl { #[inline] fn from(_: ()) -> Self { IterationControl::Continue } }