authorgravatar for squeek502@hotmail.comRyan Liptak <squeek502@hotmail.com> 2024-05-26 09:36:34-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-05-26 09:37:14-07:00
logaa463adc91d4fb356595b8f7d0af3801c0623e1e
tree5b605e19a44b64bd36bbc7cf75842fd08c1aab5f
parentf47824f24d1b20c276a797df8cf99066c08203b6

std.process.Child: Improve doc comments of Windows argv -> command line functions

1 files changed, 15 insertions(+), 0 deletions(-)

lib/std/process/Child.zig+15
......@@ -1479,6 +1479,8 @@ const WindowsCommandLineCache = struct {
14791479 }
14801480};
14811481
1482/// Returns the absolute path of `cmd.exe` within the Windows system directory.
1483/// The caller owns the returned slice.
14821484fn windowsCmdExePath(allocator: mem.Allocator) error{ OutOfMemory, Unexpected }![:0]u16 {
14831485 var buf = try std.ArrayListUnmanaged(u16).initCapacity(allocator, 128);
14841486 errdefer buf.deinit(allocator);
......@@ -1510,6 +1512,11 @@ const ArgvToCommandLineError = error{ OutOfMemory, InvalidWtf8, InvalidArg0 };
15101512
15111513/// Serializes `argv` to a Windows command-line string suitable for passing to a child process and
15121514/// parsing by the `CommandLineToArgvW` algorithm. The caller owns the returned slice.
1515///
1516/// To avoid arbitrary command execution, this function should not be used when spawning `.bat`/`.cmd` scripts.
1517/// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
1518///
1519/// When executing `.bat`/`.cmd` scripts, use `argvToScriptCommandLineWindows` instead.
15131520fn argvToCommandLineWindows(
15141521 allocator: mem.Allocator,
15151522 argv: []const []const u8,
......@@ -1678,6 +1685,14 @@ const ArgvToScriptCommandLineError = error{
16781685///
16791686/// Escapes `argv` using the suggested mitigation against arbitrary command execution from:
16801687/// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/
1688///
1689/// The return of this function will look like
1690/// `cmd.exe /d /e:ON /v:OFF /c "<escaped command line>"`
1691/// and should be used as the `lpCommandLine` of `CreateProcessW`, while the
1692/// return of `windowsCmdExePath` should be used as `lpApplicationName`.
1693///
1694/// Should only be used when spawning `.bat`/`.cmd` scripts, see `argvToCommandLineWindows` otherwise.
1695/// The `.bat`/`.cmd` file must be known to both have the `.bat`/`.cmd` extension and exist on the filesystem.
16811696fn argvToScriptCommandLineWindows(
16821697 allocator: mem.Allocator,
16831698 /// Path to the `.bat`/`.cmd` script. If this path is relative, it is assumed to be relative to the CWD.