1 // A hack for docs.rs to build documentation that has both windows and linux documentation in the 2 // same rustdoc build visible. 3 #[cfg(all(docsrs, not(unix)))] 4 mod unix_imports { 5 } 6 #[cfg(any(not(docsrs), unix))] 7 mod unix_imports { 8 pub(super) use std::os::unix::ffi::OsStrExt; 9 } 10 11 use self::unix_imports::*; 12 use util::{ensure_compatible_types, cstr_cow_from_bytes}; 13 use std::ffi::{CStr, OsStr}; 14 use std::{fmt, marker, mem, ptr}; 15 use std::os::raw; 16 pub use self::consts::*; 17 18 mod consts; 19 20 // dl* family of functions did not have enough thought put into it. 21 // 22 // Whole error handling scheme is done via setting and querying some global state, therefore it is 23 // not safe to use dynamic library loading in MT-capable environment at all. Only in POSIX 2008+TC1 24 // a thread-local state was allowed for `dlerror`, making the dl* family of functions MT-safe. 25 // 26 // In practice (as of 2020-04-01) most of the widely used targets use a thread-local for error 27 // state and have been doing so for a long time. Regardless the comments in this function shall 28 // remain as a documentation for the future generations. 29 fn with_dlerror<T, F>(wrap: fn(crate::error::DlDescription) -> crate::Error, closure: F) 30 -> Result<T, Option<crate::Error>> 31 where F: FnOnce() -> Option<T> { 32 // We used to guard all uses of dl* functions with our own mutex. This made them safe to use in 33 // MT programs provided the only way a program used dl* was via this library. However, it also 34 // had a number of downsides or cases where it failed to handle the problems. For instance, 35 // if any other library called `dlerror` internally concurrently with `libloading` things would 36 // still go awry. 37 // 38 // On platforms where `dlerror` is still MT-unsafe, `dlsym` (`Library::get`) can spuriously 39 // succeed and return a null pointer for a symbol when the actual symbol look-up operation 40 // fails. Instances where the actual symbol _could_ be `NULL` are platform specific. For 41 // instance on GNU glibc based-systems (an excerpt from dlsym(3)): 42 // 43 // > The value of a symbol returned by dlsym() will never be NULL if the shared object is the 44 // > result of normal compilation, since a global symbol is never placed at the NULL 45 // > address. There are nevertheless cases where a lookup using dlsym() may return NULL as the 46 // > value of a symbol. For example, the symbol value may be the result of a GNU indirect 47 // > function (IFUNC) resolver function that returns NULL as the resolved value. 48 49 // While we could could call `dlerror` here to clear the previous error value, only the `dlsym` 50 // call depends on it being cleared beforehand and only in some cases too. We will instead 51 // clear the error inside the dlsym binding instead. 52 // 53 // In all the other cases, clearing the error here will only be hiding misuse of these bindings 54 // or a bug in implementation of dl* family of functions. 55 closure().ok_or_else(|| unsafe { 56 // This code will only get executed if the `closure` returns `None`. 57 let error = dlerror(); 58 if error.is_null() { 59 // In non-dlsym case this may happen when there’re bugs in our bindings or there’s 60 // non-libloading user of libdl; possibly in another thread. 61 None 62 } else { 63 // You can’t even rely on error string being static here; call to subsequent dlerror 64 // may invalidate or overwrite the error message. Why couldn’t they simply give up the 65 // ownership over the message? 66 // TODO: should do locale-aware conversion here. OTOH Rust doesn’t seem to work well in 67 // any system that uses non-utf8 locale, so I doubt there’s a problem here. 68 let message = CStr::from_ptr(error).into(); 69 Some(wrap(crate::error::DlDescription(message))) 70 // Since we do a copy of the error string above, maybe we should call dlerror again to 71 // let libdl know it may free its copy of the string now? 72 } 73 }) 74 } 75 76 /// A platform-specific counterpart of the cross-platform [`Library`](crate::Library). 77 pub struct Library { 78 handle: *mut raw::c_void 79 } 80 81 unsafe impl Send for Library {} 82 83 // That being said... this section in the volume 2 of POSIX.1-2008 states: 84 // 85 // > All functions defined by this volume of POSIX.1-2008 shall be thread-safe, except that the 86 // > following functions need not be thread-safe. 87 // 88 // With notable absence of any dl* function other than dlerror in the list. By “this volume” 89 // I suppose they refer precisely to the “volume 2”. dl* family of functions are specified 90 // by this same volume, so the conclusion is indeed that dl* functions are required by POSIX 91 // to be thread-safe. Great! 92 // 93 // See for more details: 94 // 95 // * https://github.com/nagisa/rust_libloading/pull/17 96 // * http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_09_01 97 unsafe impl Sync for Library {} 98 99 impl Library { 100 /// Find and eagerly load a shared library (module). 101 /// 102 /// If the `filename` contains a [path separator], the `filename` is interpreted as a `path` to 103 /// a file. Otherwise, platform-specific algorithms are employed to find a library with a 104 /// matching file name. 105 /// 106 /// This is equivalent to <code>[Library::open](filename, [RTLD_LAZY] | [RTLD_LOCAL])</code>. 107 /// 108 /// [path separator]: std::path::MAIN_SEPARATOR 109 /// 110 /// # Safety 111 /// 112 /// When a library is loaded initialization routines contained within the library are executed. 113 /// For the purposes of safety, execution of these routines is conceptually the same calling an 114 /// unknown foreign function and may impose arbitrary requirements on the caller for the call 115 /// to be sound. 116 /// 117 /// Additionally, the callers of this function must also ensure that execution of the 118 /// termination routines contained within the library is safe as well. These routines may be 119 /// executed when the library is unloaded. 120 #[inline] 121 pub unsafe fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, crate::Error> { 122 Library::open(Some(filename), RTLD_LAZY | RTLD_LOCAL) 123 } 124 125 /// Load the `Library` representing the current executable. 126 /// 127 /// [`Library::get`] calls of the returned `Library` will look for symbols in following 128 /// locations in order: 129 /// 130 /// 1. Original program image; 131 /// 2. Any executable object files (e.g. shared libraries) loaded at program startup; 132 /// 3. Executable object files loaded at runtime (e.g. via other `Library::new` calls or via 133 /// calls to the `dlopen` function) 134 /// 135 /// Note that behaviour of `Library` loaded with this method is different from 136 /// Libraries loaded with [`os::windows::Library::this`]. 137 /// 138 /// This is equivalent to <code>[Library::open](None, [RTLD_LAZY] | [RTLD_LOCAL])</code>. 139 /// 140 /// [`os::windows::Library::this`]: crate::os::windows::Library::this 141 #[inline] 142 pub fn this() -> Library { 143 unsafe { 144 // SAFE: this does not load any new shared library images, no danger in it executing 145 // initializer routines. 146 Library::open(None::<&OsStr>, RTLD_LAZY | RTLD_LOCAL).expect("this should never fail") 147 } 148 } 149 150 /// Find and load an executable object file (shared library). 151 /// 152 /// See documentation for [`Library::this`] for further description of behaviour 153 /// when the `filename` is `None`. Otherwise see [`Library::new`]. 154 /// 155 /// Corresponds to `dlopen(filename, flags)`. 156 /// 157 /// # Safety 158 /// 159 /// When a library is loaded initialization routines contained within the library are executed. 160 /// For the purposes of safety, execution of these routines is conceptually the same calling an 161 /// unknown foreign function and may impose arbitrary requirements on the caller for the call 162 /// to be sound. 163 /// 164 /// Additionally, the callers of this function must also ensure that execution of the 165 /// termination routines contained within the library is safe as well. These routines may be 166 /// executed when the library is unloaded. 167 pub unsafe fn open<P>(filename: Option<P>, flags: raw::c_int) -> Result<Library, crate::Error> 168 where P: AsRef<OsStr> { 169 let filename = match filename { 170 None => None, 171 Some(ref f) => Some(cstr_cow_from_bytes(f.as_ref().as_bytes())?), 172 }; 173 with_dlerror(|desc| crate::Error::DlOpen { desc }, move || { 174 let result = dlopen(match filename { 175 None => ptr::null(), 176 Some(ref f) => f.as_ptr() 177 }, flags); 178 // ensure filename lives until dlopen completes 179 drop(filename); 180 if result.is_null() { 181 None 182 } else { 183 Some(Library { 184 handle: result 185 }) 186 } 187 }).map_err(|e| e.unwrap_or(crate::Error::DlOpenUnknown)) 188 } 189 190 unsafe fn get_impl<T, F>(&self, symbol: &[u8], on_null: F) -> Result<Symbol<T>, crate::Error> 191 where F: FnOnce() -> Result<Symbol<T>, crate::Error> 192 { 193 ensure_compatible_types::<T, *mut raw::c_void>()?; 194 let symbol = cstr_cow_from_bytes(symbol)?; 195 // `dlsym` may return nullptr in two cases: when a symbol genuinely points to a null 196 // pointer or the symbol cannot be found. In order to detect this case a double dlerror 197 // pattern must be used, which is, sadly, a little bit racy. 198 // 199 // We try to leave as little space as possible for this to occur, but we can’t exactly 200 // fully prevent it. 201 match with_dlerror(|desc| crate::Error::DlSym { desc }, || { 202 dlerror(); 203 let symbol = dlsym(self.handle, symbol.as_ptr()); 204 if symbol.is_null() { 205 None 206 } else { 207 Some(Symbol { 208 pointer: symbol, 209 pd: marker::PhantomData 210 }) 211 } 212 }) { 213 Err(None) => on_null(), 214 Err(Some(e)) => Err(e), 215 Ok(x) => Ok(x) 216 } 217 218 } 219 220 /// Get a pointer to function or static variable by symbol name. 221 /// 222 /// The `symbol` may not contain any null bytes, with an exception of last byte. Providing a 223 /// null terminated `symbol` may help to avoid an allocation. 224 /// 225 /// Symbol is interpreted as-is; no mangling is done. This means that symbols like `x::y` are 226 /// most likely invalid. 227 /// 228 /// # Safety 229 /// 230 /// Users of this API must specify the correct type of the function or variable loaded. Using a 231 /// `Symbol` with a wrong type is undefined. 232 /// 233 /// # Platform-specific behaviour 234 /// 235 /// Implementation of thread local variables is extremely platform specific and uses of such 236 /// variables that work on e.g. Linux may have unintended behaviour on other targets. 237 /// 238 /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe (such 239 /// as FreeBSD), this function will unconditionally return an error when the underlying `dlsym` 240 /// call returns a null pointer. There are rare situations where `dlsym` returns a genuine null 241 /// pointer without it being an error. If loading a null pointer is something you care about, 242 /// consider using the [`Library::get_singlethreaded`] call. 243 #[inline(always)] 244 pub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error> { 245 extern crate cfg_if; 246 cfg_if::cfg_if! { 247 // These targets are known to have MT-safe `dlerror`. 248 if #[cfg(any( 249 target_os = "linux", 250 target_os = "android", 251 target_os = "openbsd", 252 target_os = "macos", 253 target_os = "ios", 254 target_os = "solaris", 255 target_os = "illumos", 256 target_os = "redox", 257 target_os = "fuchsia" 258 ))] { 259 self.get_singlethreaded(symbol) 260 } else { 261 self.get_impl(symbol, || Err(crate::Error::DlSymUnknown)) 262 } 263 } 264 } 265 266 /// Get a pointer to function or static variable by symbol name. 267 /// 268 /// The `symbol` may not contain any null bytes, with an exception of last byte. Providing a 269 /// null terminated `symbol` may help to avoid an allocation. 270 /// 271 /// Symbol is interpreted as-is; no mangling is done. This means that symbols like `x::y` are 272 /// most likely invalid. 273 /// 274 /// # Safety 275 /// 276 /// Users of this API must specify the correct type of the function or variable loaded. Using a 277 /// `Symbol` with a wrong type is undefined. 278 /// 279 /// It is up to the user of this library to ensure that no other calls to an MT-unsafe 280 /// implementation of `dlerror` occur during execution of this function. Failing that, the 281 /// behaviour of this function is not defined. 282 /// 283 /// # Platform-specific behaviour 284 /// 285 /// Implementation of thread local variables is extremely platform specific and uses of such 286 /// variables that work on e.g. Linux may have unintended behaviour on other targets. 287 #[inline(always)] 288 pub unsafe fn get_singlethreaded<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error> { 289 self.get_impl(symbol, || Ok(Symbol { 290 pointer: ptr::null_mut(), 291 pd: marker::PhantomData 292 })) 293 } 294 295 /// Convert the `Library` to a raw handle. 296 /// 297 /// The handle returned by this function shall be usable with APIs which accept handles 298 /// as returned by `dlopen`. 299 pub fn into_raw(self) -> *mut raw::c_void { 300 let handle = self.handle; 301 mem::forget(self); 302 handle 303 } 304 305 /// Convert a raw handle returned by `dlopen`-family of calls to a `Library`. 306 /// 307 /// # Safety 308 /// 309 /// The pointer shall be a result of a successful call of the `dlopen`-family of functions or a 310 /// pointer previously returned by `Library::into_raw` call. It must be valid to call `dlclose` 311 /// with this pointer as an argument. 312 pub unsafe fn from_raw(handle: *mut raw::c_void) -> Library { 313 Library { 314 handle 315 } 316 } 317 318 /// Unload the library. 319 /// 320 /// This method might be a no-op, depending on the flags with which the `Library` was opened, 321 /// what library was opened or other platform specifics. 322 /// 323 /// You only need to call this if you are interested in handling any errors that may arise when 324 /// library is unloaded. Otherwise the implementation of `Drop` for `Library` will close the 325 /// library and ignore the errors were they arise. 326 /// 327 /// The underlying data structures may still get leaked if an error does occur. 328 pub fn close(self) -> Result<(), crate::Error> { 329 let result = with_dlerror(|desc| crate::Error::DlClose { desc }, || { 330 if unsafe { dlclose(self.handle) } == 0 { 331 Some(()) 332 } else { 333 None 334 } 335 }).map_err(|e| e.unwrap_or(crate::Error::DlCloseUnknown)); 336 // While the library is not free'd yet in case of an error, there is no reason to try 337 // dropping it again, because all that will do is try calling `dlclose` again. only 338 // this time it would ignore the return result, which we already seen failing… 339 std::mem::forget(self); 340 result 341 } 342 } 343 344 impl Drop for Library { 345 fn drop(&mut self) { 346 unsafe { 347 dlclose(self.handle); 348 } 349 } 350 } 351 352 impl fmt::Debug for Library { 353 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 354 f.write_str(&format!("Library@{:p}", self.handle)) 355 } 356 } 357 358 /// Symbol from a library. 359 /// 360 /// A major difference compared to the cross-platform `Symbol` is that this does not ensure the 361 /// `Symbol` does not outlive `Library` it comes from. 362 pub struct Symbol<T> { 363 pointer: *mut raw::c_void, 364 pd: marker::PhantomData<T> 365 } 366 367 impl<T> Symbol<T> { 368 /// Convert the loaded Symbol into a raw pointer. 369 pub fn into_raw(self) -> *mut raw::c_void { 370 let pointer = self.pointer; 371 mem::forget(self); 372 pointer 373 } 374 } 375 376 impl<T> Symbol<Option<T>> { 377 /// Lift Option out of the symbol. 378 pub fn lift_option(self) -> Option<Symbol<T>> { 379 if self.pointer.is_null() { 380 None 381 } else { 382 Some(Symbol { 383 pointer: self.pointer, 384 pd: marker::PhantomData, 385 }) 386 } 387 } 388 } 389 390 unsafe impl<T: Send> Send for Symbol<T> {} 391 unsafe impl<T: Sync> Sync for Symbol<T> {} 392 393 impl<T> Clone for Symbol<T> { 394 fn clone(&self) -> Symbol<T> { 395 Symbol { ..*self } 396 } 397 } 398 399 impl<T> ::std::ops::Deref for Symbol<T> { 400 type Target = T; 401 fn deref(&self) -> &T { 402 unsafe { 403 // Additional reference level for a dereference on `deref` return value. 404 &*(&self.pointer as *const *mut _ as *const T) 405 } 406 } 407 } 408 409 impl<T> fmt::Debug for Symbol<T> { 410 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { 411 unsafe { 412 let mut info = mem::MaybeUninit::<DlInfo>::uninit(); 413 if dladdr(self.pointer, info.as_mut_ptr()) != 0 { 414 let info = info.assume_init(); 415 if info.dli_sname.is_null() { 416 f.write_str(&format!("Symbol@{:p} from {:?}", 417 self.pointer, 418 CStr::from_ptr(info.dli_fname))) 419 } else { 420 f.write_str(&format!("Symbol {:?}@{:p} from {:?}", 421 CStr::from_ptr(info.dli_sname), self.pointer, 422 CStr::from_ptr(info.dli_fname))) 423 } 424 } else { 425 f.write_str(&format!("Symbol@{:p}", self.pointer)) 426 } 427 } 428 } 429 } 430 431 // Platform specific things 432 #[cfg_attr(any(target_os = "linux", target_os = "android"), link(name="dl"))] 433 #[cfg_attr(any(target_os = "freebsd", target_os = "dragonfly"), link(name="c"))] 434 extern { 435 fn dlopen(filename: *const raw::c_char, flags: raw::c_int) -> *mut raw::c_void; 436 fn dlclose(handle: *mut raw::c_void) -> raw::c_int; 437 fn dlsym(handle: *mut raw::c_void, symbol: *const raw::c_char) -> *mut raw::c_void; 438 fn dlerror() -> *mut raw::c_char; 439 fn dladdr(addr: *mut raw::c_void, info: *mut DlInfo) -> raw::c_int; 440 } 441 442 #[repr(C)] 443 struct DlInfo { 444 dli_fname: *const raw::c_char, 445 dli_fbase: *mut raw::c_void, 446 dli_sname: *const raw::c_char, 447 dli_saddr: *mut raw::c_void 448 } 449