library/std/src/sys/windows/process.rs

   1 #![unstable(feature = "process_internals", issue = "none")]
   2
   3 #[cfg(test)]
   4 mod tests;
   5
   6 use crate::cmp;
   7 use crate::collections::BTreeMap;
   8 use crate::convert::{TryFrom, TryInto};
   9 use crate::env;
  10 use crate::env::consts::{EXE_EXTENSION, EXE_SUFFIX};
  11 use crate::ffi::{OsStr, OsString};
  12 use crate::fmt;
  13 use crate::io::{self, Error, ErrorKind};
  14 use crate::mem;
  15 use crate::num::NonZeroI32;
  16 use crate::os::windows::ffi::{OsStrExt, OsStringExt};
  17 use crate::os::windows::io::{AsRawHandle, FromRawHandle, IntoRawHandle};
  18 use crate::path::{Path, PathBuf};
  19 use crate::ptr;
  20 use crate::sys::c;
  21 use crate::sys::c::NonZeroDWORD;
  22 use crate::sys::fs::{File, OpenOptions};
  23 use crate::sys::handle::Handle;
  24 use crate::sys::path;
  25 use crate::sys::pipe::{self, AnonPipe};
  26 use crate::sys::stdio;
  27 use crate::sys::{cvt, to_u16s};
  28 use crate::sys_common::mutex::StaticMutex;
  29 use crate::sys_common::process::{CommandEnv, CommandEnvs};
  30 use crate::sys_common::{AsInner, IntoInner};
  31
  32 use libc::{c_void, EXIT_FAILURE, EXIT_SUCCESS};
  33
  34 ////////////////////////////////////////////////////////////////////////////////
  35 // Command
  36 ////////////////////////////////////////////////////////////////////////////////
  37
  38 #[derive(Clone, Debug, Eq)]
  39 #[doc(hidden)]
  40 pub struct EnvKey {
  41     os_string: OsString,
  42     // This stores a UTF-16 encoded string to workaround the mismatch between
  43     // Rust's OsString (WTF-8) and the Windows API string type (UTF-16).
  44     // Normally converting on every API call is acceptable but here
  45     // `c::CompareStringOrdinal` will be called for every use of `==`.
  46     utf16: Vec<u16>,
  47 }
  48
  49 impl EnvKey {
  50     fn new<T: Into<OsString>>(key: T) -> Self {
  51         EnvKey::from(key.into())
  52     }
  53 }
  54
  55 // Comparing Windows environment variable keys[1] are behaviourally the
  56 // composition of two operations[2]:
  57 //
  58 // 1. Case-fold both strings. This is done using a language-independent
  59 // uppercase mapping that's unique to Windows (albeit based on data from an
  60 // older Unicode spec). It only operates on individual UTF-16 code units so
  61 // surrogates are left unchanged. This uppercase mapping can potentially change
  62 // between Windows versions.
  63 //
  64 // 2. Perform an ordinal comparison of the strings. A comparison using ordinal
  65 // is just a comparison based on the numerical value of each UTF-16 code unit[3].
  66 //
  67 // Because the case-folding mapping is unique to Windows and not guaranteed to
  68 // be stable, we ask the OS to compare the strings for us. This is done by
  69 // calling `CompareStringOrdinal`[4] with `bIgnoreCase` set to `TRUE`.
  70 //
  71 // [1] https://docs.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings#choosing-a-stringcomparison-member-for-your-method-call
  72 // [2] https://docs.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings#stringtoupper-and-stringtolower
  73 // [3] https://docs.microsoft.com/en-us/dotnet/api/system.stringcomparison?view=net-5.0#System_StringComparison_Ordinal
  74 // [4] https://docs.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-comparestringordinal
  75 impl Ord for EnvKey {
  76     fn cmp(&self, other: &Self) -> cmp::Ordering {
  77         unsafe {
  78             let result = c::CompareStringOrdinal(
  79                 self.utf16.as_ptr(),
  80                 self.utf16.len() as _,
  81                 other.utf16.as_ptr(),
  82                 other.utf16.len() as _,
  83                 c::TRUE,
  84             );
  85             match result {
  86                 c::CSTR_LESS_THAN => cmp::Ordering::Less,
  87                 c::CSTR_EQUAL => cmp::Ordering::Equal,
  88                 c::CSTR_GREATER_THAN => cmp::Ordering::Greater,
  89                 // `CompareStringOrdinal` should never fail so long as the parameters are correct.
  90                 _ => panic!("comparing environment keys failed: {}", Error::last_os_error()),
  91             }
  92         }
  93     }
  94 }
  95 impl PartialOrd for EnvKey {
  96     fn partial_cmp(&self, other: &Self) -> Option<cmp::Ordering> {
  97         Some(self.cmp(other))
  98     }
  99 }
 100 impl PartialEq for EnvKey {
 101     fn eq(&self, other: &Self) -> bool {
 102         if self.utf16.len() != other.utf16.len() {
 103             false
 104         } else {
 105             self.cmp(other) == cmp::Ordering::Equal
 106         }
 107     }
 108 }
 109 impl PartialOrd<str> for EnvKey {
 110     fn partial_cmp(&self, other: &str) -> Option<cmp::Ordering> {
 111         Some(self.cmp(&EnvKey::new(other)))
 112     }
 113 }
 114 impl PartialEq<str> for EnvKey {
 115     fn eq(&self, other: &str) -> bool {
 116         if self.os_string.len() != other.len() {
 117             false
 118         } else {
 119             self.cmp(&EnvKey::new(other)) == cmp::Ordering::Equal
 120         }
 121     }
 122 }
 123
 124 // Environment variable keys should preserve their original case even though
 125 // they are compared using a caseless string mapping.
 126 impl From<OsString> for EnvKey {
 127     fn from(k: OsString) -> Self {
 128         EnvKey { utf16: k.encode_wide().collect(), os_string: k }
 129     }
 130 }
 131
 132 impl From<EnvKey> for OsString {
 133     fn from(k: EnvKey) -> Self {
 134         k.os_string
 135     }
 136 }
 137
 138 impl From<&OsStr> for EnvKey {
 139     fn from(k: &OsStr) -> Self {
 140         Self::from(k.to_os_string())
 141     }
 142 }
 143
 144 impl AsRef<OsStr> for EnvKey {
 145     fn as_ref(&self) -> &OsStr {
 146         &self.os_string
 147     }
 148 }
 149
 150 fn ensure_no_nuls<T: AsRef<OsStr>>(str: T) -> io::Result<T> {
 151     if str.as_ref().encode_wide().any(|b| b == 0) {
 152         Err(io::Error::new_const(ErrorKind::InvalidInput, &"nul byte found in provided data"))
 153     } else {
 154         Ok(str)
 155     }
 156 }
 157
 158 pub struct Command {
 159     program: OsString,
 160     args: Vec<Arg>,
 161     env: CommandEnv,
 162     cwd: Option<OsString>,
 163     flags: u32,
 164     detach: bool, // not currently exposed in std::process
 165     stdin: Option<Stdio>,
 166     stdout: Option<Stdio>,
 167     stderr: Option<Stdio>,
 168     force_quotes_enabled: bool,
 169 }
 170
 171 pub enum Stdio {
 172     Inherit,
 173     Null,
 174     MakePipe,
 175     Handle(Handle),
 176 }
 177
 178 pub struct StdioPipes {
 179     pub stdin: Option<AnonPipe>,
 180     pub stdout: Option<AnonPipe>,
 181     pub stderr: Option<AnonPipe>,
 182 }
 183
 184 #[derive(Debug)]
 185 enum Arg {
 186     /// Add quotes (if needed)
 187     Regular(OsString),
 188     /// Append raw string without quoting
 189     Raw(OsString),
 190 }
 191
 192 impl Command {
 193     pub fn new(program: &OsStr) -> Command {
 194         Command {
 195             program: program.to_os_string(),
 196             args: Vec::new(),
 197             env: Default::default(),
 198             cwd: None,
 199             flags: 0,
 200             detach: false,
 201             stdin: None,
 202             stdout: None,
 203             stderr: None,
 204             force_quotes_enabled: false,
 205         }
 206     }
 207
 208     pub fn arg(&mut self, arg: &OsStr) {
 209         self.args.push(Arg::Regular(arg.to_os_string()))
 210     }
 211     pub fn env_mut(&mut self) -> &mut CommandEnv {
 212         &mut self.env
 213     }
 214     pub fn cwd(&mut self, dir: &OsStr) {
 215         self.cwd = Some(dir.to_os_string())
 216     }
 217     pub fn stdin(&mut self, stdin: Stdio) {
 218         self.stdin = Some(stdin);
 219     }
 220     pub fn stdout(&mut self, stdout: Stdio) {
 221         self.stdout = Some(stdout);
 222     }
 223     pub fn stderr(&mut self, stderr: Stdio) {
 224         self.stderr = Some(stderr);
 225     }
 226     pub fn creation_flags(&mut self, flags: u32) {
 227         self.flags = flags;
 228     }
 229
 230     pub fn force_quotes(&mut self, enabled: bool) {
 231         self.force_quotes_enabled = enabled;
 232     }
 233
 234     pub fn raw_arg(&mut self, command_str_to_append: &OsStr) {
 235         self.args.push(Arg::Raw(command_str_to_append.to_os_string()))
 236     }
 237
 238     pub fn get_program(&self) -> &OsStr {
 239         &self.program
 240     }
 241
 242     pub fn get_args(&self) -> CommandArgs<'_> {
 243         let iter = self.args.iter();
 244         CommandArgs { iter }
 245     }
 246
 247     pub fn get_envs(&self) -> CommandEnvs<'_> {
 248         self.env.iter()
 249     }
 250
 251     pub fn get_current_dir(&self) -> Option<&Path> {
 252         self.cwd.as_ref().map(|cwd| Path::new(cwd))
 253     }
 254
 255     pub fn spawn(
 256         &mut self,
 257         default: Stdio,
 258         needs_stdin: bool,
 259     ) -> io::Result<(Process, StdioPipes)> {
 260         let maybe_env = self.env.capture_if_changed();
 261
 262         let mut si = zeroed_startupinfo();
 263         si.cb = mem::size_of::<c::STARTUPINFO>() as c::DWORD;
 264         si.dwFlags = c::STARTF_USESTDHANDLES;
 265
 266         let child_paths = if let Some(env) = maybe_env.as_ref() {
 267             env.get(&EnvKey::new("PATH")).map(|s| s.as_os_str())
 268         } else {
 269             None
 270         };
 271         let program = resolve_exe(&self.program, || env::var_os("PATH"), child_paths)?;
 272         let mut cmd_str =
 273             make_command_line(program.as_os_str(), &self.args, self.force_quotes_enabled)?;
 274         cmd_str.push(0); // add null terminator
 275
 276         // stolen from the libuv code.
 277         let mut flags = self.flags | c::CREATE_UNICODE_ENVIRONMENT;
 278         if self.detach {
 279             flags |= c::DETACHED_PROCESS | c::CREATE_NEW_PROCESS_GROUP;
 280         }
 281
 282         let (envp, _data) = make_envp(maybe_env)?;
 283         let (dirp, _data) = make_dirp(self.cwd.as_ref())?;
 284         let mut pi = zeroed_process_information();
 285
 286         // Prepare all stdio handles to be inherited by the child. This
 287         // currently involves duplicating any existing ones with the ability to
 288         // be inherited by child processes. Note, however, that once an
 289         // inheritable handle is created, *any* spawned child will inherit that
 290         // handle. We only want our own child to inherit this handle, so we wrap
 291         // the remaining portion of this spawn in a mutex.
 292         //
 293         // For more information, msdn also has an article about this race:
 294         // https://support.microsoft.com/kb/315939
 295         static CREATE_PROCESS_LOCK: StaticMutex = StaticMutex::new();
 296
 297         let _guard = unsafe { CREATE_PROCESS_LOCK.lock() };
 298
 299         let mut pipes = StdioPipes { stdin: None, stdout: None, stderr: None };
 300         let null = Stdio::Null;
 301         let default_stdin = if needs_stdin { &default } else { &null };
 302         let stdin = self.stdin.as_ref().unwrap_or(default_stdin);
 303         let stdout = self.stdout.as_ref().unwrap_or(&default);
 304         let stderr = self.stderr.as_ref().unwrap_or(&default);
 305         let stdin = stdin.to_handle(c::STD_INPUT_HANDLE, &mut pipes.stdin)?;
 306         let stdout = stdout.to_handle(c::STD_OUTPUT_HANDLE, &mut pipes.stdout)?;
 307         let stderr = stderr.to_handle(c::STD_ERROR_HANDLE, &mut pipes.stderr)?;
 308         si.hStdInput = stdin.as_raw_handle();
 309         si.hStdOutput = stdout.as_raw_handle();
 310         si.hStdError = stderr.as_raw_handle();
 311
 312         let program = to_u16s(&program)?;
 313         unsafe {
 314             cvt(c::CreateProcessW(
 315                 program.as_ptr(),
 316                 cmd_str.as_mut_ptr(),
 317                 ptr::null_mut(),
 318                 ptr::null_mut(),
 319                 c::TRUE,
 320                 flags,
 321                 envp,
 322                 dirp,
 323                 &mut si,
 324                 &mut pi,
 325             ))
 326         }?;
 327
 328         // We close the thread handle because we don't care about keeping
 329         // the thread id valid, and we aren't keeping the thread handle
 330         // around to be able to close it later.
 331         unsafe {
 332             drop(Handle::from_raw_handle(pi.hThread));
 333
 334             Ok((Process { handle: Handle::from_raw_handle(pi.hProcess) }, pipes))
 335         }
 336     }
 337 }
 338
 339 impl fmt::Debug for Command {
 340     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 341         self.program.fmt(f)?;
 342         for arg in &self.args {
 343             f.write_str(" ")?;
 344             match arg {
 345                 Arg::Regular(s) => s.fmt(f),
 346                 Arg::Raw(s) => f.write_str(&s.to_string_lossy()),
 347             }?;
 348         }
 349         Ok(())
 350     }
 351 }
 352
 353 // Resolve `exe_path` to the executable name.
 354 //
 355 // * If the path is simply a file name then use the paths given by `search_paths` to find the executable.
 356 // * Otherwise use the `exe_path` as given.
 357 //
 358 // This function may also append `.exe` to the name. The rationale for doing so is as follows:
 359 //
 360 // It is a very strong convention that Windows executables have the `exe` extension.
 361 // In Rust, it is common to omit this extension.
 362 // Therefore this functions first assumes `.exe` was intended.
 363 // It falls back to the plain file name if a full path is given and the extension is omitted
 364 // or if only a file name is given and it already contains an extension.
 365 fn resolve_exe<'a>(
 366     exe_path: &'a OsStr,
 367     parent_paths: impl FnOnce() -> Option<OsString>,
 368     child_paths: Option<&OsStr>,
 369 ) -> io::Result<PathBuf> {
 370     // Early return if there is no filename.
 371     if exe_path.is_empty() || path::has_trailing_slash(exe_path) {
 372         return Err(io::Error::new_const(
 373             io::ErrorKind::InvalidInput,
 374             &"program path has no file name",
 375         ));
 376     }
 377     // Test if the file name has the `exe` extension.
 378     // This does a case-insensitive `ends_with`.
 379     let has_exe_suffix = if exe_path.len() >= EXE_SUFFIX.len() {
 380         exe_path.bytes()[exe_path.len() - EXE_SUFFIX.len()..]
 381             .eq_ignore_ascii_case(EXE_SUFFIX.as_bytes())
 382     } else {
 383         false
 384     };
 385
 386     // If `exe_path` is an absolute path or a sub-path then don't search `PATH` for it.
 387     if !path::is_file_name(exe_path) {
 388         if has_exe_suffix {
 389             // The application name is a path to a `.exe` file.
 390             // Let `CreateProcessW` figure out if it exists or not.
 391             return Ok(exe_path.into());
 392         }
 393         let mut path = PathBuf::from(exe_path);
 394
 395         // Append `.exe` if not already there.
 396         path = path::append_suffix(path, EXE_SUFFIX.as_ref());
 397         if path.try_exists().unwrap_or(false) {
 398             return Ok(path);
 399         } else {
 400             // It's ok to use `set_extension` here because the intent is to
 401             // remove the extension that was just added.
 402             path.set_extension("");
 403             return Ok(path);
 404         }
 405     } else {
 406         ensure_no_nuls(exe_path)?;
 407         // From the `CreateProcessW` docs:
 408         // > If the file name does not contain an extension, .exe is appended.
 409         // Note that this rule only applies when searching paths.
 410         let has_extension = exe_path.bytes().contains(&b'.');
 411
 412         // Search the directories given by `search_paths`.
 413         let result = search_paths(parent_paths, child_paths, |mut path| {
 414             path.push(&exe_path);
 415             if !has_extension {
 416                 path.set_extension(EXE_EXTENSION);
 417             }
 418             if let Ok(true) = path.try_exists() { Some(path) } else { None }
 419         });
 420         if let Some(path) = result {
 421             return Ok(path);
 422         }
 423     }
 424     // If we get here then the executable cannot be found.
 425     Err(io::Error::new_const(io::ErrorKind::NotFound, &"program not found"))
 426 }
 427
 428 // Calls `f` for every path that should be used to find an executable.
 429 // Returns once `f` returns the path to an executable or all paths have been searched.
 430 fn search_paths<Paths, Exists>(
 431     parent_paths: Paths,
 432     child_paths: Option<&OsStr>,
 433     mut exists: Exists,
 434 ) -> Option<PathBuf>
 435 where
 436     Paths: FnOnce() -> Option<OsString>,
 437     Exists: FnMut(PathBuf) -> Option<PathBuf>,
 438 {
 439     // 1. Child paths
 440     // This is for consistency with Rust's historic behaviour.
 441     if let Some(paths) = child_paths {
 442         for path in env::split_paths(paths).filter(|p| !p.as_os_str().is_empty()) {
 443             if let Some(path) = exists(path) {
 444                 return Some(path);
 445             }
 446         }
 447     }
 448
 449     // 2. Application path
 450     if let Ok(mut app_path) = env::current_exe() {
 451         app_path.pop();
 452         if let Some(path) = exists(app_path) {
 453             return Some(path);
 454         }
 455     }
 456
 457     // 3 & 4. System paths
 458     // SAFETY: This uses `fill_utf16_buf` to safely call the OS functions.
 459     unsafe {
 460         if let Ok(Some(path)) = super::fill_utf16_buf(
 461             |buf, size| c::GetSystemDirectoryW(buf, size),
 462             |buf| exists(PathBuf::from(OsString::from_wide(buf))),
 463         ) {
 464             return Some(path);
 465         }
 466         #[cfg(not(target_vendor = "uwp"))]
 467         {
 468             if let Ok(Some(path)) = super::fill_utf16_buf(
 469                 |buf, size| c::GetWindowsDirectoryW(buf, size),
 470                 |buf| exists(PathBuf::from(OsString::from_wide(buf))),
 471             ) {
 472                 return Some(path);
 473             }
 474         }
 475     }
 476
 477     // 5. Parent paths
 478     if let Some(parent_paths) = parent_paths() {
 479         for path in env::split_paths(&parent_paths).filter(|p| !p.as_os_str().is_empty()) {
 480             if let Some(path) = exists(path) {
 481                 return Some(path);
 482             }
 483         }
 484     }
 485     None
 486 }
 487
 488 impl Stdio {
 489     fn to_handle(&self, stdio_id: c::DWORD, pipe: &mut Option<AnonPipe>) -> io::Result<Handle> {
 490         match *self {
 491             // If no stdio handle is available, then inherit means that it
 492             // should still be unavailable so propagate the
 493             // INVALID_HANDLE_VALUE.
 494             Stdio::Inherit => match stdio::get_handle(stdio_id) {
 495                 Ok(io) => unsafe {
 496                     let io = Handle::from_raw_handle(io);
 497                     let ret = io.duplicate(0, true, c::DUPLICATE_SAME_ACCESS);
 498                     io.into_raw_handle();
 499                     ret
 500                 },
 501                 Err(..) => unsafe { Ok(Handle::from_raw_handle(c::INVALID_HANDLE_VALUE)) },
 502             },
 503
 504             Stdio::MakePipe => {
 505                 let ours_readable = stdio_id != c::STD_INPUT_HANDLE;
 506                 let pipes = pipe::anon_pipe(ours_readable, true)?;
 507                 *pipe = Some(pipes.ours);
 508                 Ok(pipes.theirs.into_handle())
 509             }
 510
 511             Stdio::Handle(ref handle) => handle.duplicate(0, true, c::DUPLICATE_SAME_ACCESS),
 512
 513             // Open up a reference to NUL with appropriate read/write
 514             // permissions as well as the ability to be inherited to child
 515             // processes (as this is about to be inherited).
 516             Stdio::Null => {
 517                 let size = mem::size_of::<c::SECURITY_ATTRIBUTES>();
 518                 let mut sa = c::SECURITY_ATTRIBUTES {
 519                     nLength: size as c::DWORD,
 520                     lpSecurityDescriptor: ptr::null_mut(),
 521                     bInheritHandle: 1,
 522                 };
 523                 let mut opts = OpenOptions::new();
 524                 opts.read(stdio_id == c::STD_INPUT_HANDLE);
 525                 opts.write(stdio_id != c::STD_INPUT_HANDLE);
 526                 opts.security_attributes(&mut sa);
 527                 File::open(Path::new("NUL"), &opts).map(|file| file.into_inner())
 528             }
 529         }
 530     }
 531 }
 532
 533 impl From<AnonPipe> for Stdio {
 534     fn from(pipe: AnonPipe) -> Stdio {
 535         Stdio::Handle(pipe.into_handle())
 536     }
 537 }
 538
 539 impl From<File> for Stdio {
 540     fn from(file: File) -> Stdio {
 541         Stdio::Handle(file.into_inner())
 542     }
 543 }
 544
 545 ////////////////////////////////////////////////////////////////////////////////
 546 // Processes
 547 ////////////////////////////////////////////////////////////////////////////////
 548
 549 /// A value representing a child process.
 550 ///
 551 /// The lifetime of this value is linked to the lifetime of the actual
 552 /// process - the Process destructor calls self.finish() which waits
 553 /// for the process to terminate.
 554 pub struct Process {
 555     handle: Handle,
 556 }
 557
 558 impl Process {
 559     pub fn kill(&mut self) -> io::Result<()> {
 560         cvt(unsafe { c::TerminateProcess(self.handle.as_raw_handle(), 1) })?;
 561         Ok(())
 562     }
 563
 564     pub fn id(&self) -> u32 {
 565         unsafe { c::GetProcessId(self.handle.as_raw_handle()) as u32 }
 566     }
 567
 568     pub fn wait(&mut self) -> io::Result<ExitStatus> {
 569         unsafe {
 570             let res = c::WaitForSingleObject(self.handle.as_raw_handle(), c::INFINITE);
 571             if res != c::WAIT_OBJECT_0 {
 572                 return Err(Error::last_os_error());
 573             }
 574             let mut status = 0;
 575             cvt(c::GetExitCodeProcess(self.handle.as_raw_handle(), &mut status))?;
 576             Ok(ExitStatus(status))
 577         }
 578     }
 579
 580     pub fn try_wait(&mut self) -> io::Result<Option<ExitStatus>> {
 581         unsafe {
 582             match c::WaitForSingleObject(self.handle.as_raw_handle(), 0) {
 583                 c::WAIT_OBJECT_0 => {}
 584                 c::WAIT_TIMEOUT => {
 585                     return Ok(None);
 586                 }
 587                 _ => return Err(io::Error::last_os_error()),
 588             }
 589             let mut status = 0;
 590             cvt(c::GetExitCodeProcess(self.handle.as_raw_handle(), &mut status))?;
 591             Ok(Some(ExitStatus(status)))
 592         }
 593     }
 594
 595     pub fn handle(&self) -> &Handle {
 596         &self.handle
 597     }
 598
 599     pub fn into_handle(self) -> Handle {
 600         self.handle
 601     }
 602 }
 603
 604 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
 605 pub struct ExitStatus(c::DWORD);
 606
 607 impl ExitStatus {
 608     pub fn exit_ok(&self) -> Result<(), ExitStatusError> {
 609         match NonZeroDWORD::try_from(self.0) {
 610             /* was nonzero */ Ok(failure) => Err(ExitStatusError(failure)),
 611             /* was zero, couldn't convert */ Err(_) => Ok(()),
 612         }
 613     }
 614     pub fn code(&self) -> Option<i32> {
 615         Some(self.0 as i32)
 616     }
 617 }
 618
 619 /// Converts a raw `c::DWORD` to a type-safe `ExitStatus` by wrapping it without copying.
 620 impl From<c::DWORD> for ExitStatus {
 621     fn from(u: c::DWORD) -> ExitStatus {
 622         ExitStatus(u)
 623     }
 624 }
 625
 626 impl fmt::Display for ExitStatus {
 627     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 628         // Windows exit codes with the high bit set typically mean some form of
 629         // unhandled exception or warning. In this scenario printing the exit
 630         // code in decimal doesn't always make sense because it's a very large
 631         // and somewhat gibberish number. The hex code is a bit more
 632         // recognizable and easier to search for, so print that.
 633         if self.0 & 0x80000000 != 0 {
 634             write!(f, "exit code: {:#x}", self.0)
 635         } else {
 636             write!(f, "exit code: {}", self.0)
 637         }
 638     }
 639 }
 640
 641 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
 642 pub struct ExitStatusError(c::NonZeroDWORD);
 643
 644 impl Into<ExitStatus> for ExitStatusError {
 645     fn into(self) -> ExitStatus {
 646         ExitStatus(self.0.into())
 647     }
 648 }
 649
 650 impl ExitStatusError {
 651     pub fn code(self) -> Option<NonZeroI32> {
 652         Some((u32::from(self.0) as i32).try_into().unwrap())
 653     }
 654 }
 655
 656 #[derive(PartialEq, Eq, Clone, Copy, Debug)]
 657 pub struct ExitCode(c::DWORD);
 658
 659 impl ExitCode {
 660     pub const SUCCESS: ExitCode = ExitCode(EXIT_SUCCESS as _);
 661     pub const FAILURE: ExitCode = ExitCode(EXIT_FAILURE as _);
 662
 663     #[inline]
 664     pub fn as_i32(&self) -> i32 {
 665         self.0 as i32
 666     }
 667 }
 668
 669 fn zeroed_startupinfo() -> c::STARTUPINFO {
 670     c::STARTUPINFO {
 671         cb: 0,
 672         lpReserved: ptr::null_mut(),
 673         lpDesktop: ptr::null_mut(),
 674         lpTitle: ptr::null_mut(),
 675         dwX: 0,
 676         dwY: 0,
 677         dwXSize: 0,
 678         dwYSize: 0,
 679         dwXCountChars: 0,
 680         dwYCountCharts: 0,
 681         dwFillAttribute: 0,
 682         dwFlags: 0,
 683         wShowWindow: 0,
 684         cbReserved2: 0,
 685         lpReserved2: ptr::null_mut(),
 686         hStdInput: c::INVALID_HANDLE_VALUE,
 687         hStdOutput: c::INVALID_HANDLE_VALUE,
 688         hStdError: c::INVALID_HANDLE_VALUE,
 689     }
 690 }
 691
 692 fn zeroed_process_information() -> c::PROCESS_INFORMATION {
 693     c::PROCESS_INFORMATION {
 694         hProcess: ptr::null_mut(),
 695         hThread: ptr::null_mut(),
 696         dwProcessId: 0,
 697         dwThreadId: 0,
 698     }
 699 }
 700
 701 enum Quote {
 702     // Every arg is quoted
 703     Always,
 704     // Whitespace and empty args are quoted
 705     Auto,
 706     // Arg appended without any changes (#29494)
 707     Never,
 708 }
 709
 710 // Produces a wide string *without terminating null*; returns an error if
 711 // `prog` or any of the `args` contain a nul.
 712 fn make_command_line(prog: &OsStr, args: &[Arg], force_quotes: bool) -> io::Result<Vec<u16>> {
 713     // Encode the command and arguments in a command line string such
 714     // that the spawned process may recover them using CommandLineToArgvW.
 715     let mut cmd: Vec<u16> = Vec::new();
 716
 717     // CreateFileW has special handling for .bat and .cmd files, which means we
 718     // need to add an extra pair of quotes surrounding the whole command line
 719     // so they are properly passed on to the script.
 720     // See issue #91991.
 721     let is_batch_file = Path::new(prog)
 722         .extension()
 723         .map(|ext| ext.eq_ignore_ascii_case("cmd") || ext.eq_ignore_ascii_case("bat"))
 724         .unwrap_or(false);
 725     if is_batch_file {
 726         cmd.push(b'"' as u16);
 727     }
 728
 729     // Always quote the program name so CreateProcess doesn't interpret args as
 730     // part of the name if the binary wasn't found first time.
 731     append_arg(&mut cmd, prog, Quote::Always)?;
 732     for arg in args {
 733         cmd.push(' ' as u16);
 734         let (arg, quote) = match arg {
 735             Arg::Regular(arg) => (arg, if force_quotes { Quote::Always } else { Quote::Auto }),
 736             Arg::Raw(arg) => (arg, Quote::Never),
 737         };
 738         append_arg(&mut cmd, arg, quote)?;
 739     }
 740     if is_batch_file {
 741         cmd.push(b'"' as u16);
 742     }
 743     return Ok(cmd);
 744
 745     fn append_arg(cmd: &mut Vec<u16>, arg: &OsStr, quote: Quote) -> io::Result<()> {
 746         // If an argument has 0 characters then we need to quote it to ensure
 747         // that it actually gets passed through on the command line or otherwise
 748         // it will be dropped entirely when parsed on the other end.
 749         ensure_no_nuls(arg)?;
 750         let arg_bytes = &arg.as_inner().inner.as_inner();
 751         let (quote, escape) = match quote {
 752             Quote::Always => (true, true),
 753             Quote::Auto => {
 754                 (arg_bytes.iter().any(|c| *c == b' ' || *c == b'\t') || arg_bytes.is_empty(), true)
 755             }
 756             Quote::Never => (false, false),
 757         };
 758         if quote {
 759             cmd.push('"' as u16);
 760         }
 761
 762         let mut backslashes: usize = 0;
 763         for x in arg.encode_wide() {
 764             if escape {
 765                 if x == '\\' as u16 {
 766                     backslashes += 1;
 767                 } else {
 768                     if x == '"' as u16 {
 769                         // Add n+1 backslashes to total 2n+1 before internal '"'.
 770                         cmd.extend((0..=backslashes).map(|_| '\\' as u16));
 771                     }
 772                     backslashes = 0;
 773                 }
 774             }
 775             cmd.push(x);
 776         }
 777
 778         if quote {
 779             // Add n backslashes to total 2n before ending '"'.
 780             cmd.extend((0..backslashes).map(|_| '\\' as u16));
 781             cmd.push('"' as u16);
 782         }
 783         Ok(())
 784     }
 785 }
 786
 787 fn make_envp(maybe_env: Option<BTreeMap<EnvKey, OsString>>) -> io::Result<(*mut c_void, Vec<u16>)> {
 788     // On Windows we pass an "environment block" which is not a char**, but
 789     // rather a concatenation of null-terminated k=v\0 sequences, with a final
 790     // \0 to terminate.
 791     if let Some(env) = maybe_env {
 792         let mut blk = Vec::new();
 793
 794         // If there are no environment variables to set then signal this by
 795         // pushing a null.
 796         if env.is_empty() {
 797             blk.push(0);
 798         }
 799
 800         for (k, v) in env {
 801             ensure_no_nuls(k.os_string)?;
 802             blk.extend(k.utf16);
 803             blk.push('=' as u16);
 804             blk.extend(ensure_no_nuls(v)?.encode_wide());
 805             blk.push(0);
 806         }
 807         blk.push(0);
 808         Ok((blk.as_mut_ptr() as *mut c_void, blk))
 809     } else {
 810         Ok((ptr::null_mut(), Vec::new()))
 811     }
 812 }
 813
 814 fn make_dirp(d: Option<&OsString>) -> io::Result<(*const u16, Vec<u16>)> {
 815     match d {
 816         Some(dir) => {
 817             let mut dir_str: Vec<u16> = ensure_no_nuls(dir)?.encode_wide().collect();
 818             dir_str.push(0);
 819             Ok((dir_str.as_ptr(), dir_str))
 820         }
 821         None => Ok((ptr::null(), Vec::new())),
 822     }
 823 }
 824
 825 pub struct CommandArgs<'a> {
 826     iter: crate::slice::Iter<'a, Arg>,
 827 }
 828
 829 impl<'a> Iterator for CommandArgs<'a> {
 830     type Item = &'a OsStr;
 831     fn next(&mut self) -> Option<&'a OsStr> {
 832         self.iter.next().map(|arg| match arg {
 833             Arg::Regular(s) | Arg::Raw(s) => s.as_ref(),
 834         })
 835     }
 836     fn size_hint(&self) -> (usize, Option<usize>) {
 837         self.iter.size_hint()
 838     }
 839 }
 840
 841 impl<'a> ExactSizeIterator for CommandArgs<'a> {
 842     fn len(&self) -> usize {
 843         self.iter.len()
 844     }
 845     fn is_empty(&self) -> bool {
 846         self.iter.is_empty()
 847     }
 848 }
 849
 850 impl<'a> fmt::Debug for CommandArgs<'a> {
 851     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 852         f.debug_list().entries(self.iter.clone()).finish()
 853     }
 854 }