]>
Commit | Line | Data |
---|---|---|
1b1a35ee XL |
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 | } | |
f035d41b | 10 | |
1b1a35ee XL |
11 | use self::unix_imports::*; |
12 | use util::{ensure_compatible_types, cstr_cow_from_bytes}; | |
f035d41b XL |
13 | use std::ffi::{CStr, OsStr}; |
14 | use std::{fmt, marker, mem, ptr}; | |
15 | use std::os::raw; | |
1b1a35ee XL |
16 | pub use self::consts::*; |
17 | ||
18 | mod consts; | |
f035d41b XL |
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 | ||
1b1a35ee | 76 | /// A platform-specific counterpart of the cross-platform [`Library`](crate::Library). |
f035d41b XL |
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 { | |
1b1a35ee | 100 | /// Find and eagerly load a shared library (module). |
f035d41b | 101 | /// |
1b1a35ee XL |
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. | |
f035d41b | 105 | /// |
1b1a35ee XL |
106 | /// This is equivalent to [`Library::open`]`(filename, RTLD_NOW)`. |
107 | /// | |
108 | /// [path separator]: std::path::MAIN_SEPARATOR | |
f035d41b XL |
109 | #[inline] |
110 | pub fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, crate::Error> { | |
111 | Library::open(Some(filename), RTLD_NOW) | |
112 | } | |
113 | ||
1b1a35ee XL |
114 | /// Eagerly load the `Library` representing the current executable. |
115 | /// | |
116 | /// [`Library::get`] calls of the returned `Library` will look for symbols in following | |
117 | /// locations in order: | |
118 | /// | |
119 | /// 1. Original program image; | |
120 | /// 2. Any executable object files (e.g. shared libraries) loaded at program startup; | |
121 | /// 3. Executable object files loaded at runtime (e.g. via other `Library::new` calls or via | |
122 | /// calls to the `dlopen` function) | |
f035d41b | 123 | /// |
1b1a35ee XL |
124 | /// Note that behaviour of `Library` loaded with this method is different from |
125 | /// Libraries loaded with [`os::windows::Library::this`]. | |
f035d41b | 126 | /// |
1b1a35ee XL |
127 | /// This is equivalent to [`Library::open`]`(None, RTLD_NOW)`. |
128 | /// | |
129 | /// [`os::windows::Library::this`]: crate::os::windows::Library::this | |
f035d41b XL |
130 | #[inline] |
131 | pub fn this() -> Library { | |
132 | Library::open(None::<&OsStr>, RTLD_NOW).expect("this should never fail") | |
133 | } | |
134 | ||
1b1a35ee | 135 | /// Find and load an executable object file (shared library). |
f035d41b | 136 | /// |
1b1a35ee XL |
137 | /// See documentation for [`Library::this`] for further description of behaviour |
138 | /// when the `filename` is `None`. Otherwise see [`Library::new`]. | |
f035d41b XL |
139 | /// |
140 | /// Corresponds to `dlopen(filename, flags)`. | |
141 | pub fn open<P>(filename: Option<P>, flags: raw::c_int) -> Result<Library, crate::Error> | |
142 | where P: AsRef<OsStr> { | |
143 | let filename = match filename { | |
144 | None => None, | |
145 | Some(ref f) => Some(cstr_cow_from_bytes(f.as_ref().as_bytes())?), | |
146 | }; | |
147 | with_dlerror(|desc| crate::Error::DlOpen { desc }, move || { | |
148 | let result = unsafe { | |
149 | let r = dlopen(match filename { | |
150 | None => ptr::null(), | |
151 | Some(ref f) => f.as_ptr() | |
152 | }, flags); | |
153 | // ensure filename lives until dlopen completes | |
154 | drop(filename); | |
155 | r | |
156 | }; | |
157 | if result.is_null() { | |
158 | None | |
159 | } else { | |
160 | Some(Library { | |
161 | handle: result | |
162 | }) | |
163 | } | |
164 | }).map_err(|e| e.unwrap_or(crate::Error::DlOpenUnknown)) | |
165 | } | |
166 | ||
167 | unsafe fn get_impl<T, F>(&self, symbol: &[u8], on_null: F) -> Result<Symbol<T>, crate::Error> | |
168 | where F: FnOnce() -> Result<Symbol<T>, crate::Error> | |
169 | { | |
170 | ensure_compatible_types::<T, *mut raw::c_void>()?; | |
171 | let symbol = cstr_cow_from_bytes(symbol)?; | |
172 | // `dlsym` may return nullptr in two cases: when a symbol genuinely points to a null | |
173 | // pointer or the symbol cannot be found. In order to detect this case a double dlerror | |
174 | // pattern must be used, which is, sadly, a little bit racy. | |
175 | // | |
176 | // We try to leave as little space as possible for this to occur, but we can’t exactly | |
177 | // fully prevent it. | |
178 | match with_dlerror(|desc| crate::Error::DlSym { desc }, || { | |
179 | dlerror(); | |
180 | let symbol = dlsym(self.handle, symbol.as_ptr()); | |
181 | if symbol.is_null() { | |
182 | None | |
183 | } else { | |
184 | Some(Symbol { | |
185 | pointer: symbol, | |
186 | pd: marker::PhantomData | |
187 | }) | |
188 | } | |
189 | }) { | |
190 | Err(None) => on_null(), | |
191 | Err(Some(e)) => Err(e), | |
192 | Ok(x) => Ok(x) | |
193 | } | |
194 | ||
195 | } | |
196 | ||
197 | /// Get a pointer to function or static variable by symbol name. | |
198 | /// | |
199 | /// The `symbol` may not contain any null bytes, with an exception of last byte. A null | |
1b1a35ee | 200 | /// terminated `symbol` may avoid an allocation in some cases. |
f035d41b XL |
201 | /// |
202 | /// Symbol is interpreted as-is; no mangling is done. This means that symbols like `x::y` are | |
203 | /// most likely invalid. | |
204 | /// | |
1b1a35ee | 205 | /// # Safety |
f035d41b XL |
206 | /// |
207 | /// This function does not validate the type `T`. It is up to the user of this function to | |
208 | /// ensure that the loaded symbol is in fact a `T`. Using a value with a wrong type has no | |
1b1a35ee | 209 | /// defined behaviour. |
f035d41b | 210 | /// |
1b1a35ee | 211 | /// # Platform-specific behaviour |
f035d41b | 212 | /// |
1b1a35ee XL |
213 | /// Implementation of thread local variables is extremely platform specific and uses of these |
214 | /// variables that work on e.g. Linux may have unintended behaviour on other POSIX systems. | |
f035d41b XL |
215 | /// |
216 | /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe (such | |
1b1a35ee XL |
217 | /// as FreeBSD), this function will unconditionally return an error when the underlying `dlsym` |
218 | /// call returns a null pointer. There are rare situations where `dlsym` returns a genuine null | |
219 | /// pointer without it being an error. If loading a symbol at null address is something you | |
220 | /// care about, consider using the [`Library::get_singlethreaded`] call. | |
f035d41b XL |
221 | #[inline(always)] |
222 | pub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error> { | |
223 | #[cfg(mtsafe_dlerror)] | |
1b1a35ee | 224 | { self.get_singlethreaded(symbol) } |
f035d41b | 225 | #[cfg(not(mtsafe_dlerror))] |
1b1a35ee | 226 | { self.get_impl(symbol, || Err(crate::Error::DlSymUnknown)) } |
f035d41b XL |
227 | } |
228 | ||
229 | /// Get a pointer to function or static variable by symbol name. | |
230 | /// | |
231 | /// The `symbol` may not contain any null bytes, with an exception of last byte. A null | |
232 | /// terminated `symbol` may avoid a string allocation in some cases. | |
233 | /// | |
234 | /// Symbol is interpreted as-is; no mangling is done. This means that symbols like `x::y` are | |
235 | /// most likely invalid. | |
236 | /// | |
1b1a35ee | 237 | /// # Safety |
f035d41b XL |
238 | /// |
239 | /// This function does not validate the type `T`. It is up to the user of this function to | |
240 | /// ensure that the loaded symbol is in fact a `T`. Using a value with a wrong type has no | |
1b1a35ee | 241 | /// defined behaviour. |
f035d41b XL |
242 | /// |
243 | /// It is up to the user of this library to ensure that no other calls to an MT-unsafe | |
1b1a35ee XL |
244 | /// implementation of `dlerror` occur during execution of this function. Failing that, the |
245 | /// behaviour of this function is not defined. | |
f035d41b | 246 | /// |
1b1a35ee | 247 | /// # Platform-specific behaviour |
f035d41b | 248 | /// |
1b1a35ee XL |
249 | /// Implementation of thread local variables is extremely platform specific and uses of these |
250 | /// variables that work on e.g. Linux may have unintended behaviour on other POSIX systems. | |
f035d41b XL |
251 | #[inline(always)] |
252 | pub unsafe fn get_singlethreaded<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, crate::Error> { | |
253 | self.get_impl(symbol, || Ok(Symbol { | |
254 | pointer: ptr::null_mut(), | |
255 | pd: marker::PhantomData | |
256 | })) | |
257 | } | |
258 | ||
259 | /// Convert the `Library` to a raw handle. | |
260 | /// | |
261 | /// The handle returned by this function shall be usable with APIs which accept handles | |
262 | /// as returned by `dlopen`. | |
263 | pub fn into_raw(self) -> *mut raw::c_void { | |
264 | let handle = self.handle; | |
265 | mem::forget(self); | |
266 | handle | |
267 | } | |
268 | ||
269 | /// Convert a raw handle returned by `dlopen`-family of calls to a `Library`. | |
270 | /// | |
1b1a35ee | 271 | /// # Safety |
f035d41b XL |
272 | /// |
273 | /// The pointer shall be a result of a successful call of the `dlopen`-family of functions or a | |
274 | /// pointer previously returned by `Library::into_raw` call. It must be valid to call `dlclose` | |
275 | /// with this pointer as an argument. | |
276 | pub unsafe fn from_raw(handle: *mut raw::c_void) -> Library { | |
277 | Library { | |
1b1a35ee | 278 | handle |
f035d41b XL |
279 | } |
280 | } | |
281 | ||
282 | /// Unload the library. | |
283 | /// | |
284 | /// This method might be a no-op, depending on the flags with which the `Library` was opened, | |
285 | /// what library was opened or other platform specifics. | |
286 | /// | |
287 | /// You only need to call this if you are interested in handling any errors that may arise when | |
1b1a35ee | 288 | /// library is unloaded. Otherwise this will be done when `Library` is dropped. |
f035d41b XL |
289 | pub fn close(self) -> Result<(), crate::Error> { |
290 | let result = with_dlerror(|desc| crate::Error::DlClose { desc }, || { | |
291 | if unsafe { dlclose(self.handle) } == 0 { | |
292 | Some(()) | |
293 | } else { | |
294 | None | |
295 | } | |
296 | }).map_err(|e| e.unwrap_or(crate::Error::DlCloseUnknown)); | |
297 | std::mem::forget(self); | |
298 | result | |
299 | } | |
300 | } | |
301 | ||
302 | impl Drop for Library { | |
303 | fn drop(&mut self) { | |
304 | unsafe { | |
305 | dlclose(self.handle); | |
306 | } | |
307 | } | |
308 | } | |
309 | ||
310 | impl fmt::Debug for Library { | |
311 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
312 | f.write_str(&format!("Library@{:p}", self.handle)) | |
313 | } | |
314 | } | |
315 | ||
316 | /// Symbol from a library. | |
317 | /// | |
318 | /// A major difference compared to the cross-platform `Symbol` is that this does not ensure the | |
319 | /// `Symbol` does not outlive `Library` it comes from. | |
320 | pub struct Symbol<T> { | |
321 | pointer: *mut raw::c_void, | |
322 | pd: marker::PhantomData<T> | |
323 | } | |
324 | ||
325 | impl<T> Symbol<T> { | |
326 | /// Convert the loaded Symbol into a raw pointer. | |
327 | pub fn into_raw(self) -> *mut raw::c_void { | |
328 | let pointer = self.pointer; | |
329 | mem::forget(self); | |
330 | pointer | |
331 | } | |
332 | } | |
333 | ||
334 | impl<T> Symbol<Option<T>> { | |
335 | /// Lift Option out of the symbol. | |
336 | pub fn lift_option(self) -> Option<Symbol<T>> { | |
337 | if self.pointer.is_null() { | |
338 | None | |
339 | } else { | |
340 | Some(Symbol { | |
341 | pointer: self.pointer, | |
342 | pd: marker::PhantomData, | |
343 | }) | |
344 | } | |
345 | } | |
346 | } | |
347 | ||
348 | unsafe impl<T: Send> Send for Symbol<T> {} | |
349 | unsafe impl<T: Sync> Sync for Symbol<T> {} | |
350 | ||
351 | impl<T> Clone for Symbol<T> { | |
352 | fn clone(&self) -> Symbol<T> { | |
353 | Symbol { ..*self } | |
354 | } | |
355 | } | |
356 | ||
357 | impl<T> ::std::ops::Deref for Symbol<T> { | |
358 | type Target = T; | |
359 | fn deref(&self) -> &T { | |
360 | unsafe { | |
361 | // Additional reference level for a dereference on `deref` return value. | |
1b1a35ee | 362 | &*(&self.pointer as *const *mut _ as *const T) |
f035d41b XL |
363 | } |
364 | } | |
365 | } | |
366 | ||
367 | impl<T> fmt::Debug for Symbol<T> { | |
368 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
369 | unsafe { | |
370 | let mut info = mem::MaybeUninit::<DlInfo>::uninit(); | |
371 | if dladdr(self.pointer, info.as_mut_ptr()) != 0 { | |
372 | let info = info.assume_init(); | |
373 | if info.dli_sname.is_null() { | |
374 | f.write_str(&format!("Symbol@{:p} from {:?}", | |
375 | self.pointer, | |
376 | CStr::from_ptr(info.dli_fname))) | |
377 | } else { | |
378 | f.write_str(&format!("Symbol {:?}@{:p} from {:?}", | |
379 | CStr::from_ptr(info.dli_sname), self.pointer, | |
380 | CStr::from_ptr(info.dli_fname))) | |
381 | } | |
382 | } else { | |
383 | f.write_str(&format!("Symbol@{:p}", self.pointer)) | |
384 | } | |
385 | } | |
386 | } | |
387 | } | |
388 | ||
389 | // Platform specific things | |
f035d41b XL |
390 | extern { |
391 | fn dlopen(filename: *const raw::c_char, flags: raw::c_int) -> *mut raw::c_void; | |
392 | fn dlclose(handle: *mut raw::c_void) -> raw::c_int; | |
393 | fn dlsym(handle: *mut raw::c_void, symbol: *const raw::c_char) -> *mut raw::c_void; | |
394 | fn dlerror() -> *mut raw::c_char; | |
395 | fn dladdr(addr: *mut raw::c_void, info: *mut DlInfo) -> raw::c_int; | |
396 | } | |
397 | ||
f035d41b XL |
398 | #[repr(C)] |
399 | struct DlInfo { | |
400 | dli_fname: *const raw::c_char, | |
401 | dli_fbase: *mut raw::c_void, | |
402 | dli_sname: *const raw::c_char, | |
403 | dli_saddr: *mut raw::c_void | |
404 | } |