execve
Replaces the current process image with the executed process.
This function must allocate memory to add a null terminating bytes on path and each arg.
It must also convert to KEY=VALUE\0 format for environment variables, and include null
pointers after the args and after the environment variables.
argv[0] is the executable path.
This function also uses the PATH environment variable to get the full path to the executable.
Due to the heap-allocation, it is illegal to call this function in a fork() child.
For that use case, use the std.posix functions directly.
Function parameters
Parameters
Type definitions in this namespace
Types
- ArgIteratorWindows
- Iterator that implements the Windows command-line parsing algorithm.
- ArgIteratorGeneralOptions
- Optional parameters for `ArgIteratorGeneral`
- ArgIterator
- Cross-platform command line argument iterator.
Functions in this namespace
Functions
- getCwd
- The result is a slice of `out_buffer`, from index `0`.
- getCwdAlloc
- Caller must free the returned memory.
- getEnvMap
- Returns a snapshot of the environment variables of the current process.
- getEnvVarOwned
- Caller must free returned memory.
- hasEnvVarConstant
- On Windows, `key` must be valid WTF-8.
- hasNonEmptyEnvVarConstant
- On Windows, `key` must be valid WTF-8.
- parseEnvVarInt
- Parses an environment variable as an integer.
- hasEnvVar
- On Windows, if `key` is not valid [WTF-8](https://simonsapin.github.io/wtf-8/),
- hasNonEmptyEnvVar
- On Windows, if `key` is not valid [WTF-8](https://simonsapin.github.io/wtf-8/),
- getenvW
- Windows-only.
- ArgIteratorGeneral
- A general Iterator to parse a string into a set of arguments
- args
- Holds the command-line arguments, with the program name as the first entry.
- argsWithAllocator
- You must deinitialize iterator's internal buffers by calling `deinit` when done.
- argsAlloc
- Caller must call argsFree on result.
- getUserInfo
- POSIX function which gets a uid from username.
- posixGetUserInfo
- TODO this reads /etc/passwd.
- execv
- Replaces the current process image with the executed process.
- execve
- Replaces the current process image with the executed process.
- totalSystemMemory
- Returns the total system memory, in bytes as a u64.
- cleanExit
- Indicate that we are now terminating with a successful exit code.
- raiseFileDescriptorLimit
- Raise the open file descriptor limit.
- createEnvironFromMap
- Creates a null-delimited environment variable block in the format
- createEnvironFromExisting
- Creates a null-delimited environment variable block in the format
- createWindowsEnvBlock
- Caller must free result.
- fatal
- Logs an error and then terminates the process with exit code 1.
Error sets in this namespace
Error Sets
Tells whether calling the `execv` or `execve` functions will be a compile error.
Values
Source
Implementation
pub fn execve(
allocator: Allocator,
argv: []const []const u8,
env_map: ?*const EnvMap,
) ExecvError {
if (!can_execv) @compileError("The target OS does not support execv");
var arena_allocator = std.heap.ArenaAllocator.init(allocator);
defer arena_allocator.deinit();
const arena = arena_allocator.allocator();
const argv_buf = try arena.allocSentinel(?[*:0]const u8, argv.len, null);
for (argv, 0..) |arg, i| argv_buf[i] = (try arena.dupeZ(u8, arg)).ptr;
const envp = m: {
if (env_map) |m| {
const envp_buf = try createNullDelimitedEnvMap(arena, m);
break :m envp_buf.ptr;
} else if (builtin.link_libc) {
break :m std.c.environ;
} else if (builtin.output_mode == .Exe) {
// Then we have Zig start code and this works.
// TODO type-safety for null-termination of `os.environ`.
break :m @as([*:null]const ?[*:0]const u8, @ptrCast(std.os.environ.ptr));
} else {
// TODO come up with a solution for this.
@compileError("missing std lib enhancement: std.process.execv implementation has no way to collect the environment variables to forward to the child process");
}
};
return posix.execvpeZ_expandArg0(.no_expand, argv_buf.ptr[0].?, argv_buf.ptr, envp);
}