src/libstd/dynamic_lib.rs

   1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 /*!
  12
  13 Dynamic library facilities.
  14
  15 A simple wrapper over the platform's dynamic library facilities
  16
  17 */
  18
  19 #![experimental]
  20 #![allow(missing_doc)]
  21
  22 use clone::Clone;
  23 use c_str::ToCStr;
  24 use iter::Iterator;
  25 use mem;
  26 use ops::*;
  27 use option::*;
  28 use os;
  29 use path::{Path,GenericPath};
  30 use result::*;
  31 use slice::{Vector,ImmutableVector};
  32 use str;
  33 use string::String;
  34 use vec::Vec;
  35
  36 pub struct DynamicLibrary { handle: *mut u8 }
  37
  38 impl Drop for DynamicLibrary {
  39     fn drop(&mut self) {
  40         match dl::check_for_errors_in(|| {
  41             unsafe {
  42                 dl::close(self.handle)
  43             }
  44         }) {
  45             Ok(()) => {},
  46             Err(str) => fail!("{}", str)
  47         }
  48     }
  49 }
  50
  51 impl DynamicLibrary {
  52     // FIXME (#12938): Until DST lands, we cannot decompose &str into
  53     // & and str, so we cannot usefully take ToCStr arguments by
  54     // reference (without forcing an additional & around &str). So we
  55     // are instead temporarily adding an instance for &Path, so that
  56     // we can take ToCStr as owned. When DST lands, the &Path instance
  57     // should be removed, and arguments bound by ToCStr should be
  58     // passed by reference. (Here: in the `open` method.)
  59
  60     /// Lazily open a dynamic library. When passed None it gives a
  61     /// handle to the calling process
  62     pub fn open<T: ToCStr>(filename: Option<T>)
  63                         -> Result<DynamicLibrary, String> {
  64         unsafe {
  65             let mut filename = filename;
  66             let maybe_library = dl::check_for_errors_in(|| {
  67                 match filename.take() {
  68                     Some(name) => dl::open_external(name),
  69                     None => dl::open_internal()
  70                 }
  71             });
  72
  73             // The dynamic library must not be constructed if there is
  74             // an error opening the library so the destructor does not
  75             // run.
  76             match maybe_library {
  77                 Err(err) => Err(err),
  78                 Ok(handle) => Ok(DynamicLibrary { handle: handle })
  79             }
  80         }
  81     }
  82
  83     /// Prepends a path to this process's search path for dynamic libraries
  84     pub fn prepend_search_path(path: &Path) {
  85         let mut search_path = DynamicLibrary::search_path();
  86         search_path.insert(0, path.clone());
  87         let newval = DynamicLibrary::create_path(search_path.as_slice());
  88         os::setenv(DynamicLibrary::envvar(),
  89                    str::from_utf8(newval.as_slice()).unwrap());
  90     }
  91
  92     /// From a slice of paths, create a new vector which is suitable to be an
  93     /// environment variable for this platforms dylib search path.
  94     pub fn create_path(path: &[Path]) -> Vec<u8> {
  95         let mut newvar = Vec::new();
  96         for (i, path) in path.iter().enumerate() {
  97             if i > 0 { newvar.push(DynamicLibrary::separator()); }
  98             newvar.push_all(path.as_vec());
  99         }
 100         return newvar;
 101     }
 102
 103     /// Returns the environment variable for this process's dynamic library
 104     /// search path
 105     pub fn envvar() -> &'static str {
 106         if cfg!(windows) {
 107             "PATH"
 108         } else if cfg!(target_os = "macos") {
 109             "DYLD_LIBRARY_PATH"
 110         } else {
 111             "LD_LIBRARY_PATH"
 112         }
 113     }
 114
 115     fn separator() -> u8 {
 116         if cfg!(windows) {';' as u8} else {':' as u8}
 117     }
 118
 119     /// Returns the current search path for dynamic libraries being used by this
 120     /// process
 121     pub fn search_path() -> Vec<Path> {
 122         let mut ret = Vec::new();
 123         match os::getenv_as_bytes(DynamicLibrary::envvar()) {
 124             Some(env) => {
 125                 for portion in
 126                         env.as_slice()
 127                            .split(|a| *a == DynamicLibrary::separator()) {
 128                     ret.push(Path::new(portion));
 129                 }
 130             }
 131             None => {}
 132         }
 133         return ret;
 134     }
 135
 136     /// Access the value at the symbol of the dynamic library
 137     pub unsafe fn symbol<T>(&self, symbol: &str) -> Result<*mut T, String> {
 138         // This function should have a lifetime constraint of 'a on
 139         // T but that feature is still unimplemented
 140
 141         let maybe_symbol_value = dl::check_for_errors_in(|| {
 142             symbol.with_c_str(|raw_string| {
 143                 dl::symbol(self.handle, raw_string)
 144             })
 145         });
 146
 147         // The value must not be constructed if there is an error so
 148         // the destructor does not run.
 149         match maybe_symbol_value {
 150             Err(err) => Err(err),
 151             Ok(symbol_value) => Ok(mem::transmute(symbol_value))
 152         }
 153     }
 154 }
 155
 156 #[cfg(test, not(target_os = "ios"))]
 157 mod test {
 158     use super::*;
 159     use prelude::*;
 160     use libc;
 161     use mem;
 162
 163     #[test]
 164     #[ignore(cfg(windows))] // FIXME #8818
 165     #[ignore(cfg(target_os="android"))] // FIXME(#10379)
 166     fn test_loading_cosine() {
 167         // The math library does not need to be loaded since it is already
 168         // statically linked in
 169         let none: Option<Path> = None; // appease the typechecker
 170         let libm = match DynamicLibrary::open(none) {
 171             Err(error) => fail!("Could not load self as module: {}", error),
 172             Ok(libm) => libm
 173         };
 174
 175         let cosine: extern fn(libc::c_double) -> libc::c_double = unsafe {
 176             match libm.symbol("cos") {
 177                 Err(error) => fail!("Could not load function cos: {}", error),
 178                 Ok(cosine) => mem::transmute::<*mut u8, _>(cosine)
 179             }
 180         };
 181
 182         let argument = 0.0;
 183         let expected_result = 1.0;
 184         let result = cosine(argument);
 185         if result != expected_result {
 186             fail!("cos({:?}) != {:?} but equaled {:?} instead", argument,
 187                    expected_result, result)
 188         }
 189     }
 190
 191     #[test]
 192     #[cfg(target_os = "linux")]
 193     #[cfg(target_os = "macos")]
 194     #[cfg(target_os = "freebsd")]
 195     fn test_errors_do_not_crash() {
 196         // Open /dev/null as a library to get an error, and make sure
 197         // that only causes an error, and not a crash.
 198         let path = Path::new("/dev/null");
 199         match DynamicLibrary::open(Some(&path)) {
 200             Err(_) => {}
 201             Ok(_) => fail!("Successfully opened the empty library.")
 202         }
 203     }
 204 }
 205
 206 #[cfg(target_os = "linux")]
 207 #[cfg(target_os = "android")]
 208 #[cfg(target_os = "macos")]
 209 #[cfg(target_os = "ios")]
 210 #[cfg(target_os = "freebsd")]
 211 pub mod dl {
 212     use prelude::*;
 213
 214     use c_str::{CString, ToCStr};
 215     use libc;
 216     use ptr;
 217     use result::*;
 218     use str::StrAllocating;
 219     use string::String;
 220
 221     pub unsafe fn open_external<T: ToCStr>(filename: T) -> *mut u8 {
 222         filename.with_c_str(|raw_name| {
 223             dlopen(raw_name, Lazy as libc::c_int) as *mut u8
 224         })
 225     }
 226
 227     pub unsafe fn open_internal() -> *mut u8 {
 228         dlopen(ptr::null(), Lazy as libc::c_int) as *mut u8
 229     }
 230
 231     pub fn check_for_errors_in<T>(f: || -> T) -> Result<T, String> {
 232         use rt::mutex::{StaticNativeMutex, NATIVE_MUTEX_INIT};
 233         static mut lock: StaticNativeMutex = NATIVE_MUTEX_INIT;
 234         unsafe {
 235             // dlerror isn't thread safe, so we need to lock around this entire
 236             // sequence
 237             let _guard = lock.lock();
 238             let _old_error = dlerror();
 239
 240             let result = f();
 241
 242             let last_error = dlerror() as *const _;
 243             let ret = if ptr::null() == last_error {
 244                 Ok(result)
 245             } else {
 246                 Err(CString::new(last_error, false).as_str()
 247                                                    .unwrap()
 248                                                    .to_string())
 249             };
 250
 251             ret
 252         }
 253     }
 254
 255     pub unsafe fn symbol(handle: *mut u8,
 256                          symbol: *const libc::c_char) -> *mut u8 {
 257         dlsym(handle as *mut libc::c_void, symbol) as *mut u8
 258     }
 259     pub unsafe fn close(handle: *mut u8) {
 260         dlclose(handle as *mut libc::c_void); ()
 261     }
 262
 263     pub enum RTLD {
 264         Lazy = 1,
 265         Now = 2,
 266         Global = 256,
 267         Local = 0,
 268     }
 269
 270     #[link_name = "dl"]
 271     extern {
 272         fn dlopen(filename: *const libc::c_char,
 273                   flag: libc::c_int) -> *mut libc::c_void;
 274         fn dlerror() -> *mut libc::c_char;
 275         fn dlsym(handle: *mut libc::c_void,
 276                  symbol: *const libc::c_char) -> *mut libc::c_void;
 277         fn dlclose(handle: *mut libc::c_void) -> libc::c_int;
 278     }
 279 }
 280
 281 #[cfg(target_os = "win32")]
 282 pub mod dl {
 283     use c_str::ToCStr;
 284     use iter::Iterator;
 285     use libc;
 286     use os;
 287     use ptr;
 288     use result::{Ok, Err, Result};
 289     use str::StrSlice;
 290     use str;
 291     use string::String;
 292     use vec::Vec;
 293
 294     pub unsafe fn open_external<T: ToCStr>(filename: T) -> *mut u8 {
 295         // Windows expects Unicode data
 296         let filename_cstr = filename.to_c_str();
 297         let filename_str = str::from_utf8(filename_cstr.as_bytes_no_nul()).unwrap();
 298         let filename_str: Vec<u16> = filename_str.utf16_units().collect();
 299         let filename_str = filename_str.append_one(0);
 300         LoadLibraryW(filename_str.as_ptr() as *const libc::c_void) as *mut u8
 301     }
 302
 303     pub unsafe fn open_internal() -> *mut u8 {
 304         let mut handle = ptr::mut_null();
 305         GetModuleHandleExW(0 as libc::DWORD, ptr::null(), &mut handle);
 306         handle as *mut u8
 307     }
 308
 309     pub fn check_for_errors_in<T>(f: || -> T) -> Result<T, String> {
 310         unsafe {
 311             SetLastError(0);
 312
 313             let result = f();
 314
 315             let error = os::errno();
 316             if 0 == error {
 317                 Ok(result)
 318             } else {
 319                 Err(format!("Error code {}", error))
 320             }
 321         }
 322     }
 323
 324     pub unsafe fn symbol(handle: *mut u8, symbol: *const libc::c_char) -> *mut u8 {
 325         GetProcAddress(handle as *mut libc::c_void, symbol) as *mut u8
 326     }
 327     pub unsafe fn close(handle: *mut u8) {
 328         FreeLibrary(handle as *mut libc::c_void); ()
 329     }
 330
 331     #[allow(non_snake_case_functions)]
 332     extern "system" {
 333         fn SetLastError(error: libc::size_t);
 334         fn LoadLibraryW(name: *const libc::c_void) -> *mut libc::c_void;
 335         fn GetModuleHandleExW(dwFlags: libc::DWORD, name: *const u16,
 336                               handle: *mut *mut libc::c_void)
 337                               -> *mut libc::c_void;
 338         fn GetProcAddress(handle: *mut libc::c_void,
 339                           name: *const libc::c_char) -> *mut libc::c_void;
 340         fn FreeLibrary(handle: *mut libc::c_void);
 341     }
 342 }