clues::ForeignTracee Class Reference

Specialization of Tracee that attaches to an existing, unrelated process in the system. More...

#include <ForeignTracee.hxx>

Inheritance diagram for clues::ForeignTracee:

Public Member Functions
	ForeignTracee (Engine &engine, EventConsumer &consumer, TraceePtr sibling=nullptr)
	Create a traced process object by attaching to the given process ID.
void	configure (const cosmos::ProcessID tracee)
	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 that attaches to an existing, unrelated process in the system.

Definition at line 9 of file ForeignTracee.hxx.

Constructor & Destructor Documentation

ForeignTracee()

clues::ForeignTracee::ForeignTracee	(	Engine &	engine,
		EventConsumer &	consumer,
		TraceePtr	sibling = nullptr )

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

Definition at line 12 of file ForeignTracee.cxx.

                                   :
                Tracee{engine, consumer, sibling} {
        /*
         * NOTE: the approach using `sibling` for keeping track of process
         * data sharing is relatively simple at the moment but doesn't
         * necessarily cover all situations.
         * An application might explicitly add two threads of the same process
         * to an Engine instance, in which case the process sharing
         * relationship is lost. It's questionable whether such use cases
         * should be supported at all, though.
         *
         * Another approach would be to parse the Tgid from each new Tracee's
         * /proc/<pid>/status file. This involves a lot of additional
         * complexity, however:
         *
         * - parsing the file can fail (e.g. the tracee disappeared in the
         *   meanwhile).
         * - parsing the file for each an every tracee adds additional
         *   overhead (an file I/O for each attach could be especially
         *   problematic).
         * - the Engine would need to keep track of all existing thread groups
         *   and their members, more data that can get out of sync.
         *
         * Thus, for the moment, stick to the simple `sibling` approach which
         * should work well enough for most scenarios.
         */
}

~ForeignTracee()

clues::ForeignTracee::~ForeignTracee ( )

override

Definition at line 45 of file ForeignTracee.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::ForeignTracee::configure

(

const cosmos::ProcessID

tracee

)

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

Definition at line 41 of file ForeignTracee.cxx.

                                                          {
        setPID(tracee);
}

---

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

• include/ForeignTracee.hxx
• src/ForeignTracee.cxx