std/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
7use crate::ffi::{OsStr, c_void};
8use crate::mem::MaybeUninit;
9use crate::os::windows::io::{
10 AsHandle, AsRawHandle, BorrowedHandle, FromRawHandle, IntoRawHandle, OwnedHandle, RawHandle,
11};
12use crate::sys::{AsInner, AsInnerMut, FromInner, IntoInner};
13use crate::{io, marker, process, ptr, sys};
14
15#[stable(feature = "process_extensions", since = "1.2.0")]
16impl FromRawHandle for process::Stdio {
17 unsafe fn from_raw_handle(handle: RawHandle) -> process::Stdio {
18 let handle = unsafe { sys::handle::Handle::from_raw_handle(handle as *mut _) };
19 let io = sys::process::Stdio::Handle(handle);
20 process::Stdio::from_inner(io)
21 }
22}
23
24#[stable(feature = "io_safety", since = "1.63.0")]
25impl From<OwnedHandle> for process::Stdio {
26 /// Takes ownership of a handle and returns a [`Stdio`](process::Stdio)
27 /// that can attach a stream to it.
28 fn from(handle: OwnedHandle) -> process::Stdio {
29 let handle = sys::handle::Handle::from_inner(handle);
30 let io = sys::process::Stdio::Handle(handle);
31 process::Stdio::from_inner(io)
32 }
33}
34
35#[stable(feature = "process_extensions", since = "1.2.0")]
36impl AsRawHandle for process::Child {
37 #[inline]
38 fn as_raw_handle(&self) -> RawHandle {
39 self.as_inner().handle().as_raw_handle() as *mut _
40 }
41}
42
43#[stable(feature = "io_safety", since = "1.63.0")]
44impl AsHandle for process::Child {
45 #[inline]
46 fn as_handle(&self) -> BorrowedHandle<'_> {
47 self.as_inner().handle().as_handle()
48 }
49}
50
51#[stable(feature = "into_raw_os", since = "1.4.0")]
52impl IntoRawHandle for process::Child {
53 fn into_raw_handle(self) -> RawHandle {
54 self.into_inner().into_handle().into_raw_handle() as *mut _
55 }
56}
57
58#[stable(feature = "io_safety", since = "1.63.0")]
59impl From<process::Child> for OwnedHandle {
60 /// Takes ownership of a [`Child`](process::Child)'s process handle.
61 fn from(child: process::Child) -> OwnedHandle {
62 child.into_inner().into_handle().into_inner()
63 }
64}
65
66#[stable(feature = "process_extensions", since = "1.2.0")]
67impl AsRawHandle for process::ChildStdin {
68 #[inline]
69 fn as_raw_handle(&self) -> RawHandle {
70 self.as_inner().handle().as_raw_handle() as *mut _
71 }
72}
73
74#[stable(feature = "process_extensions", since = "1.2.0")]
75impl AsRawHandle for process::ChildStdout {
76 #[inline]
77 fn as_raw_handle(&self) -> RawHandle {
78 self.as_inner().handle().as_raw_handle() as *mut _
79 }
80}
81
82#[stable(feature = "process_extensions", since = "1.2.0")]
83impl AsRawHandle for process::ChildStderr {
84 #[inline]
85 fn as_raw_handle(&self) -> RawHandle {
86 self.as_inner().handle().as_raw_handle() as *mut _
87 }
88}
89
90#[stable(feature = "into_raw_os", since = "1.4.0")]
91impl IntoRawHandle for process::ChildStdin {
92 fn into_raw_handle(self) -> RawHandle {
93 self.into_inner().into_handle().into_raw_handle() as *mut _
94 }
95}
96
97#[stable(feature = "into_raw_os", since = "1.4.0")]
98impl IntoRawHandle for process::ChildStdout {
99 fn into_raw_handle(self) -> RawHandle {
100 self.into_inner().into_handle().into_raw_handle() as *mut _
101 }
102}
103
104#[stable(feature = "into_raw_os", since = "1.4.0")]
105impl IntoRawHandle for process::ChildStderr {
106 fn into_raw_handle(self) -> RawHandle {
107 self.into_inner().into_handle().into_raw_handle() as *mut _
108 }
109}
110
111/// Creates a `ChildStdin` from the provided `OwnedHandle`.
112///
113/// The provided handle must be asynchronous, as reading and
114/// writing from and to it is implemented using asynchronous APIs.
115#[stable(feature = "child_stream_from_fd", since = "1.74.0")]
116impl From<OwnedHandle> for process::ChildStdin {
117 fn from(handle: OwnedHandle) -> process::ChildStdin {
118 let handle = sys::handle::Handle::from_inner(handle);
119 let pipe = sys::process::ChildPipe::from_inner(handle);
120 process::ChildStdin::from_inner(pipe)
121 }
122}
123
124/// Creates a `ChildStdout` from the provided `OwnedHandle`.
125///
126/// The provided handle must be asynchronous, as reading and
127/// writing from and to it is implemented using asynchronous APIs.
128#[stable(feature = "child_stream_from_fd", since = "1.74.0")]
129impl From<OwnedHandle> for process::ChildStdout {
130 fn from(handle: OwnedHandle) -> process::ChildStdout {
131 let handle = sys::handle::Handle::from_inner(handle);
132 let pipe = sys::process::ChildPipe::from_inner(handle);
133 process::ChildStdout::from_inner(pipe)
134 }
135}
136
137/// Creates a `ChildStderr` from the provided `OwnedHandle`.
138///
139/// The provided handle must be asynchronous, as reading and
140/// writing from and to it is implemented using asynchronous APIs.
141#[stable(feature = "child_stream_from_fd", since = "1.74.0")]
142impl From<OwnedHandle> for process::ChildStderr {
143 fn from(handle: OwnedHandle) -> process::ChildStderr {
144 let handle = sys::handle::Handle::from_inner(handle);
145 let pipe = sys::process::ChildPipe::from_inner(handle);
146 process::ChildStderr::from_inner(pipe)
147 }
148}
149
150/// Windows-specific extensions to [`process::ExitStatus`].
151///
152/// This trait is sealed: it cannot be implemented outside the standard library.
153/// This is so that future additional methods are not breaking changes.
154#[stable(feature = "exit_status_from", since = "1.12.0")]
155pub impl(self) trait ExitStatusExt {
156 /// Creates a new `ExitStatus` from the raw underlying `u32` return value of
157 /// a process.
158 #[stable(feature = "exit_status_from", since = "1.12.0")]
159 fn from_raw(raw: u32) -> Self;
160}
161
162#[stable(feature = "exit_status_from", since = "1.12.0")]
163impl ExitStatusExt for process::ExitStatus {
164 fn from_raw(raw: u32) -> Self {
165 process::ExitStatus::from_inner(From::from(raw))
166 }
167}
168
169/// Windows-specific extensions to the [`process::Command`] builder.
170///
171/// This trait is sealed: it cannot be implemented outside the standard library.
172/// This is so that future additional methods are not breaking changes.
173#[stable(feature = "windows_process_extensions", since = "1.16.0")]
174pub impl(self) trait CommandExt {
175 /// Sets the [process creation flags][1] to be passed to `CreateProcess`.
176 ///
177 /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`.
178 ///
179 /// [1]: https://docs.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
180 #[stable(feature = "windows_process_extensions", since = "1.16.0")]
181 fn creation_flags(&mut self, flags: u32) -> &mut process::Command;
182
183 /// Sets the field `wShowWindow` of [STARTUPINFO][1] that is passed to `CreateProcess`.
184 /// Allowed values are the ones listed in
185 /// <https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-showwindow>
186 ///
187 /// [1]: <https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfow>
188 #[unstable(feature = "windows_process_extensions_show_window", issue = "127544")]
189 fn show_window(&mut self, cmd_show: u16) -> &mut process::Command;
190
191 /// Forces all arguments to be wrapped in quote (`"`) characters.
192 ///
193 /// This is useful for passing arguments to [MSYS2/Cygwin][1] based
194 /// executables: these programs will expand unquoted arguments containing
195 /// wildcard characters (`?` and `*`) by searching for any file paths
196 /// matching the wildcard pattern.
197 ///
198 /// Adding quotes has no effect when passing arguments to programs
199 /// that use [msvcrt][2]. This includes programs built with both
200 /// MinGW and MSVC.
201 ///
202 /// [1]: <https://github.com/msys2/MSYS2-packages/issues/2176>
203 /// [2]: <https://msdn.microsoft.com/en-us/library/17w5ykft.aspx>
204 #[unstable(feature = "windows_process_extensions_force_quotes", issue = "82227")]
205 fn force_quotes(&mut self, enabled: bool) -> &mut process::Command;
206
207 /// Append literal text to the command line without any quoting or escaping.
208 ///
209 /// This is useful for passing arguments to applications that don't follow
210 /// the standard C run-time escaping rules, such as `cmd.exe /c`.
211 ///
212 /// # Batch files
213 ///
214 /// Note the `cmd /c` command line has slightly different escaping rules than batch files
215 /// themselves. If possible, it may be better to write complex arguments to a temporary
216 /// `.bat` file, with appropriate escaping, and simply run that using:
217 ///
218 /// ```no_run
219 /// # use std::process::Command;
220 /// # let temp_bat_file = "";
221 /// # #[allow(unused)]
222 /// let output = Command::new("cmd").args(["/c", &format!("\"{temp_bat_file}\"")]).output();
223 /// ```
224 ///
225 /// # Example
226 ///
227 /// Run a batch script using both trusted and untrusted arguments.
228 ///
229 /// ```no_run
230 /// #[cfg(windows)]
231 /// // `my_script_path` is a path to known bat file.
232 /// // `user_name` is an untrusted name given by the user.
233 /// fn run_script(
234 /// my_script_path: &str,
235 /// user_name: &str,
236 /// ) -> Result<std::process::Output, std::io::Error> {
237 /// use std::io::{Error, ErrorKind};
238 /// use std::os::windows::process::CommandExt;
239 /// use std::process::Command;
240 ///
241 /// // Create the command line, making sure to quote the script path.
242 /// // This assumes the fixed arguments have been tested to work with the script we're using.
243 /// let mut cmd_args = format!(r#""{my_script_path}" "--features=[a,b,c]""#);
244 ///
245 /// // Make sure the user name is safe. In particular we need to be
246 /// // cautious of ascii symbols that cmd may interpret specially.
247 /// // Here we only allow alphanumeric characters.
248 /// if !user_name.chars().all(|c| c.is_alphanumeric()) {
249 /// return Err(Error::new(ErrorKind::InvalidInput, "invalid user name"));
250 /// }
251 ///
252 /// // now we have validated the user name, let's add that too.
253 /// cmd_args.push_str(" --user ");
254 /// cmd_args.push_str(user_name);
255 ///
256 /// // call cmd.exe and return the output
257 /// Command::new("cmd.exe")
258 /// .arg("/c")
259 /// // surround the entire command in an extra pair of quotes, as required by cmd.exe.
260 /// .raw_arg(&format!("\"{cmd_args}\""))
261 /// .output()
262 /// }
263 /// ````
264 #[stable(feature = "windows_process_extensions_raw_arg", since = "1.62.0")]
265 fn raw_arg<S: AsRef<OsStr>>(&mut self, text_to_append_as_is: S) -> &mut process::Command;
266
267 /// When [`process::Command`] creates pipes, request that our side is always async.
268 ///
269 /// By default [`process::Command`] may choose to use pipes where both ends
270 /// are opened for synchronous read or write operations. By using
271 /// `async_pipes(true)`, this behavior is overridden so that our side is
272 /// always async.
273 ///
274 /// This is important because if doing async I/O a pipe or a file has to be
275 /// opened for async access.
276 ///
277 /// The end of the pipe sent to the child process will always be synchronous
278 /// regardless of this option.
279 ///
280 /// # Example
281 ///
282 /// ```
283 /// #![feature(windows_process_extensions_async_pipes)]
284 /// use std::os::windows::process::CommandExt;
285 /// use std::process::{Command, Stdio};
286 ///
287 /// # let program = "";
288 ///
289 /// Command::new(program)
290 /// .async_pipes(true)
291 /// .stdin(Stdio::piped())
292 /// .stdout(Stdio::piped())
293 /// .stderr(Stdio::piped());
294 /// ```
295 #[unstable(feature = "windows_process_extensions_async_pipes", issue = "98289")]
296 fn async_pipes(&mut self, always_async: bool) -> &mut process::Command;
297
298 /// Executes the command as a child process with the given
299 /// [`ProcThreadAttributeList`], returning a handle to it.
300 ///
301 /// This method enables the customization of attributes for the spawned
302 /// child process on Windows systems.
303 /// Attributes offer extended configurability for process creation,
304 /// but their usage can be intricate and potentially unsafe.
305 ///
306 /// # Note
307 ///
308 /// By default, stdin, stdout, and stderr are inherited from the parent
309 /// process.
310 ///
311 /// # Example
312 ///
313 /// ```
314 /// #![feature(windows_process_extensions_raw_attribute)]
315 /// use std::os::windows::io::AsRawHandle;
316 /// use std::os::windows::process::{CommandExt, ProcThreadAttributeList};
317 /// use std::process::Command;
318 ///
319 /// # struct ProcessDropGuard(std::process::Child);
320 /// # impl Drop for ProcessDropGuard {
321 /// # fn drop(&mut self) {
322 /// # let _ = self.0.kill();
323 /// # }
324 /// # }
325 /// #
326 /// let parent = Command::new("cmd").spawn()?;
327 /// let parent_process_handle = parent.as_raw_handle();
328 /// # let parent = ProcessDropGuard(parent);
329 ///
330 /// const PROC_THREAD_ATTRIBUTE_PARENT_PROCESS: usize = 0x00020000;
331 /// let mut attribute_list = ProcThreadAttributeList::build()
332 /// .attribute(PROC_THREAD_ATTRIBUTE_PARENT_PROCESS, &parent_process_handle)
333 /// .finish()
334 /// .unwrap();
335 ///
336 /// let mut child = Command::new("cmd").spawn_with_attributes(&attribute_list)?;
337 /// #
338 /// # child.kill()?;
339 /// # Ok::<(), std::io::Error>(())
340 /// ```
341 #[unstable(feature = "windows_process_extensions_raw_attribute", issue = "114854")]
342 fn spawn_with_attributes(
343 &mut self,
344 attribute_list: &ProcThreadAttributeList<'_>,
345 ) -> io::Result<process::Child>;
346
347 /// When true, sets the `STARTF_RUNFULLSCREEN` flag on the [STARTUPINFO][1] struct before passing it to `CreateProcess`.
348 ///
349 /// [1]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfoa
350 #[unstable(feature = "windows_process_extensions_startupinfo", issue = "141010")]
351 fn startupinfo_fullscreen(&mut self, enabled: bool) -> &mut process::Command;
352
353 /// When true, sets the `STARTF_UNTRUSTEDSOURCE` flag on the [STARTUPINFO][1] struct before passing it to `CreateProcess`.
354 ///
355 /// [1]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfoa
356 #[unstable(feature = "windows_process_extensions_startupinfo", issue = "141010")]
357 fn startupinfo_untrusted_source(&mut self, enabled: bool) -> &mut process::Command;
358
359 /// When specified, sets the following flags on the [STARTUPINFO][1] struct before passing it to `CreateProcess`:
360 /// - If `Some(true)`, sets `STARTF_FORCEONFEEDBACK`
361 /// - If `Some(false)`, sets `STARTF_FORCEOFFFEEDBACK`
362 /// - If `None`, does not set any flags
363 ///
364 /// [1]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ns-processthreadsapi-startupinfoa
365 #[unstable(feature = "windows_process_extensions_startupinfo", issue = "141010")]
366 fn startupinfo_force_feedback(&mut self, enabled: Option<bool>) -> &mut process::Command;
367
368 /// If this flag is set to `true`, each inheritable handle in the calling
369 /// process is inherited by the new process. If the flag is `false`, the
370 /// handles are not inherited.
371 ///
372 /// The default value for this flag is `true`.
373 ///
374 /// **Note** that inherited handles have the same value and access rights
375 /// as the original handles. For additional discussion of inheritable handles,
376 /// see the [Remarks][1] section of the `CreateProcessW` documentation.
377 ///
378 /// [1]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw#remarks
379 #[unstable(feature = "windows_process_extensions_inherit_handles", issue = "146407")]
380 fn inherit_handles(&mut self, inherit_handles: bool) -> &mut process::Command;
381}
382
383#[stable(feature = "windows_process_extensions", since = "1.16.0")]
384impl CommandExt for process::Command {
385 fn creation_flags(&mut self, flags: u32) -> &mut process::Command {
386 self.as_inner_mut().creation_flags(flags);
387 self
388 }
389
390 fn show_window(&mut self, cmd_show: u16) -> &mut process::Command {
391 self.as_inner_mut().show_window(Some(cmd_show));
392 self
393 }
394
395 fn force_quotes(&mut self, enabled: bool) -> &mut process::Command {
396 self.as_inner_mut().force_quotes(enabled);
397 self
398 }
399
400 fn raw_arg<S: AsRef<OsStr>>(&mut self, raw_text: S) -> &mut process::Command {
401 self.as_inner_mut().raw_arg(raw_text.as_ref());
402 self
403 }
404
405 fn async_pipes(&mut self, always_async: bool) -> &mut process::Command {
406 // FIXME: This currently has an intentional no-op implementation.
407 // For the time being our side of the pipes will always be async.
408 // Once the ecosystem has adjusted, we may then be able to start making
409 // use of synchronous pipes within the standard library.
410 let _ = always_async;
411 self
412 }
413
414 fn spawn_with_attributes(
415 &mut self,
416 attribute_list: &ProcThreadAttributeList<'_>,
417 ) -> io::Result<process::Child> {
418 self.as_inner_mut()
419 .spawn_with_attributes(sys::process::Stdio::Inherit, true, Some(attribute_list))
420 .map(process::Child::from_inner)
421 }
422
423 fn startupinfo_fullscreen(&mut self, enabled: bool) -> &mut process::Command {
424 self.as_inner_mut().startupinfo_fullscreen(enabled);
425 self
426 }
427
428 fn startupinfo_untrusted_source(&mut self, enabled: bool) -> &mut process::Command {
429 self.as_inner_mut().startupinfo_untrusted_source(enabled);
430 self
431 }
432
433 fn startupinfo_force_feedback(&mut self, enabled: Option<bool>) -> &mut process::Command {
434 self.as_inner_mut().startupinfo_force_feedback(enabled);
435 self
436 }
437
438 fn inherit_handles(&mut self, inherit_handles: bool) -> &mut process::Command {
439 self.as_inner_mut().inherit_handles(inherit_handles);
440 self
441 }
442}
443
444#[unstable(feature = "windows_process_extensions_main_thread_handle", issue = "96723")]
445pub impl(self) trait ChildExt {
446 /// Extracts the main thread raw handle, without taking ownership
447 #[unstable(feature = "windows_process_extensions_main_thread_handle", issue = "96723")]
448 fn main_thread_handle(&self) -> BorrowedHandle<'_>;
449}
450
451#[unstable(feature = "windows_process_extensions_main_thread_handle", issue = "96723")]
452impl ChildExt for process::Child {
453 fn main_thread_handle(&self) -> BorrowedHandle<'_> {
454 self.handle.main_thread_handle()
455 }
456}
457
458/// Windows-specific extensions to [`process::ExitCode`].
459///
460/// This trait is sealed: it cannot be implemented outside the standard library.
461/// This is so that future additional methods are not breaking changes.
462#[unstable(feature = "windows_process_exit_code_from", issue = "111688")]
463pub impl(self) trait ExitCodeExt {
464 /// Creates a new `ExitCode` from the raw underlying `u32` return value of
465 /// a process.
466 ///
467 /// The exit code should not be 259, as this conflicts with the `STILL_ACTIVE`
468 /// macro returned from the `GetExitCodeProcess` function to signal that the
469 /// process has yet to run to completion.
470 #[unstable(feature = "windows_process_exit_code_from", issue = "111688")]
471 fn from_raw(raw: u32) -> Self;
472}
473
474#[unstable(feature = "windows_process_exit_code_from", issue = "111688")]
475impl ExitCodeExt for process::ExitCode {
476 fn from_raw(raw: u32) -> Self {
477 process::ExitCode::from_inner(From::from(raw))
478 }
479}
480
481/// A wrapper around windows [`ProcThreadAttributeList`][1].
482///
483/// [1]: <https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-initializeprocthreadattributelist>
484#[derive(Debug)]
485#[unstable(feature = "windows_process_extensions_raw_attribute", issue = "114854")]
486pub struct ProcThreadAttributeList<'a> {
487 attribute_list: Box<[MaybeUninit<u8>]>,
488 _lifetime_marker: marker::PhantomData<&'a ()>,
489}
490
491#[unstable(feature = "windows_process_extensions_raw_attribute", issue = "114854")]
492impl<'a> ProcThreadAttributeList<'a> {
493 /// Creates a new builder for constructing a [`ProcThreadAttributeList`].
494 pub fn build() -> ProcThreadAttributeListBuilder<'a> {
495 ProcThreadAttributeListBuilder::new()
496 }
497
498 /// Returns a pointer to the underling attribute list.
499 #[doc(hidden)]
500 pub fn as_ptr(&self) -> *const MaybeUninit<u8> {
501 self.attribute_list.as_ptr()
502 }
503}
504
505#[unstable(feature = "windows_process_extensions_raw_attribute", issue = "114854")]
506impl<'a> Drop for ProcThreadAttributeList<'a> {
507 /// Deletes the attribute list.
508 ///
509 /// This method calls [`DeleteProcThreadAttributeList`][1] to delete the
510 /// underlying attribute list.
511 ///
512 /// [1]: <https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-deleteprocthreadattributelist>
513 fn drop(&mut self) {
514 let lp_attribute_list = self.attribute_list.as_mut_ptr().cast::<c_void>();
515 unsafe { sys::c::DeleteProcThreadAttributeList(lp_attribute_list) }
516 }
517}
518
519/// Builder for constructing a [`ProcThreadAttributeList`].
520#[derive(Clone, Debug)]
521#[unstable(feature = "windows_process_extensions_raw_attribute", issue = "114854")]
522pub struct ProcThreadAttributeListBuilder<'a> {
523 attributes: alloc::collections::BTreeMap<usize, ProcThreadAttributeValue>,
524 _lifetime_marker: marker::PhantomData<&'a ()>,
525}
526
527#[unstable(feature = "windows_process_extensions_raw_attribute", issue = "114854")]
528impl<'a> ProcThreadAttributeListBuilder<'a> {
529 fn new() -> Self {
530 ProcThreadAttributeListBuilder {
531 attributes: alloc::collections::BTreeMap::new(),
532 _lifetime_marker: marker::PhantomData,
533 }
534 }
535
536 /// Sets an attribute on the attribute list.
537 ///
538 /// The `attribute` parameter specifies the raw attribute to be set, while
539 /// the `value` parameter holds the value associated with that attribute.
540 /// Please refer to the [Windows documentation][1] for a list of valid attributes.
541 ///
542 /// # Note
543 ///
544 /// The maximum number of attributes is the value of [`u32::MAX`]. If this
545 /// limit is exceeded, the call to [`Self::finish`] will return an `Error`
546 /// indicating that the maximum number of attributes has been exceeded.
547 ///
548 /// # Safety Note
549 ///
550 /// Remember that improper use of attributes can lead to undefined behavior
551 /// or security vulnerabilities. Always consult the documentation and ensure
552 /// proper attribute values are used.
553 ///
554 /// [1]: <https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-updateprocthreadattribute#parameters>
555 pub fn attribute<T>(self, attribute: usize, value: &'a T) -> Self {
556 unsafe {
557 self.raw_attribute(attribute, ptr::addr_of!(*value).cast::<c_void>(), size_of::<T>())
558 }
559 }
560
561 /// Sets a raw attribute on the attribute list.
562 ///
563 /// This function is useful for setting attributes with pointers or sizes
564 /// that cannot be derived directly from their values.
565 ///
566 /// # Safety
567 ///
568 /// This function is marked as `unsafe` because it deals with raw pointers
569 /// and sizes. It is the responsibility of the caller to ensure the value
570 /// lives longer than the resulting [`ProcThreadAttributeList`] as well as
571 /// the validity of the size parameter.
572 ///
573 /// # Example
574 ///
575 #[cfg_attr(target_vendor = "win7", doc = "```no_run")]
576 #[cfg_attr(not(target_vendor = "win7"), doc = "```")]
577 /// #![feature(windows_process_extensions_raw_attribute)]
578 /// use std::ffi::c_void;
579 /// use std::os::windows::process::{CommandExt, ProcThreadAttributeList};
580 /// use std::os::windows::raw::HANDLE;
581 /// use std::process::Command;
582 ///
583 /// #[repr(C)]
584 /// pub struct COORD {
585 /// pub X: i16,
586 /// pub Y: i16,
587 /// }
588 ///
589 /// unsafe extern "system" {
590 /// fn CreatePipe(
591 /// hreadpipe: *mut HANDLE,
592 /// hwritepipe: *mut HANDLE,
593 /// lppipeattributes: *const c_void,
594 /// nsize: u32,
595 /// ) -> i32;
596 /// fn CreatePseudoConsole(
597 /// size: COORD,
598 /// hinput: HANDLE,
599 /// houtput: HANDLE,
600 /// dwflags: u32,
601 /// phpc: *mut isize,
602 /// ) -> i32;
603 /// fn CloseHandle(hobject: HANDLE) -> i32;
604 /// }
605 ///
606 /// let [mut input_read_side, mut output_write_side, mut output_read_side, mut input_write_side] =
607 /// [unsafe { std::mem::zeroed::<HANDLE>() }; 4];
608 ///
609 /// unsafe {
610 /// CreatePipe(&mut input_read_side, &mut input_write_side, std::ptr::null(), 0);
611 /// CreatePipe(&mut output_read_side, &mut output_write_side, std::ptr::null(), 0);
612 /// }
613 ///
614 /// let size = COORD { X: 60, Y: 40 };
615 /// let mut h_pc = unsafe { std::mem::zeroed() };
616 /// unsafe { CreatePseudoConsole(size, input_read_side, output_write_side, 0, &mut h_pc) };
617 ///
618 /// unsafe { CloseHandle(input_read_side) };
619 /// unsafe { CloseHandle(output_write_side) };
620 ///
621 /// const PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE: usize = 131094;
622 ///
623 /// let attribute_list = unsafe {
624 /// ProcThreadAttributeList::build()
625 /// .raw_attribute(
626 /// PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE,
627 /// h_pc as *const c_void,
628 /// size_of::<isize>(),
629 /// )
630 /// .finish()?
631 /// };
632 ///
633 /// let mut child = Command::new("cmd").spawn_with_attributes(&attribute_list)?;
634 /// #
635 /// # child.kill()?;
636 /// # Ok::<(), std::io::Error>(())
637 /// ```
638 pub unsafe fn raw_attribute<T>(
639 mut self,
640 attribute: usize,
641 value_ptr: *const T,
642 value_size: usize,
643 ) -> Self {
644 self.attributes.insert(
645 attribute,
646 ProcThreadAttributeValue { ptr: value_ptr.cast::<c_void>(), size: value_size },
647 );
648 self
649 }
650
651 /// Finalizes the construction of the `ProcThreadAttributeList`.
652 ///
653 /// # Errors
654 ///
655 /// Returns an error if the maximum number of attributes is exceeded
656 /// or if there is an I/O error during initialization.
657 pub fn finish(&self) -> io::Result<ProcThreadAttributeList<'a>> {
658 // To initialize our ProcThreadAttributeList, we need to determine
659 // how many bytes to allocate for it. The Windows API simplifies this
660 // process by allowing us to call `InitializeProcThreadAttributeList`
661 // with a null pointer to retrieve the required size.
662 let mut required_size = 0;
663 let Ok(attribute_count) = self.attributes.len().try_into() else {
664 return Err(io::const_error!(
665 io::ErrorKind::InvalidInput,
666 "maximum number of ProcThreadAttributes exceeded",
667 ));
668 };
669 unsafe {
670 sys::c::InitializeProcThreadAttributeList(
671 ptr::null_mut(),
672 attribute_count,
673 0,
674 &mut required_size,
675 )
676 };
677
678 let mut attribute_list = vec![MaybeUninit::uninit(); required_size].into_boxed_slice();
679
680 // Once we've allocated the necessary memory, it's safe to invoke
681 // `InitializeProcThreadAttributeList` to properly initialize the list.
682 sys::cvt(unsafe {
683 sys::c::InitializeProcThreadAttributeList(
684 attribute_list.as_mut_ptr().cast::<c_void>(),
685 attribute_count,
686 0,
687 &mut required_size,
688 )
689 })?;
690
691 // # Add our attributes to the buffer.
692 // It's theoretically possible for the attribute count to exceed a u32
693 // value. Therefore, we ensure that we don't add more attributes than
694 // the buffer was initialized for.
695 for (&attribute, value) in self.attributes.iter().take(attribute_count as usize) {
696 sys::cvt(unsafe {
697 sys::c::UpdateProcThreadAttribute(
698 attribute_list.as_mut_ptr().cast::<c_void>(),
699 0,
700 attribute,
701 value.ptr,
702 value.size,
703 ptr::null_mut(),
704 ptr::null_mut(),
705 )
706 })?;
707 }
708
709 Ok(ProcThreadAttributeList { attribute_list, _lifetime_marker: marker::PhantomData })
710 }
711}
712
713/// Wrapper around the value data to be used as a Process Thread Attribute.
714#[derive(Clone, Debug)]
715struct ProcThreadAttributeValue {
716 ptr: *const c_void,
717 size: usize,
718}