1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273
//! A "compatibility layer" for supporting older versions of Windows
//!
//! The standard library uses some Windows API functions that are not present
//! on older versions of Windows. (Note that the oldest version of Windows
//! that Rust supports is Windows 7 (client) and Windows Server 2008 (server).)
//! This module implements a form of delayed DLL import binding, using
//! `GetModuleHandle` and `GetProcAddress` to look up DLL entry points at
//! runtime.
//!
//! This implementation uses a static initializer to look up the DLL entry
//! points. The CRT (C runtime) executes static initializers before `main`
//! is called (for binaries) and before `DllMain` is called (for DLLs).
//! This is the ideal time to look up DLL imports, because we are guaranteed
//! that no other threads will attempt to call these entry points. Thus,
//! we can look up the imports and store them in `static mut` fields
//! without any synchronization.
//!
//! This has an additional advantage: Because the DLL import lookup happens
//! at module initialization, the cost of these lookups is deterministic,
//! and is removed from the code paths that actually call the DLL imports.
//! That is, there is no unpredictable "cache miss" that occurs when calling
//! a DLL import. For applications that benefit from predictable delays,
//! this is a benefit. This also eliminates the comparison-and-branch
//! from the hot path.
//!
//! Currently, the standard library uses only a small number of dynamic
//! DLL imports. If this number grows substantially, then the cost of
//! performing all of the lookups at initialization time might become
//! substantial.
//!
//! The mechanism of registering a static initializer with the CRT is
//! documented in
//! [CRT Initialization](https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-initialization?view=msvc-160).
//! It works by contributing a global symbol to the `.CRT$XCU` section.
//! The linker builds a table of all static initializer functions.
//! The CRT startup code then iterates that table, calling each
//! initializer function.
//!
//! # **WARNING!!*
//! The environment that a static initializer function runs in is highly
//! constrained. There are **many** restrictions on what static initializers
//! can safely do. Static initializer functions **MUST NOT** do any of the
//! following (this list is not comprehensive):
//! * touch any other static field that is used by a different static
//! initializer, because the order that static initializers run in
//! is not defined.
//! * call `LoadLibrary` or any other function that acquires the DLL
//! loader lock.
//! * call any Rust function or CRT function that touches any static
//! (global) state.
use crate::ffi::{c_void, CStr};
use crate::ptr::NonNull;
use crate::sys::c;
/// Helper macro for creating CStrs from literals and symbol names.
macro_rules! ansi_str {
(sym $ident:ident) => {{
#[allow(unused_unsafe)]
crate::sys::compat::const_cstr_from_bytes(concat!(stringify!($ident), "\0").as_bytes())
}};
($lit:literal) => {{ crate::sys::compat::const_cstr_from_bytes(concat!($lit, "\0").as_bytes()) }};
}
/// Creates a C string wrapper from a byte slice, in a constant context.
///
/// This is a utility function used by the [`ansi_str`] macro.
///
/// # Panics
///
/// Panics if the slice is not null terminated or contains nulls, except as the last item
pub(crate) const fn const_cstr_from_bytes(bytes: &'static [u8]) -> &'static CStr {
if !matches!(bytes.last(), Some(&0)) {
panic!("A CStr must be null terminated");
}
let mut i = 0;
// At this point `len()` is at least 1.
while i < bytes.len() - 1 {
if bytes[i] == 0 {
panic!("A CStr must not have interior nulls")
}
i += 1;
}
// SAFETY: The safety is ensured by the above checks.
unsafe { crate::ffi::CStr::from_bytes_with_nul_unchecked(bytes) }
}
#[used]
#[link_section = ".CRT$XCU"]
static INIT_TABLE_ENTRY: unsafe extern "C" fn() = init;
/// This is where the magic preloading of symbols happens.
///
/// Note that any functions included here will be unconditionally included in
/// the final binary, regardless of whether or not they're actually used.
///
/// Therefore, this is limited to `compat_fn_optional` functions which must be
/// preloaded and any functions which may be more time sensitive, even for the first call.
unsafe extern "C" fn init() {
// There is no locking here. This code is executed before main() is entered, and
// is guaranteed to be single-threaded.
//
// DO NOT do anything interesting or complicated in this function! DO NOT call
// any Rust functions or CRT functions if those functions touch any global state,
// because this function runs during global initialization. For example, DO NOT
// do any dynamic allocation, don't call LoadLibrary, etc.
if let Some(synch) = Module::new(c::SYNCH_API) {
// These are optional and so we must manually attempt to load them
// before they can be used.
c::WaitOnAddress::preload(synch);
c::WakeByAddressSingle::preload(synch);
}
if let Some(kernel32) = Module::new(c::KERNEL32) {
// Preloading this means getting a precise time will be as fast as possible.
c::GetSystemTimePreciseAsFileTime::preload(kernel32);
}
}
/// Represents a loaded module.
///
/// Note that the modules std depends on must not be unloaded.
/// Therefore a `Module` is always valid for the lifetime of std.
#[derive(Copy, Clone)]
pub(in crate::sys) struct Module(NonNull<c_void>);
impl Module {
/// Try to get a handle to a loaded module.
///
/// # SAFETY
///
/// This should only be use for modules that exist for the lifetime of std
/// (e.g. kernel32 and ntdll).
pub unsafe fn new(name: &CStr) -> Option<Self> {
// SAFETY: A CStr is always null terminated.
let module = c::GetModuleHandleA(name.as_ptr());
NonNull::new(module).map(Self)
}
// Try to get the address of a function.
pub fn proc_address(self, name: &CStr) -> Option<NonNull<c_void>> {
// SAFETY:
// `self.0` will always be a valid module.
// A CStr is always null terminated.
let proc = unsafe { c::GetProcAddress(self.0.as_ptr(), name.as_ptr()) };
NonNull::new(proc)
}
}
/// Load a function or use a fallback implementation if that fails.
macro_rules! compat_fn_with_fallback {
(pub static $module:ident: &CStr = $name:expr; $(
$(#[$meta:meta])*
pub fn $symbol:ident($($argname:ident: $argtype:ty),*) -> $rettype:ty $fallback_body:block
)*) => (
pub static $module: &CStr = $name;
$(
$(#[$meta])*
pub mod $symbol {
#[allow(unused_imports)]
use super::*;
use crate::mem;
use crate::ffi::CStr;
use crate::sync::atomic::{AtomicPtr, Ordering};
use crate::sys::compat::Module;
type F = unsafe extern "system" fn($($argtype),*) -> $rettype;
/// `PTR` contains a function pointer to one of three functions.
/// It starts with the `load` function.
/// When that is called it attempts to load the requested symbol.
/// If it succeeds, `PTR` is set to the address of that symbol.
/// If it fails, then `PTR` is set to `fallback`.
static PTR: AtomicPtr<c_void> = AtomicPtr::new(load as *mut _);
unsafe extern "system" fn load($($argname: $argtype),*) -> $rettype {
let func = load_from_module(Module::new($module));
func($($argname),*)
}
fn load_from_module(module: Option<Module>) -> F {
unsafe {
static SYMBOL_NAME: &CStr = ansi_str!(sym $symbol);
if let Some(f) = module.and_then(|m| m.proc_address(SYMBOL_NAME)) {
PTR.store(f.as_ptr(), Ordering::Relaxed);
mem::transmute(f)
} else {
PTR.store(fallback as *mut _, Ordering::Relaxed);
fallback
}
}
}
#[allow(unused_variables)]
unsafe extern "system" fn fallback($($argname: $argtype),*) -> $rettype {
$fallback_body
}
#[allow(unused)]
pub(in crate::sys) fn preload(module: Module) {
load_from_module(Some(module));
}
#[inline(always)]
pub unsafe fn call($($argname: $argtype),*) -> $rettype {
let func: F = mem::transmute(PTR.load(Ordering::Relaxed));
func($($argname),*)
}
}
$(#[$meta])*
pub use $symbol::call as $symbol;
)*)
}
/// A function that either exists or doesn't.
///
/// NOTE: Optional functions must be preloaded in the `init` function above, or they will always be None.
macro_rules! compat_fn_optional {
(pub static $module:ident: &CStr = $name:expr; $(
$(#[$meta:meta])*
pub fn $symbol:ident($($argname:ident: $argtype:ty),*) -> $rettype:ty;
)*) => (
pub static $module: &CStr = $name;
$(
$(#[$meta])*
pub mod $symbol {
#[allow(unused_imports)]
use super::*;
use crate::mem;
use crate::sync::atomic::{AtomicPtr, Ordering};
use crate::sys::compat::Module;
use crate::ptr::{self, NonNull};
type F = unsafe extern "system" fn($($argtype),*) -> $rettype;
/// `PTR` will either be `null()` or set to the loaded function.
static PTR: AtomicPtr<c_void> = AtomicPtr::new(ptr::null_mut());
/// Only allow access to the function if it has loaded successfully.
#[inline(always)]
#[cfg(not(miri))]
pub fn option() -> Option<F> {
unsafe {
NonNull::new(PTR.load(Ordering::Relaxed)).map(|f| mem::transmute(f))
}
}
// Miri does not understand the way we do preloading
// therefore load the function here instead.
#[cfg(miri)]
pub fn option() -> Option<F> {
let mut func = NonNull::new(PTR.load(Ordering::Relaxed));
if func.is_none() {
unsafe { Module::new($module).map(preload) };
func = NonNull::new(PTR.load(Ordering::Relaxed));
}
unsafe {
func.map(|f| mem::transmute(f))
}
}
#[allow(unused)]
pub(in crate::sys) fn preload(module: Module) {
unsafe {
static SYMBOL_NAME: &CStr = ansi_str!(sym $symbol);
if let Some(f) = module.proc_address(SYMBOL_NAME) {
PTR.store(f.as_ptr(), Ordering::Relaxed);
}
}
}
}
)*)
}