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.
with_dlerror<T, F>(wrap: fn(crate::error::DlDescription) -> crate::Error, closure: F) -> Result<T, Option<crate::Error>> where F: FnOnce() -> Option<T>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]
new<P: AsRef<OsStr>>(filename: P) -> Result<Library, crate::Error>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]
this() -> Library142 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.
open<P>(filename: Option<P>, flags: raw::c_int) -> Result<Library, crate::Error> where P: AsRef<OsStr>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
get_impl<T, F>(&self, symbol: &[u8], on_null: F) -> Result<Symbol<T>, crate::Error> where F: FnOnce() -> Result<Symbol<T>, crate::Error>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)]
get<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error>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)]
get_singlethreaded<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error>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`.
into_raw(self) -> *mut raw::c_void299 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.
from_raw(handle: *mut raw::c_void) -> Library312 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.
close(self) -> Result<(), crate::Error>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 {
drop(&mut self)345 fn drop(&mut self) {
346 unsafe {
347 dlclose(self.handle);
348 }
349 }
350 }
351
352 impl fmt::Debug for Library {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result353 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.
into_raw(self) -> *mut raw::c_void369 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.
lift_option(self) -> Option<Symbol<T>>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> {
clone(&self) -> 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;
deref(&self) -> &T401 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> {
fmt(&self, f: &mut fmt::Formatter) -> fmt::Result410 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 {
dlopen(filename: *const raw::c_char, flags: raw::c_int) -> *mut raw::c_void435 fn dlopen(filename: *const raw::c_char, flags: raw::c_int) -> *mut raw::c_void;
dlclose(handle: *mut raw::c_void) -> raw::c_int436 fn dlclose(handle: *mut raw::c_void) -> raw::c_int;
dlsym(handle: *mut raw::c_void, symbol: *const raw::c_char) -> *mut raw::c_void437 fn dlsym(handle: *mut raw::c_void, symbol: *const raw::c_char) -> *mut raw::c_void;
dlerror() -> *mut raw::c_char438 fn dlerror() -> *mut raw::c_char;
dladdr(addr: *mut raw::c_void, info: *mut DlInfo) -> raw::c_int439 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