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 {...@@ -1479,6 +1479,8 @@ const WindowsCommandLineCache = struct {
1479 }1479 }
1480};1480};
14811481
1482/// Returns the absolute path of `cmd.exe` within the Windows system directory.
1483/// The caller owns the returned slice.
1482fn windowsCmdExePath(allocator: mem.Allocator) error{ OutOfMemory, Unexpected }![:0]u16 {1484fn windowsCmdExePath(allocator: mem.Allocator) error{ OutOfMemory, Unexpected }![:0]u16 {
1483 var buf = try std.ArrayListUnmanaged(u16).initCapacity(allocator, 128);1485 var buf = try std.ArrayListUnmanaged(u16).initCapacity(allocator, 128);
1484 errdefer buf.deinit(allocator);1486 errdefer buf.deinit(allocator);
...@@ -1510,6 +1512,11 @@ const ArgvToCommandLineError = error{ OutOfMemory, InvalidWtf8, InvalidArg0 };...@@ -1510,6 +1512,11 @@ const ArgvToCommandLineError = error{ OutOfMemory, InvalidWtf8, InvalidArg0 };
15101512
1511/// Serializes `argv` to a Windows command-line string suitable for passing to a child process and1513/// Serializes `argv` to a Windows command-line string suitable for passing to a child process and
1512/// parsing by the `CommandLineToArgvW` algorithm. The caller owns the returned slice.1514/// 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.
1513fn argvToCommandLineWindows(1520fn argvToCommandLineWindows(
1514 allocator: mem.Allocator,1521 allocator: mem.Allocator,
1515 argv: []const []const u8,1522 argv: []const []const u8,
...@@ -1678,6 +1685,14 @@ const ArgvToScriptCommandLineError = error{...@@ -1678,6 +1685,14 @@ const ArgvToScriptCommandLineError = error{
1678///1685///
1679/// Escapes `argv` using the suggested mitigation against arbitrary command execution from:1686/// Escapes `argv` using the suggested mitigation against arbitrary command execution from:
1680/// https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/1687/// 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.
1681fn argvToScriptCommandLineWindows(1696fn argvToScriptCommandLineWindows(
1682 allocator: mem.Allocator,1697 allocator: mem.Allocator,
1683 /// Path to the `.bat`/`.cmd` script. If this path is relative, it is assumed to be relative to the CWD.1698 /// Path to the `.bat`/`.cmd` script. If this path is relative, it is assumed to be relative to the CWD.