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