asmgrader::Tracer Class Reference

A lightweight wrapper of ptrace(2) More...

#include <tracer.hpp>

Public Member Functions
	Tracer ()=default
Result< void >	begin (pid_t pid)
	Sets up tracing in parent process, then stops child immediately after exec call.
Result< RunResult >	run ()
	Run the child process. Records each syscall execution. Equivalent to run_until({})
Result< RunResult >	run_until (const std::function< bool(SyscallRecord)> &pred)
	Run the child process until pred returns true.
Result< SyscallRecord >	execute_syscall (u64 sys_nr, std::array< std::uint64_t, 6 > args)
	Executes a syscall with the given arguments as the stopped tracee.
Result< user_regs_struct >	get_registers () const
	Get the general purpose registers of the stopped tracee IMPORTANT: this is (obviously) architecture-dependent.
Result< user_fpregs_struct >	get_fp_registers () const
Result< void >	set_registers (user_regs_struct regs) const
	Set the general purpose registers of the stopped tracee IMPORTANT: this is (obviously) architecture-dependent.
Result< void >	set_fp_registers (user_fpregs_struct regs) const
const std::vector< SyscallRecord > &	get_records () const
	Obtain records of syscalls run so far in the child process.
std::optional< int >	get_exit_code () const
	Obtain the process exit code, or nullopt if the process has not yet exited.
Result< void >	jump_to (std::uintptr_t address)
	Set the child process's instruction pointer to address
template<typename... Args>
Result< void >	setup_function_call (Args &&... args)
template<typename Ret >
Result< Ret >	process_function_ret ()
	AFTER a function has been called, inspects register values (and memory if necessary) to construct the expected return type.
MemoryIOBase &	get_memory_io ()
std::uintptr_t	get_mmapped_addr () const

Static Public Member Functions
static Result< void >	init_child ()
	Set up child process for tracing Call this within the newly-forked process.

Static Public Attributes
static constexpr std::size_t	MMAP_LENGTH = 4096
static constexpr auto	DEFAULT_TIMEOUT = std::chrono::milliseconds{10}

Detailed Description

A lightweight wrapper of ptrace(2)

Instantiate and use this class in the parent process to trace a child. In the child process, call Tracer::init_child.

Constructor & Destructor Documentation

Tracer()

asmgrader::Tracer::Tracer ( )

default

Member Function Documentation

begin()

Result< void > asmgrader::Tracer::begin

(

pid_t

pid

)

Sets up tracing in parent process, then stops child immediately after exec call.

execute_syscall()

Result< SyscallRecord > asmgrader::Tracer::execute_syscall	(	u64	sys_nr,
		std::array< std::uint64_t, 6 >	args )

Executes a syscall with the given arguments as the stopped tracee.

get_exit_code()

std::optional< int > asmgrader::Tracer::get_exit_code ( ) const

inline

Obtain the process exit code, or nullopt if the process has not yet exited.

get_fp_registers()

Result< user_fpregs_struct > asmgrader::Tracer::get_fp_registers

(

)

const

get_memory_io()

MemoryIOBase & asmgrader::Tracer::get_memory_io

(

)

get_mmapped_addr()

std::uintptr_t asmgrader::Tracer::get_mmapped_addr ( ) const

inline

get_records()

const std::vector< SyscallRecord > & asmgrader::Tracer::get_records ( ) const

inline

Obtain records of syscalls run so far in the child process.

get_registers()

Result< user_regs_struct > asmgrader::Tracer::get_registers

(

)

const

Get the general purpose registers of the stopped tracee IMPORTANT: this is (obviously) architecture-dependent.

init_child()

Result< void > asmgrader::Tracer::init_child ( )

static

Set up child process for tracing Call this within the newly-forked process.

Immediately after a call to this function should be a call to execve.

jump_to()

Result< void > asmgrader::Tracer::jump_to

(

std::uintptr_t

address

)

Set the child process's instruction pointer to address

process_function_ret()

template<typename Ret >

Result< Ret > asmgrader::Tracer::process_function_ret

(

)

AFTER a function has been called, inspects register values (and memory if necessary) to construct the expected return type.

std::nullopt is returned if it's not possible to construct return type.

run()

Result< RunResult > asmgrader::Tracer::run

(

)

Run the child process. Records each syscall execution. Equivalent to run_until({})

run_until()

Result< RunResult > asmgrader::Tracer::run_until

(

const std::function< bool(SyscallRecord)> &

pred

)

Run the child process until pred returns true.

pred is passed a copy of each invoked syscall upon entry, in the child process. Note that certain fields of the SyscallEntry requiring completion of the syscall, such as the exit return value for instance, will be invalid as the syscall has not yet completed at the time of the predicate's evaluation.

It is valid to pass an empty pred value. This is equivalent to passing a predicate that always returns true, and also equivalent to a call to run. run should always be preferred, however.

set_fp_registers()

Result< void > asmgrader::Tracer::set_fp_registers

(

user_fpregs_struct

regs

)

const

set_registers()

Result< void > asmgrader::Tracer::set_registers

(

user_regs_struct

regs

)

const

Set the general purpose registers of the stopped tracee IMPORTANT: this is (obviously) architecture-dependent.

setup_function_call()

template<typename... Args>

Result< void > asmgrader::Tracer::setup_function_call

(

Args &&...

args

)

Member Data Documentation

DEFAULT_TIMEOUT

auto asmgrader::Tracer::DEFAULT_TIMEOUT = std::chrono::milliseconds{10}

staticconstexpr

MMAP_LENGTH

std::size_t asmgrader::Tracer::MMAP_LENGTH = 4096

staticconstexpr

---

The documentation for this class was generated from the following files:

• include/asmgrader/subprocess/tracer.hpp
• src/subprocess/tracer.cpp