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 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484
// A hack for docs.rs to build documentation that has both windows and linux documentation in the
// same rustdoc build visible.
#[cfg(all(libloading_docs, not(unix)))]
mod unix_imports {}
#[cfg(any(not(libloading_docs), unix))]
mod unix_imports {
pub(super) use std::os::unix::ffi::OsStrExt;
}
pub use self::consts::*;
use self::unix_imports::*;
use std::ffi::{CStr, OsStr};
use std::os::raw;
use std::{fmt, marker, mem, ptr};
use util::{cstr_cow_from_bytes, ensure_compatible_types};
mod consts;
/// Run code and handle errors reported by `dlerror`.
///
/// This function first executes the `closure` function containing calls to the functions that
/// report their errors via `dlerror`. This closure may return either `None` or `Some(*)` to
/// further affect operation of this function.
///
/// In case the `closure` returns `None`, `with_dlerror` inspects the `dlerror`. `dlerror` may
/// decide to not provide any error description, in which case `Err(None)` is returned to the
/// caller. Otherwise the `error` callback is invoked to allow inspection and conversion of the
/// error message. The conversion result is returned as `Err(Some(Error))`.
///
/// If the operations that report their errors via `dlerror` were all successful, `closure` should
/// return `Some(T)` instead. In this case `dlerror` is not inspected at all.
///
/// # Notes
///
/// The whole `dlerror` handling scheme is done via setting and querying some global state. For
/// that reason it is not safe to use dynamic library loading in MT-capable environment at all.
/// Only in POSIX 2008+TC1 a thread-local state was allowed for `dlerror`, making the dl* family of
/// functions possibly MT-safe, depending on the implementation of `dlerror`.
///
/// In practice (as of 2020-04-01) most of the widely used targets use a thread-local for error
/// state and have been doing so for a long time.
pub fn with_dlerror<T, F, Error>(closure: F, error: fn(&CStr) -> Error) -> Result<T, Option<Error>>
where
F: FnOnce() -> Option<T>,
{
// We used to guard all uses of dl* functions with our own mutex. This made them safe to use in
// MT programs provided the only way a program used dl* was via this library. However, it also
// had a number of downsides or cases where it failed to handle the problems. For instance,
// if any other library called `dlerror` internally concurrently with `libloading` things would
// still go awry.
//
// On platforms where `dlerror` is still MT-unsafe, `dlsym` (`Library::get`) can spuriously
// succeed and return a null pointer for a symbol when the actual symbol look-up operation
// fails. Instances where the actual symbol _could_ be `NULL` are platform specific. For
// instance on GNU glibc based-systems (an excerpt from dlsym(3)):
//
// > The value of a symbol returned by dlsym() will never be NULL if the shared object is the
// > result of normal compilation, since a global symbol is never placed at the NULL
// > address. There are nevertheless cases where a lookup using dlsym() may return NULL as the
// > value of a symbol. For example, the symbol value may be the result of a GNU indirect
// > function (IFUNC) resolver function that returns NULL as the resolved value.
// While we could could call `dlerror` here to clear the previous error value, only the `dlsym`
// call depends on it being cleared beforehand and only in some cases too. We will instead
// clear the error inside the dlsym binding instead.
//
// In all the other cases, clearing the error here will only be hiding misuse of these bindings
// or a bug in implementation of dl* family of functions.
closure().ok_or_else(|| unsafe {
// This code will only get executed if the `closure` returns `None`.
let dlerror_str = dlerror();
if dlerror_str.is_null() {
// In non-dlsym case this may happen when there’re bugs in our bindings or there’s
// non-libloading user of libdl; possibly in another thread.
None
} else {
// You can’t even rely on error string being static here; call to subsequent dlerror
// may invalidate or overwrite the error message. Why couldn’t they simply give up the
// ownership over the message?
// TODO: should do locale-aware conversion here. OTOH Rust doesn’t seem to work well in
// any system that uses non-utf8 locale, so I doubt there’s a problem here.
Some(error(CStr::from_ptr(dlerror_str)))
// Since we do a copy of the error string above, maybe we should call dlerror again to
// let libdl know it may free its copy of the string now?
}
})
}
/// A platform-specific counterpart of the cross-platform [`Library`](crate::Library).
pub struct Library {
handle: *mut raw::c_void,
}
unsafe impl Send for Library {}
// That being said... this section in the volume 2 of POSIX.1-2008 states:
//
// > All functions defined by this volume of POSIX.1-2008 shall be thread-safe, except that the
// > following functions need not be thread-safe.
//
// With notable absence of any dl* function other than dlerror in the list. By “this volume”
// I suppose they refer precisely to the “volume 2”. dl* family of functions are specified
// by this same volume, so the conclusion is indeed that dl* functions are required by POSIX
// to be thread-safe. Great!
//
// See for more details:
//
// * https://github.com/nagisa/rust_libloading/pull/17
// * http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_09_01
unsafe impl Sync for Library {}
impl Library {
/// Find and eagerly load a shared library (module).
///
/// If the `filename` contains a [path separator], the `filename` is interpreted as a `path` to
/// a file. Otherwise, platform-specific algorithms are employed to find a library with a
/// matching file name.
///
/// This is equivalent to <code>[Library::open](filename, [RTLD_LAZY] | [RTLD_LOCAL])</code>.
///
/// [path separator]: std::path::MAIN_SEPARATOR
///
/// # Safety
///
/// When a library is loaded, initialisation routines contained within the library are executed.
/// For the purposes of safety, the execution of these routines is conceptually the same calling an
/// unknown foreign function and may impose arbitrary requirements on the caller for the call
/// to be sound.
///
/// Additionally, the callers of this function must also ensure that execution of the
/// termination routines contained within the library is safe as well. These routines may be
/// executed when the library is unloaded.
#[inline]
pub unsafe fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, crate::Error> {
Library::open(Some(filename), RTLD_LAZY | RTLD_LOCAL)
}
/// Load the `Library` representing the current executable.
///
/// [`Library::get`] calls of the returned `Library` will look for symbols in following
/// locations in order:
///
/// 1. The original program image;
/// 2. Any executable object files (e.g. shared libraries) loaded at program startup;
/// 3. Any executable object files loaded at runtime (e.g. via other `Library::new` calls or via
/// calls to the `dlopen` function).
///
/// Note that the behaviour of a `Library` loaded with this method is different from that of
/// Libraries loaded with [`os::windows::Library::this`].
///
/// This is equivalent to <code>[Library::open](None, [RTLD_LAZY] | [RTLD_LOCAL])</code>.
///
/// [`os::windows::Library::this`]: crate::os::windows::Library::this
#[inline]
pub fn this() -> Library {
unsafe {
// SAFE: this does not load any new shared library images, no danger in it executing
// initialiser routines.
Library::open(None::<&OsStr>, RTLD_LAZY | RTLD_LOCAL).expect("this should never fail")
}
}
/// Find and load an executable object file (shared library).
///
/// See documentation for [`Library::this`] for further description of the behaviour
/// when the `filename` is `None`. Otherwise see [`Library::new`].
///
/// Corresponds to `dlopen(filename, flags)`.
///
/// # Safety
///
/// When a library is loaded, initialisation routines contained within the library are executed.
/// For the purposes of safety, the execution of these routines is conceptually the same calling an
/// unknown foreign function and may impose arbitrary requirements on the caller for the call
/// to be sound.
///
/// Additionally, the callers of this function must also ensure that execution of the
/// termination routines contained within the library is safe as well. These routines may be
/// executed when the library is unloaded.
pub unsafe fn open<P>(filename: Option<P>, flags: raw::c_int) -> Result<Library, crate::Error>
where
P: AsRef<OsStr>,
{
let filename = match filename {
None => None,
Some(ref f) => Some(cstr_cow_from_bytes(f.as_ref().as_bytes())?),
};
with_dlerror(
move || {
let result = dlopen(
match filename {
None => ptr::null(),
Some(ref f) => f.as_ptr(),
},
flags,
);
// ensure filename lives until dlopen completes
drop(filename);
if result.is_null() {
None
} else {
Some(Library { handle: result })
}
},
|desc| crate::Error::DlOpen { desc: desc.into() },
)
.map_err(|e| e.unwrap_or(crate::Error::DlOpenUnknown))
}
unsafe fn get_impl<T, F>(&self, symbol: &[u8], on_null: F) -> Result<Symbol<T>, crate::Error>
where
F: FnOnce() -> Result<Symbol<T>, crate::Error>,
{
ensure_compatible_types::<T, *mut raw::c_void>()?;
let symbol = cstr_cow_from_bytes(symbol)?;
// `dlsym` may return nullptr in two cases: when a symbol genuinely points to a null
// pointer or the symbol cannot be found. In order to detect this case a double dlerror
// pattern must be used, which is, sadly, a little bit racy.
//
// We try to leave as little space as possible for this to occur, but we can’t exactly
// fully prevent it.
let result = with_dlerror(
|| {
dlerror();
let symbol = dlsym(self.handle, symbol.as_ptr());
if symbol.is_null() {
None
} else {
Some(Symbol {
pointer: symbol,
pd: marker::PhantomData,
})
}
},
|desc| crate::Error::DlSym { desc: desc.into() },
);
match result {
Err(None) => on_null(),
Err(Some(e)) => Err(e),
Ok(x) => Ok(x),
}
}
/// Get a pointer to a function or static variable by symbol name.
///
/// The `symbol` may not contain any null bytes, with the exception of the last byte. Providing a
/// null terminated `symbol` may help to avoid an allocation.
///
/// Symbol is interpreted as-is; no mangling is done. This means that symbols like `x::y` are
/// most likely invalid.
///
/// # Safety
///
/// Users of this API must specify the correct type of the function or variable loaded. Using a
/// `Symbol` with a wrong type is undefined.
///
/// # Platform-specific behaviour
///
/// Implementation of thread local variables is extremely platform specific and uses of such
/// variables that work on e.g. Linux may have unintended behaviour on other targets.
///
/// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe (such
/// as FreeBSD), this function will unconditionally return an error when the underlying `dlsym`
/// call returns a null pointer. There are rare situations where `dlsym` returns a genuine null
/// pointer without it being an error. If loading a null pointer is something you care about,
/// consider using the [`Library::get_singlethreaded`] call.
#[inline(always)]
pub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error> {
extern crate cfg_if;
cfg_if::cfg_if! {
// These targets are known to have MT-safe `dlerror`.
if #[cfg(any(
target_os = "linux",
target_os = "android",
target_os = "openbsd",
target_os = "macos",
target_os = "ios",
target_os = "solaris",
target_os = "illumos",
target_os = "redox",
target_os = "fuchsia"
))] {
self.get_singlethreaded(symbol)
} else {
self.get_impl(symbol, || Err(crate::Error::DlSymUnknown))
}
}
}
/// Get a pointer to function or static variable by symbol name.
///
/// The `symbol` may not contain any null bytes, with the exception of the last byte. Providing a
/// null terminated `symbol` may help to avoid an allocation.
///
/// Symbol is interpreted as-is; no mangling is done. This means that symbols like `x::y` are
/// most likely invalid.
///
/// # Safety
///
/// Users of this API must specify the correct type of the function or variable loaded.
///
/// It is up to the user of this library to ensure that no other calls to an MT-unsafe
/// implementation of `dlerror` occur during the execution of this function. Failing that, the
/// behaviour of this function is not defined.
///
/// # Platform-specific behaviour
///
/// The implementation of thread-local variables is extremely platform specific and uses of such
/// variables that work on e.g. Linux may have unintended behaviour on other targets.
#[inline(always)]
pub unsafe fn get_singlethreaded<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error> {
self.get_impl(symbol, || {
Ok(Symbol {
pointer: ptr::null_mut(),
pd: marker::PhantomData,
})
})
}
/// Convert the `Library` to a raw handle.
///
/// The handle returned by this function shall be usable with APIs which accept handles
/// as returned by `dlopen`.
pub fn into_raw(self) -> *mut raw::c_void {
let handle = self.handle;
mem::forget(self);
handle
}
/// Convert a raw handle returned by `dlopen`-family of calls to a `Library`.
///
/// # Safety
///
/// The pointer shall be a result of a successful call of the `dlopen`-family of functions or a
/// pointer previously returned by `Library::into_raw` call. It must be valid to call `dlclose`
/// with this pointer as an argument.
pub unsafe fn from_raw(handle: *mut raw::c_void) -> Library {
Library { handle }
}
/// Unload the library.
///
/// This method might be a no-op, depending on the flags with which the `Library` was opened,
/// what library was opened or other platform specifics.
///
/// You only need to call this if you are interested in handling any errors that may arise when
/// library is unloaded. Otherwise the implementation of `Drop` for `Library` will close the
/// library and ignore the errors were they arise.
///
/// The underlying data structures may still get leaked if an error does occur.
pub fn close(self) -> Result<(), crate::Error> {
let result = with_dlerror(
|| {
if unsafe { dlclose(self.handle) } == 0 {
Some(())
} else {
None
}
},
|desc| crate::Error::DlClose { desc: desc.into() },
)
.map_err(|e| e.unwrap_or(crate::Error::DlCloseUnknown));
// While the library is not free'd yet in case of an error, there is no reason to try
// dropping it again, because all that will do is try calling `dlclose` again. only
// this time it would ignore the return result, which we already seen failing…
std::mem::forget(self);
result
}
}
impl Drop for Library {
fn drop(&mut self) {
unsafe {
dlclose(self.handle);
}
}
}
impl fmt::Debug for Library {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.write_str(&format!("Library@{:p}", self.handle))
}
}
/// Symbol from a library.
///
/// A major difference compared to the cross-platform `Symbol` is that this does not ensure that the
/// `Symbol` does not outlive the `Library` it comes from.
pub struct Symbol<T> {
pointer: *mut raw::c_void,
pd: marker::PhantomData<T>,
}
impl<T> Symbol<T> {
/// Convert the loaded `Symbol` into a raw pointer.
pub fn into_raw(self) -> *mut raw::c_void {
self.pointer
}
/// Convert the loaded `Symbol` into a raw pointer.
/// For unix this does the same as into_raw.
pub fn as_raw_ptr(self) -> *mut raw::c_void {
self.pointer
}
}
impl<T> Symbol<Option<T>> {
/// Lift Option out of the symbol.
pub fn lift_option(self) -> Option<Symbol<T>> {
if self.pointer.is_null() {
None
} else {
Some(Symbol {
pointer: self.pointer,
pd: marker::PhantomData,
})
}
}
}
unsafe impl<T: Send> Send for Symbol<T> {}
unsafe impl<T: Sync> Sync for Symbol<T> {}
impl<T> Clone for Symbol<T> {
fn clone(&self) -> Symbol<T> {
Symbol { ..*self }
}
}
impl<T> ::std::ops::Deref for Symbol<T> {
type Target = T;
fn deref(&self) -> &T {
unsafe {
// Additional reference level for a dereference on `deref` return value.
&*(&self.pointer as *const *mut _ as *const T)
}
}
}
impl<T> fmt::Debug for Symbol<T> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
unsafe {
let mut info = mem::MaybeUninit::<DlInfo>::uninit();
if dladdr(self.pointer, info.as_mut_ptr()) != 0 {
let info = info.assume_init();
if info.dli_sname.is_null() {
f.write_str(&format!(
"Symbol@{:p} from {:?}",
self.pointer,
CStr::from_ptr(info.dli_fname)
))
} else {
f.write_str(&format!(
"Symbol {:?}@{:p} from {:?}",
CStr::from_ptr(info.dli_sname),
self.pointer,
CStr::from_ptr(info.dli_fname)
))
}
} else {
f.write_str(&format!("Symbol@{:p}", self.pointer))
}
}
}
}
// Platform specific things
#[cfg_attr(any(target_os = "linux", target_os = "android"), link(name = "dl"))]
#[cfg_attr(any(target_os = "freebsd", target_os = "dragonfly"), link(name = "c"))]
extern "C" {
fn dlopen(filename: *const raw::c_char, flags: raw::c_int) -> *mut raw::c_void;
fn dlclose(handle: *mut raw::c_void) -> raw::c_int;
fn dlsym(handle: *mut raw::c_void, symbol: *const raw::c_char) -> *mut raw::c_void;
fn dlerror() -> *mut raw::c_char;
fn dladdr(addr: *mut raw::c_void, info: *mut DlInfo) -> raw::c_int;
}
#[repr(C)]
struct DlInfo {
dli_fname: *const raw::c_char,
dli_fbase: *mut raw::c_void,
dli_sname: *const raw::c_char,
dli_saddr: *mut raw::c_void,
}