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