This is an example of documentation generated by ZigDoc, an alternative to Zig's built-in Auto Doc feature. See also examples in other modes/formats. The project being documented here (as the example) is the Zig standard library. Private Function
Serializes argv to a Windows command-line string suitable for passing to a child process and parsing by the CommandLineToArgvW algorithm. The caller owns the returned slice.
fnargvToCommandLineWindows(
allocator: Allocator,
argv: []const []constu8,
) ArgvToCommandLineError![:0]u16 {
varbuf = std.array_list.Managed(u8).init(allocator);
deferbuf.deinit();
if (argv.len != 0) {
constarg0 = argv[0];
// The first argument must be quoted if it contains spaces or ASCII control characters// (excluding DEL). It also follows special quoting rules where backslashes have no special// interpretation, which makes it impossible to pass certain first arguments containing// double quotes to a child process without characters from the first argument leaking into// subsequent ones (which could have security implications).//// Empty arguments technically don't need quotes, but we quote them anyway for maximum// compatibility with different implementations of the 'CommandLineToArgvW' algorithm.//// Double quotes are illegal in paths on Windows, so for the sake of simplicity we reject// all first arguments containing double quotes, even ones that we could theoretically// serialize in unquoted form.varneeds_quotes = arg0.len == 0;
for (arg0) |c| {
if (c <= ' ') {
needs_quotes = true;
} elseif (c == '"') {
returnerror.InvalidArg0;
}
}
if (needs_quotes) {
trybuf.append('"');
trybuf.appendSlice(arg0);
trybuf.append('"');
} else {
trybuf.appendSlice(arg0);
}
for (argv[1..]) |arg| {
trybuf.append(' ');
// Subsequent arguments must be quoted if they contain spaces, tabs or double quotes,// or if they are empty. For simplicity and for maximum compatibility with different// implementations of the 'CommandLineToArgvW' algorithm, we also quote all ASCII// control characters (again, excluding DEL).needs_quotes = for (arg) |c| {
if (c <= ' 'orc == '"') {
breaktrue;
}
} elsearg.len == 0;
if (!needs_quotes) {
trybuf.appendSlice(arg);
continue;
}
trybuf.append('"');
varbackslash_count: usize = 0;
for (arg) |byte| {
switch (byte) {
'\\' => {
backslash_count += 1;
},
'"' => {
trybuf.appendNTimes('\\', backslash_count * 2 + 1);
trybuf.append('"');
backslash_count = 0;
},
else => {
trybuf.appendNTimes('\\', backslash_count);
trybuf.append(byte);
backslash_count = 0;
},
}
}
trybuf.appendNTimes('\\', backslash_count * 2);
trybuf.append('"');
}
}
returntrystd.unicode.wtf8ToWtf16LeAllocZ(allocator, buf.items);
}
Serializes
argvto a Windows command-line string suitable for passing to a child process and parsing by theCommandLineToArgvWalgorithm. The caller owns the returned slice.To avoid arbitrary command execution, this function should not be used when spawning
.bat/.cmdscripts. https://flatt.tech/research/posts/batbadbut-you-cant-securely-execute-commands-on-windows/When executing
.bat/.cmdscripts, useargvToScriptCommandLineWindowsinstead.