std/os/windows/
process.rs

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

std/os/windows/
process.rs
