execveat

Implemented in Antinomie 0.7.0 · Syscall list

Synopsis

long execveat(int dfd, const char *filename, const char *const *argv, const char *const *envp, int flags);

Number (x86-64)	322
ABI	64
Kernel entry point	sys_execveat

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

Description

Like execve, but the program is given by a directory descriptor and path, or by an open file with an empty path.

Arguments

Name	Type	Meaning
dfd (arg0)	int	Directory file descriptor that a relative path is resolved against, or AT_FDCWD (-100) for the current directory.
filename (arg1)	const char *	Path of the program, relative to fd, or empty with AT_EMPTY_PATH to run the file fd refers to.
argv (arg2)	const char *const *	Pointer to a NULL-terminated array of argument strings.
envp (arg3)	const char *const *	Pointer to a NULL-terminated array of environment strings.
flags (arg4)	int	AT_EMPTY_PATH or AT_SYMLINK_NOFOLLOW.

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.

Man page

execveat(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
dfd (arg0)	Entry	raw scalar word	args.0, args.dfd
filename (arg1)	Entry	the pointer itself, as a raw word	args.1, args.raw[1]
↳ pointee	Entry	NUL-terminated string, up to 4,096 bytes (PATH_MAX)	arg1.path	always
argv (arg2)	Entry	the pointer itself, as a raw word	args.2, args.raw[2]
↳ pointee	Entry	each argument pointer and then its NUL-terminated string, until the NULL terminator or the budget	arg2.ptr[i], arg2.string[i]	always
envp (arg3)	Entry	the pointer itself, as a raw word	args.3, args.raw[3]
↳ pointee	Entry	each environment pointer and then its NUL-terminated string, with the budget shared with the arguments	arg3.ptr[i], arg3.string[i]	always
flags (arg4)	Entry	raw scalar word; Syscall Trace also decodes it into flag names (execveat group), listing unknown bits separately	args.4, args.flags

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).

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.dfd (arg0), args.filename (arg1), args.argv (arg2), args.envp (arg3), args.flags (arg4); 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.