|
90 | 90 | //! |
91 | 91 | //! # Windows argument splitting |
92 | 92 | //! |
93 | | -//! On Unix systems arguments are passed to a new process as an array of strings |
94 | | -//! but on Windows arguments are passed as a single commandline string and it's |
| 93 | +//! On Unix systems arguments are passed to a new process as an array of strings, |
| 94 | +//! but on Windows arguments are passed as a single commandline string and it is |
95 | 95 | //! up to the child process to parse it into an array. Therefore the parent and |
96 | 96 | //! child processes must agree on how the commandline string is encoded. |
97 | 97 | //! |
|
107 | 107 | //! * Use [`raw_arg`] to build a custom commandline. This bypasses the escaping |
108 | 108 | //! rules used by [`arg`] so should be used with due caution. |
109 | 109 | //! |
110 | | -//! `cmd.exe` and `.bat` use non-standard argument parsing and are especially |
| 110 | +//! `cmd.exe` and `.bat` files use non-standard argument parsing and are especially |
111 | 111 | //! vulnerable to malicious input as they may be used to run arbitrary shell |
112 | 112 | //! commands. Untrusted arguments should be restricted as much as possible. |
113 | 113 | //! For examples on handling this see [`raw_arg`]. |
114 | 114 | //! |
115 | | -//! ### Bat file special handling |
| 115 | +//! ### Batch file special handling |
116 | 116 | //! |
117 | 117 | //! On Windows, `Command` uses the Windows API function [`CreateProcessW`] to |
118 | | -//! spawn new processes. An undocumented feature of this function is that, |
| 118 | +//! spawn new processes. An undocumented feature of this function is that |
119 | 119 | //! when given a `.bat` file as the application to run, it will automatically |
120 | | -//! convert that into running `cmd.exe /c` with the bat file as the next argument. |
| 120 | +//! convert that into running `cmd.exe /c` with the batch file as the next argument. |
121 | 121 | //! |
122 | 122 | //! For historical reasons Rust currently preserves this behaviour when using |
123 | 123 | //! [`Command::new`], and escapes the arguments according to `cmd.exe` rules. |
124 | 124 | //! Due to the complexity of `cmd.exe` argument handling, it might not be |
125 | | -//! possible to safely escape some special chars, and using them will result |
| 125 | +//! possible to safely escape some special characters, and using them will result |
126 | 126 | //! in an error being returned at process spawn. The set of unescapeable |
127 | | -//! special chars might change between releases. |
| 127 | +//! special characters might change between releases. |
128 | 128 | //! |
129 | | -//! Also note that running `.bat` scripts in this way may be removed in the |
| 129 | +//! Also note that running batch scripts in this way may be removed in the |
130 | 130 | //! future and so should not be relied upon. |
131 | 131 | //! |
132 | 132 | //! [`spawn`]: Command::spawn |
@@ -659,16 +659,19 @@ impl Command { |
659 | 659 | /// |
660 | 660 | /// Note that the argument is not passed through a shell, but given |
661 | 661 | /// literally to the program. This means that shell syntax like quotes, |
662 | | - /// escaped characters, word splitting, glob patterns, variable substitution, etc. |
663 | | - /// have no effect. |
| 662 | + /// escaped characters, word splitting, glob patterns, variable substitution, |
| 663 | + /// etc. have no effect. |
664 | 664 | /// |
665 | 665 | /// <div class="warning"> |
666 | 666 | /// |
667 | | - /// On Windows use caution with untrusted inputs. Most applications use the |
668 | | - /// standard convention for decoding arguments passed to them. These are safe to use with `arg`. |
669 | | - /// However some applications, such as `cmd.exe` and `.bat` files, use a non-standard way of decoding arguments |
670 | | - /// and are therefore vulnerable to malicious input. |
671 | | - /// In the case of `cmd.exe` this is especially important because a malicious argument can potentially run arbitrary shell commands. |
| 667 | + /// On Windows, use caution with untrusted inputs. Most applications use the |
| 668 | + /// standard convention for decoding arguments passed to them. These are safe to |
| 669 | + /// use with `arg`. However, some applications such as `cmd.exe` and `.bat` files |
| 670 | + /// use a non-standard way of decoding arguments. They are therefore vulnerable |
| 671 | + /// to malicious input. |
| 672 | + /// |
| 673 | + /// In the case of `cmd.exe` this is especially important because a malicious |
| 674 | + /// argument can potentially run arbitrary shell commands. |
672 | 675 | /// |
673 | 676 | /// See [Windows argument splitting][windows-args] for more details |
674 | 677 | /// or [`raw_arg`] for manually implementing non-standard argument encoding. |
@@ -710,11 +713,14 @@ impl Command { |
710 | 713 | /// |
711 | 714 | /// <div class="warning"> |
712 | 715 | /// |
713 | | - /// On Windows use caution with untrusted inputs. Most applications use the |
714 | | - /// standard convention for decoding arguments passed to them. These are safe to use with `args`. |
715 | | - /// However some applications, such as `cmd.exe` and `.bat` files, use a non-standard way of decoding arguments |
716 | | - /// and are therefore vulnerable to malicious input. |
717 | | - /// In the case of `cmd.exe` this is especially important because a malicious argument can potentially run arbitrary shell commands. |
| 716 | + /// On Windows, use caution with untrusted inputs. Most applications use the |
| 717 | + /// standard convention for decoding arguments passed to them. These are safe to |
| 718 | + /// use with `arg`. However, some applications such as `cmd.exe` and `.bat` files |
| 719 | + /// use a non-standard way of decoding arguments. They are therefore vulnerable |
| 720 | + /// to malicious input. |
| 721 | + /// |
| 722 | + /// In the case of `cmd.exe` this is especially important because a malicious |
| 723 | + /// argument can potentially run arbitrary shell commands. |
718 | 724 | /// |
719 | 725 | /// See [Windows argument splitting][windows-args] for more details |
720 | 726 | /// or [`raw_arg`] for manually implementing non-standard argument encoding. |
|
0 commit comments