Specialization of Tracee for automatically attached child tracees. More...

#include <AutoAttachedTracee.hxx>

Inheritance diagram for clues::AutoAttachedTracee:

Public Member Functions
	AutoAttachedTracee (Engine &engine, EventConsumer &consumer, TraceePtr parent)
	Create a traced process object by attaching to the given process ID.

void	configure (const cosmos::ProcessID pid, const cosmos::ptrace::Event event, const SystemCall &sc)
	Sets the given process ID as the process to be traced.

Public Member Functions inherited from clues::Tracee
const std::string &	executable () const

const cosmos::StringVector &	cmdLine () const

const FDInfoMap &	fdInfoMap () const
	Provides access to the current knowledge about file descriptors in the tracee.

cosmos::ProcessID	pid () const

bool	alive () const

size_t	maxBufferPrefetch () const

void	setMaxBufferPrefetch (const size_t bytes)
	Sets an upper limit for the retrieval of variable-length buffer parameters in system calls.

size_t	syscallCtr () const
	Returns the number of system calls observed so far.

std::optional< cosmos::Signal >	stopSignal () const
	For state() == State::GROUP_STOP this returns the stopping signal that caused it.

State	state () const

State	prevState () const

bool	isEnterStop () const

bool	isExitStop () const

Flags	flags () const

std::optional< cosmos::ChildState >	exitData () const
	Returns possible tracee exit data.

virtual void	attach (const FollowChildren follow_children, const AttachThreads attach_threads=AttachThreads{false})
	Logic to handle attaching to the tracee.

bool	detach ()
	Attempt to detach the Tracee.

long	getData (const ForeignPtr addr) const
	Reads a word of data from the tracee's memory.

void	readString (const ForeignPtr addr, std::string &out) const
	Reads a zero-terminated C-string from the tracee.

void	readBlob (const ForeignPtr addr, char *buffer, const size_t bytes) const
	Reads an arbitrary binary blob of fixed length from the tracee.

template<typename T, bool CHECK_TRIVIAL = true>
bool	readStruct (const ForeignPtr addr, T &out) const
	Reads a system call struct from the tracee's address space into `out`.

template<typename VECTOR>
void	readVector (const ForeignPtr pointer, VECTOR &out) const
	Reads in a zero terminated array of data items into the STL-vector like parameter `out`.

virtual bool	isChildProcess () const
	Returns whether the tracee is a child process created by us.

bool	isThreadGroupLeader () const
	Checks in the proc file system whether the Tracee is a thread group leader.

bool	isInitiallyAttachedThread () const
	Indicates whether this Tracee is an automatically attached thread.

std::optional< SystemCallNr >	currentSystemCallNr () const
	Returns the number of the currently running system call, if any.

const std::optional< SystemCallInfo > &	currentSystemCallInfo () const

const Engine &	engine () const

Additional Inherited Members
Public Types inherited from clues::Tracee
enum class	State { UNKNOWN , RUNNING , SYSCALL_ENTER_STOP , SYSCALL_EXIT_STOP , SIGNAL_DELIVERY_STOP , GROUP_STOP , EVENT_STOP , DEAD , DETACHED }
	Current tracing state for a single tracee. More...

enum class	Flag { WAIT_FOR_ATTACH_STOP = 1 << 0 , DETACH_AT_NEXT_STOP = 1 << 1 , INJECTED_SIGSTOP = 1 << 2 , INJECTED_SIGCONT = 1 << 3 , SYSCALL_ENTERED = 1 << 4 , WAIT_FOR_EXITED = 1 << 5 , ATTACH_THREADS_PENDING = 1 << 6 , SEEN_SIGRETURN = 1 << 7 }
	Different flags reflecting the tracer status. More...

using	Flags = cosmos::BitMask<Flag>

Static Public Member Functions inherited from clues::Tracee
static const char *	getStateLabel (const State state)

Protected Member Functions inherited from clues::Tracee
	Tracee (Engine &engine, EventConsumer &consumer, TraceePtr sibling=nullptr)

void	processEvent (const cosmos::ChildState &data)
	Process the given ptrace event.

void	updateExecutable ()

void	updateCmdLine ()

void	updateExecInfo ()

void	syncFDsAfterExec ()

void	changeState (const State new_state)

void	interrupt ()
	Forces the traced process to stop.

void	restart (const cosmos::Tracee::RestartMode mode=cosmos::Tracee::RestartMode::CONT, const std::optional< cosmos::Signal > signal={})
	Restarts the traced process, optionally delivering `signal`.

void	setOptions (const cosmos::ptrace::Opts opts)
	Applies the given trace `flags`.

void	seize (const cosmos::ptrace::Opts opts)
	Makes the tracee a tracee.

void	setPID (const cosmos::ProcessID tracee)
	Sets the tracee PID.

template<ABI abi>
void	getRegisters (RegisterSet< abi > &rs)
	Reads the current register set from the process.

void	handleSystemCall ()

void	handleSystemCallEntry ()

void	handleSystemCallExit ()

void	handleStateMismatch ()

void	handleSignal (const cosmos::SigInfo &info)

void	handleEvent (const cosmos::ChildState &data, const cosmos::ptrace::Event event, const cosmos::Signal signal)

void	handleStopEvent (const cosmos::Signal signal)

void	handleExitEvent ()

void	handleExecEvent (const cosmos::ProcessID main_pid)

void	handleNewChildEvent (const cosmos::ptrace::Event event)

void	handleAttached ()

void	syncState (Tracee &other)

void	attachThreads ()

template<typename FILLER>
void	fillData (ForeignPtr addr, FILLER &filler) const
	Reads data from the Tracee starting at `addr` and feeds it to `filler` until it's saturated.

virtual void	cleanupChild ()

void	verifyArch ()
	Verifies the tracee's architecture according to m_syscall_info, throws on mismatch.

std::optional< SystemCallNr >	getInitialSyscallNr (const ABI abi) const
	Returns the initial system call nr. stored in m_initial_regset, if available for `abi`.

void	getInitialRegisters ()

void	unshareProcessData ()

void	doDetach ()
	Actually perform a detach without checking tracee state.

void	handleError (const cosmos::ApiError &error)
	Handle ApiErrors raised from ptrace() requests.

bool	hasClonedThread () const
	Returns whether the current/last seen system call was a clone() for a thread.

void	trackFD (FDInfo &&info) const
	Track a new file descriptor for this Tracee's thread group.

void	dropFD (const cosmos::FileNum fd) const
	Drop a file descriptor from the tracking of the Tracee's thread group.

Protected Attributes inherited from clues::Tracee
Engine &	m_engine
	The engine that manages this tracee.

EventConsumer &	m_consumer
	Callback interface receiving our information.

State	m_state = State::UNKNOWN
	The current state the tracee is in.

State	m_prev_state = State::UNKNOWN
	The previous Tracee state we've seen (except RUNNING).

Flags	m_flags
	These keep track of various state on the tracer side.

cosmos::Tracee	m_ptrace
	libcosmos API for the Tracee.

cosmos::ptrace::Opts	m_ptrace_opts
	The options we've set for ptrace().

std::optional< SystemCallInfo >	m_syscall_info
	The current system call information, if any.

SystemCallDB	m_syscall_db
	Reusable database object for tracing system calls.

SystemCall *	m_current_syscall = nullptr
	Holds state for the currently executing system call.

SystemCall *	m_interrupted_syscall = nullptr
	Previous system call, if it has been interrupted.

cosmos::Tracee::RestartMode	m_restart_mode = cosmos::Tracee::RestartMode::CONT
	current RestartMode to use.

std::optional< cosmos::Signal >	m_inject_sig
	signal to inject upon next restart of the tracee.

std::optional< cosmos::ChildState >	m_exit_data
	If tracee exit was observed then this contains the final exit data.

std::optional< cosmos::ProcessID >	m_initial_attacher
	If this Tracee was automatically attached due to AttachThreads{true} then this contains the ProcessID of the initial Thread that caused this.

size_t	m_syscall_ctr = 0
	Number of system calls observed.

AnyRegisterSet	m_initial_regset
	Register set observed during initial attach event stop.

std::optional< cosmos::Signal >	m_stop_signal
	For State::GROUP_STOP this contains the signal that caused it.

ProcessDataPtr	m_process_data
	Shared process data.

size_t	m_max_buffer_prefetch = 128
	Number of bytes system calls will fetch for variable-length data buffers.

Static Protected Attributes inherited from clues::Tracee
static constexpr std::array< cosmos::Signal, 4 >	STOPPING_SIGNALS
	Array of signals that cause tracee stop.

Detailed Description

Specialization of Tracee for automatically attached child tracees.

Automatically attached children will report a ptrace-event stop as initial activity.

Definition at line 13 of file AutoAttachedTracee.hxx.

Constructor & Destructor Documentation

◆ AutoAttachedTracee()

clues::AutoAttachedTracee::AutoAttachedTracee	(	Engine &	engine,
		EventConsumer &	consumer,
		TraceePtr	parent )

Create a traced process object by attaching to the given process ID.

Definition at line 65 of file AutoAttachedTracee.cxx.

                                                                                                :
                Tracee{engine, consumer, parent} {
}

◆ ~AutoAttachedTracee()

clues::AutoAttachedTracee::~AutoAttachedTracee ( )

override

Definition at line 80 of file AutoAttachedTracee.cxx.

                                        {
        try {
                detach();
        } catch (const cosmos::CosmosError &ce) {
                LOG_DEBUG("Couldn't detach from PID " << cosmos::to_integral(m_ptrace.pid()) << ":\n\n" << ce.what());
        }
}

Member Function Documentation

◆ configure()

void clues::AutoAttachedTracee::configure	(	const cosmos::ProcessID	pid,
		const cosmos::ptrace::Event	event,
		const SystemCall &	sc )

Sets the given process ID as the process to be traced.

event and sc describe how the new tracee has come into existence.

Definition at line 69 of file AutoAttachedTracee.cxx.

                                      {
        (void)event;
        setPID(pid);
        m_flags.set(Flag::WAIT_FOR_ATTACH_STOP);
 
        if (!shares_file_descriptors_with_parent(sc)) {
                unshareProcessData();
        }
}

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

include/AutoAttachedTracee.hxx
src/AutoAttachedTracee.cxx