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

   1 //! Windows-specific extensions to primitives in the [`std::process`] module.
   2 //!
   3 //! [`std::process`]: crate::process
   4
   5 #![stable(feature = "process_extensions", since = "1.2.0")]
   6
   7 use crate::ffi::OsStr;
   8 use crate::os::windows::io::{
   9     AsHandle, AsRawHandle, BorrowedHandle, FromRawHandle, IntoRawHandle, OwnedHandle, RawHandle,
  10 };
  11 use crate::process;
  12 use crate::sealed::Sealed;
  13 use crate::sys;
  14 use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner};
  15
  16 #[stable(feature = "process_extensions", since = "1.2.0")]
  17 impl FromRawHandle for process::Stdio {
  18     unsafe fn from_raw_handle(handle: RawHandle) -> process::Stdio {
  19         let handle = sys::handle::Handle::from_raw_handle(handle as *mut _);
  20         let io = sys::process::Stdio::Handle(handle);
  21         process::Stdio::from_inner(io)
  22     }
  23 }
  24
  25 #[unstable(feature = "io_safety", issue = "87074")]
  26 impl From<OwnedHandle> for process::Stdio {
  27     fn from(handle: OwnedHandle) -> process::Stdio {
  28         let handle = sys::handle::Handle::from_inner(handle);
  29         let io = sys::process::Stdio::Handle(handle);
  30         process::Stdio::from_inner(io)
  31     }
  32 }
  33
  34 #[stable(feature = "process_extensions", since = "1.2.0")]
  35 impl AsRawHandle for process::Child {
  36     #[inline]
  37     fn as_raw_handle(&self) -> RawHandle {
  38         self.as_inner().handle().as_raw_handle() as *mut _
  39     }
  40 }
  41
  42 #[unstable(feature = "io_safety", issue = "87074")]
  43 impl AsHandle for process::Child {
  44     #[inline]
  45     fn as_handle(&self) -> BorrowedHandle<'_> {
  46         self.as_inner().handle().as_handle()
  47     }
  48 }
  49
  50 #[stable(feature = "into_raw_os", since = "1.4.0")]
  51 impl IntoRawHandle for process::Child {
  52     fn into_raw_handle(self) -> RawHandle {
  53         self.into_inner().into_handle().into_raw_handle() as *mut _
  54     }
  55 }
  56
  57 #[unstable(feature = "io_safety", issue = "87074")]
  58 impl From<process::Child> for OwnedHandle {
  59     fn from(child: process::Child) -> OwnedHandle {
  60         child.into_inner().into_handle().into_inner()
  61     }
  62 }
  63
  64 #[stable(feature = "process_extensions", since = "1.2.0")]
  65 impl AsRawHandle for process::ChildStdin {
  66     #[inline]
  67     fn as_raw_handle(&self) -> RawHandle {
  68         self.as_inner().handle().as_raw_handle() as *mut _
  69     }
  70 }
  71
  72 #[stable(feature = "process_extensions", since = "1.2.0")]
  73 impl AsRawHandle for process::ChildStdout {
  74     #[inline]
  75     fn as_raw_handle(&self) -> RawHandle {
  76         self.as_inner().handle().as_raw_handle() as *mut _
  77     }
  78 }
  79
  80 #[stable(feature = "process_extensions", since = "1.2.0")]
  81 impl AsRawHandle for process::ChildStderr {
  82     #[inline]
  83     fn as_raw_handle(&self) -> RawHandle {
  84         self.as_inner().handle().as_raw_handle() as *mut _
  85     }
  86 }
  87
  88 #[stable(feature = "into_raw_os", since = "1.4.0")]
  89 impl IntoRawHandle for process::ChildStdin {
  90     fn into_raw_handle(self) -> RawHandle {
  91         self.into_inner().into_handle().into_raw_handle() as *mut _
  92     }
  93 }
  94
  95 #[stable(feature = "into_raw_os", since = "1.4.0")]
  96 impl IntoRawHandle for process::ChildStdout {
  97     fn into_raw_handle(self) -> RawHandle {
  98         self.into_inner().into_handle().into_raw_handle() as *mut _
  99     }
 100 }
 101
 102 #[stable(feature = "into_raw_os", since = "1.4.0")]
 103 impl IntoRawHandle for process::ChildStderr {
 104     fn into_raw_handle(self) -> RawHandle {
 105         self.into_inner().into_handle().into_raw_handle() as *mut _
 106     }
 107 }
 108
 109 /// Windows-specific extensions to [`process::ExitStatus`].
 110 ///
 111 /// This trait is sealed: it cannot be implemented outside the standard library.
 112 /// This is so that future additional methods are not breaking changes.
 113 #[stable(feature = "exit_status_from", since = "1.12.0")]
 114 pub trait ExitStatusExt: Sealed {
 115     /// Creates a new `ExitStatus` from the raw underlying `u32` return value of
 116     /// a process.
 117     #[stable(feature = "exit_status_from", since = "1.12.0")]
 118     fn from_raw(raw: u32) -> Self;
 119 }
 120
 121 #[stable(feature = "exit_status_from", since = "1.12.0")]
 122 impl ExitStatusExt for process::ExitStatus {
 123     fn from_raw(raw: u32) -> Self {
 124         process::ExitStatus::from_inner(From::from(raw))
 125     }
 126 }
 127
 128 /// Windows-specific extensions to the [`process::Command`] builder.
 129 ///
 130 /// This trait is sealed: it cannot be implemented outside the standard library.
 131 /// This is so that future additional methods are not breaking changes.
 132 #[stable(feature = "windows_process_extensions", since = "1.16.0")]
 133 pub trait CommandExt: Sealed {
 134     /// Sets the [process creation flags][1] to be passed to `CreateProcess`.
 135     ///
 136     /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`.
 137     ///
 138     /// [1]: https://docs.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
 139     #[stable(feature = "windows_process_extensions", since = "1.16.0")]
 140     fn creation_flags(&mut self, flags: u32) -> &mut process::Command;
 141
 142     /// Forces all arguments to be wrapped in quote (`"`) characters.
 143     ///
 144     /// This is useful for passing arguments to [MSYS2/Cygwin][1] based
 145     /// executables: these programs will expand unquoted arguments containing
 146     /// wildcard characters (`?` and `*`) by searching for any file paths
 147     /// matching the wildcard pattern.
 148     ///
 149     /// Adding quotes has no effect when passing arguments to programs
 150     /// that use [msvcrt][2]. This includes programs built with both
 151     /// MinGW and MSVC.
 152     ///
 153     /// [1]: <https://github.com/msys2/MSYS2-packages/issues/2176>
 154     /// [2]: <https://msdn.microsoft.com/en-us/library/17w5ykft.aspx>
 155     #[unstable(feature = "windows_process_extensions_force_quotes", issue = "82227")]
 156     fn force_quotes(&mut self, enabled: bool) -> &mut process::Command;
 157
 158     /// Append literal text to the command line without any quoting or escaping.
 159     ///
 160     /// This is useful for passing arguments to `cmd.exe /c`, which doesn't follow
 161     /// `CommandLineToArgvW` escaping rules.
 162     #[unstable(feature = "windows_process_extensions_raw_arg", issue = "29494")]
 163     fn raw_arg<S: AsRef<OsStr>>(&mut self, text_to_append_as_is: S) -> &mut process::Command;
 164 }
 165
 166 #[stable(feature = "windows_process_extensions", since = "1.16.0")]
 167 impl CommandExt for process::Command {
 168     fn creation_flags(&mut self, flags: u32) -> &mut process::Command {
 169         self.as_inner_mut().creation_flags(flags);
 170         self
 171     }
 172
 173     fn force_quotes(&mut self, enabled: bool) -> &mut process::Command {
 174         self.as_inner_mut().force_quotes(enabled);
 175         self
 176     }
 177
 178     fn raw_arg<S: AsRef<OsStr>>(&mut self, raw_text: S) -> &mut process::Command {
 179         self.as_inner_mut().raw_arg(raw_text.as_ref());
 180         self
 181     }
 182 }