execve

Implemented in Antinomie 0.7.0 · Syscall list

Synopsis

long execve(const char *filename, const char *const *argv, const char *const *envp);

Number (x86-64)	59
ABI	64
Kernel entry point	sys_execve

This is the raw kernel prototype from the pinned Linux 6.12.94 schema, not the libc wrapper.

Description

Replaces the running program with a new executable, with a given argument list and environment.

Arguments

Name	Type	Meaning
filename (arg0)	const char *	Path of the program to execute.
argv (arg1)	const char *const *	Pointer to the NULL-terminated array of argument strings; argv[0] is conventionally the program name.
envp (arg2)	const char *const *	Pointer to the NULL-terminated array of NAME=value environment strings.

Return value

On success: nothing on success because the program is replaced; an error otherwise.

In an Antinomie trace the Return column and the ret filter field show the raw kernel return value. On failure that is the negative errno, for example -2 for ENOENT, not the -1 plus errno that the libc wrapper gives. syscall.errno holds the positive errno and syscall.success is false.

Common errors

Raw return	Name	Meaning
-7	E2BIG	An argument list or structure is too large.
-13	EACCES	Permission denied.
-2	ENOENT	A path component or the named object does not exist.
-8	ENOEXEC	The file is not in a format the kernel can execute.

Man page

execve(2) on man7.org

Captured by Antinomie

Coverage mark: Implemented. Every pointer argument has a capture rule in the pinned kernel patch and none of them records a “no decoder”, “address only” or “not observed” gap on any code path. Individual values can still be incomplete on a particular call; see the capture statuses.

Every call is recorded as an Entry record (the six argument words and the pointees copied at entry) and an Exit record (the return value and the pointees copied at exit).

Arguments

Argument	When	How	Recorded field key	Condition
filename (arg0)	Entry	the pointer itself, as a raw word	args.0, args.raw[0]
↳ pointee	Entry	NUL-terminated string, up to 4,096 bytes (PATH_MAX)	arg0.path	always
argv (arg1)	Entry	the pointer itself, as a raw word	args.1, args.raw[1]
↳ pointee	Entry	each argument pointer and then its NUL-terminated string (up to MAX_ARG_STRLEN), until the NULL terminator or the budget	arg1.ptr[i], arg1.string[i]	always
envp (arg2)	Entry	the pointer itself, as a raw word	args.2, args.raw[2]
↳ pointee	Entry	each environment pointer and then its NUL-terminated string, with the budget shared with the arguments	arg2.ptr[i], arg2.string[i]	always

Family notes

• The argument and environment vectors are read up to a stack-size budget (at least ARG_MAX, otherwise up to a quarter of the stack limit). A vector that exceeds the budget records arg1.vector or arg2.vector with the “invalid extent” status.

Derived and lifecycle records

• A lifecycle.exec_commit record is emitted when the exec succeeds and the new program image is committed. It is what makes the process.exe and process.argv filter fields available.
• A lifecycle.exec_image record names the image that was loaded and, for a script, the interpreter its #! line named, and a lifecycle.file_hash record (kind Exec) gives the SHA-256 of the committed image, or the reason there is none. Written by a base built for Antinomie 0.7.0 or later.

Filter fields

• Result: ret, syscall.errno, syscall.success, syscall.duration_ns.
• Argument words: args.filename (arg0), args.argv (arg1), args.envp (arg2); args.0 to args.5 by position.
• Captured strings: the args.<name> field of a path argument, and args.path, give the captured text instead of the pointer.

See Syscall Trace filter for the full syntax.

For what the capture statuses mean, see Capture statuses. For what is never recorded, see Known gaps.