clues::Tracee Class Reference

Base class for traced processes. More...

#include <Tracee.hxx>

Inheritance diagram for clues::Tracee:

Public Types
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>

Public Member Functions
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

Static Public Member Functions
static const char *	getStateLabel (const State state)

Protected Member Functions
	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
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
static constexpr std::array< cosmos::Signal, 4 >	STOPPING_SIGNALS
	Array of signals that cause tracee stop.

Friends
class	Engine
class	SystemCall

Detailed Description

Base class for traced processes.

The concrete implementation of Tracee defines the means of how the traced process is attached to and detached from etc.

Definition at line 39 of file Tracee.hxx.

Member Typedef Documentation

Flags

using clues::Tracee::Flags = cosmos::BitMask<Flag>

Definition at line 72 of file Tracee.hxx.

Member Enumeration Documentation

Flag

enum class clues::Tracee::Flag

strong

Different flags reflecting the tracer status.

Enumerator
WAIT_FOR_ATTACH_STOP	we're still waiting for the PTRACE_INTERRUPT event stop.
DETACH_AT_NEXT_STOP	as soon as the tracee reaches a stop stace, detach from it.
INJECTED_SIGSTOP	whether we've injected a SIGSTOP that needs to be undone.
INJECTED_SIGCONT	whether we've injected a SIGCONT that needs to be ignored.
SYSCALL_ENTERED	we've seen a syscall-enter-stop and are waiting for the corresponding exit-stop.
WAIT_FOR_EXITED	we've already seen PTHREAD_EVENT_EXIT but are still waiting for CLD_EXITED.
ATTACH_THREADS_PENDING	attach all threads of the process as soon as the initial event stop happens.
SEEN_SIGRETURN	a sigreturn with a pending interrupted system call has been observed.

Definition at line 61 of file Tracee.hxx.

                        {
                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, 
        };

State

enum class clues::Tracee::State

strong

Current tracing state for a single tracee.

These states are modelled after the states described in man(2) ptrace.

Enumerator
UNKNOWN	initial PTRACE_SIZE / PTRACE_INTERRUPT.
RUNNING	tracee is running normally / not in a special trace state.
SYSCALL_ENTER_STOP	system call started.
SYSCALL_EXIT_STOP	system call finished.
SIGNAL_DELIVERY_STOP	signal was delivered.
GROUP_STOP	SIGSTOP executed, the tracee is stopped.
EVENT_STOP	special ptrace event occurred.
DEAD	the tracee no longer exists.
DETACHED	we already detached from the tracee

Definition at line 48 of file Tracee.hxx.

                         {
                UNKNOWN, 
                RUNNING, 
                SYSCALL_ENTER_STOP, 
                SYSCALL_EXIT_STOP, 
                SIGNAL_DELIVERY_STOP, 
                GROUP_STOP, 
                EVENT_STOP, 
                DEAD, 
                DETACHED, 
        };

Constructor & Destructor Documentation

~Tracee()

clues::Tracee::~Tracee ( )

virtual

Definition at line 108 of file Tracee.cxx.

                {
        if (m_state != State::DEAD && m_state != State::DETACHED) {
                LOG_WARN_PID("destroying Tracee in live state");
        }
}

Tracee()

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

explicitprotected

Parameters

[in]

sibling

establish a process data sharing relationship with `sibling. Do this only if you knows that both tracees are related (e.g. member of the same thread group).

Definition at line 100 of file Tracee.cxx.

                                                                         :
                m_engine{engine},
                m_consumer{consumer},
                m_process_data{sibling ?
                        sibling->m_process_data :
                        std::make_shared<ProcessData>()} {
}

Member Function Documentation

alive()

bool clues::Tracee::alive ( ) const

inline

Definition at line 95 of file Tracee.hxx.

                           {
                return pid() != cosmos::ProcessID::INVALID;
        }

attach()

void clues::Tracee::attach ( const FollowChildren follow_children, const AttachThreads attach_threads = AttachThreads{false} )

virtual

Logic to handle attaching to the tracee.

Parameters

[in]

follow_children

If true then newly created child processes will automatically be attached. The EventConsumer interface will received a newChildProcess() callback once a new child process has been attached. This covers all ways by which new child processes can be created (fork, vfork, clone).

Definition at line 133 of file Tracee.cxx.

                                                                                            {
        using Opt = cosmos::ptrace::Opt;
        m_ptrace_opts = cosmos::ptrace::Opts{
                Opt::TRACESYSGOOD,
                Opt::TRACEEXIT,
                Opt::TRACEEXEC,
        };
 
        if (follow_children) {
                m_ptrace_opts.set({
                        Opt::TRACECLONE,
                        Opt::TRACEFORK,
                        Opt::TRACEVFORK,
                        Opt::TRACEVFORKDONE
                });
        }
 
        try {
                seize(m_ptrace_opts);
        } catch (...) {
                if (!isChildProcess()) {
                        changeState(State::DEAD);
                }
                throw;
        }
        updateExecutable();
        updateCmdLine();
        interrupt();
        m_flags.set(Flag::WAIT_FOR_ATTACH_STOP);
        if (m_flags[Flag::INJECTED_SIGSTOP]) {
                // send SIGCONT via kill() instead of via a ptrace injected
                // signal. For some reason, when injecting the signal via
                // ptrace, the stopped state will be applied again after
                // performing a PTRACE_DETACH operation. This could even be a
                // kernel bug.
                cosmos::signal::send(m_ptrace.pid(), cosmos::signal::CONT);
                m_flags.set(Flag::INJECTED_SIGCONT);
        }
 
        if (attach_threads) {
                m_flags.set(Flag::ATTACH_THREADS_PENDING);
        }
}

attachThreads()

void clues::Tracee::attachThreads ( )

protected

Attach to all threads of the current Tracee's process.

Definition at line 725 of file Tracee.cxx.

                           {
        const auto path = cosmos::sprintf("/proc/%d/task",
                        cosmos::to_integral(m_ptrace.pid()));
 
        /*
         * TODO: there is a race condition involved here:
         *
         * We are stopping one of the threads but all the others are still
         * running while we're looking into /proc. Two things can happen here:
         *
         * - threads we're trying to attach might already be lost by the time
         *   we're trying to call ptrace() on them. This is not much of an
         *   issue.
         * - new threads might come into existence that we don't catch in
         *   /proc, and we'll never trace them, giving an incomplete picture.
         *
         * It would be safer to send a SIGSTOP to the whole thread group
         * before attaching, but this would make the attach procedure even
         * more complicated than it already is.
         *
         * It seems `strace` does not take any precautions regarding this
         * matter neither.
         *
         * We could look at /proc/<pid>/status, which has a thread count
         * field. This is again racy, however. We could do this after the
         * fact for verification, or iterate over /proc/<pid>/task until we're
         * sure we've attached all threads.
         */
        cosmos::DirStream task_dir{path};
        const FollowChildren follow_children{
                m_ptrace_opts[cosmos::ptrace::Opt::TRACEFORK]};
 
        for (const auto &entry: task_dir) {
                if (entry.isDotEntry() ||
                                entry.type() != cosmos::DirEntry::Type::DIRECTORY)
                        continue;
 
                auto pid = cosmos::ProcessID{static_cast<int>(std::strtol(entry.name(), nullptr, 10))};
                if (pid == m_ptrace.pid())
                        // ourselves
                        continue;
 
                try {
                        auto tracee = m_engine.addTracee(
                                        pid, follow_children, AttachThreads{false}, this->pid());
                        tracee->m_initial_attacher = m_ptrace.pid();
                } catch (const std::exception &ex) {
                        LOG_WARN_PID("failed to attach to thread " << cosmos::to_integral(pid) << ": " << ex.what());
                }
        }
}

changeState()

void clues::Tracee::changeState ( const State new_state )

protected

Definition at line 336 of file Tracee.cxx.

                                              {
        LOG_DEBUG_PID("state " << m_state << " → " << new_state);
 
        if (new_state == State::SYSCALL_ENTER_STOP) {
                m_flags.set(Flag::SYSCALL_ENTERED);
        } else if (new_state == State::SYSCALL_EXIT_STOP) {
                m_flags.reset(Flag::SYSCALL_ENTERED);
        } else if (new_state == State::GROUP_STOP) {
                if (m_flags[Flag::INJECTED_SIGSTOP]) {
                        // our own injected group stop
                        // let the tracee continue and we're tracing syscalls now
                        m_flags.reset(Flag::INJECTED_SIGSTOP);
                        m_restart_mode = cosmos::Tracee::RestartMode::SYSCALL;
                } else {
                        // enter listen state to avoid restarting a stopped
                        // process as a side-effect.
                        m_restart_mode = cosmos::Tracee::RestartMode::LISTEN;
                }
        } else if (new_state == State::DETACHED) {
                m_flags.reset(Flag::DETACH_AT_NEXT_STOP);
        } else if (new_state == State::DEAD) {
                if (isChildProcess()) {
                        cleanupChild();
                }
        }
 
        if (m_state != State::RUNNING)
                m_prev_state = m_state;
 
        if (m_prev_state == State::GROUP_STOP && m_state != State::GROUP_STOP)
                m_stop_signal = std::nullopt;
 
        m_state = new_state;
}

cleanupChild()

virtual void clues::Tracee::cleanupChild ( )

inlineprotectedvirtual

Definition at line 393 of file Tracee.hxx.

{}

cmdLine()

const cosmos::StringVector & clues::Tracee::cmdLine ( ) const

inline

Definition at line 82 of file Tracee.hxx.

                                                  {
                return m_process_data->cmdline;
        }

currentSystemCallInfo()

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

inline

Definition at line 276 of file Tracee.hxx.

                                                                         {
                return m_syscall_info;
        }

currentSystemCallNr()

std::optional< SystemCallNr > clues::Tracee::currentSystemCallNr

(

)

const

Returns the number of the currently running system call, if any.

Definition at line 974 of file Tracee.cxx.

                                                            {
        if (!m_current_syscall)
                return {};
 
        return m_current_syscall->callNr();
}

detach()

bool clues::Tracee::detach

(

)

Attempt to detach the Tracee.

Detaching is only possible if the tracee is in a stopped state. If this is the case then the detach is performed and true is returned.

Otherwise a future detach will be prepared by adjusting state flags and false is returned.

If the tracee is already detached then nothing happens and true is returned.

Definition at line 177 of file Tracee.cxx.

                    {
        if (!m_ptrace.valid()) {
                return true;
        } else if (m_state == State::DEAD || m_state == State::DETACHED) {
                return true;
        }
 
        if (m_state != State::RUNNING && m_state != State::UNKNOWN) {
                // we can detach immediately
                doDetach();
                return true;
        }
 
        // otherwise we need to indicate that we want to detach at the
        // next ptrace stop we're seeing
        m_flags.set(Flag::DETACH_AT_NEXT_STOP);
 
        if (!m_flags[Flag::WAIT_FOR_ATTACH_STOP]) {
                // interrupt, if not still pending, for being able to detach
                try {
                        interrupt();
                } catch (const cosmos::ApiError &error) {
                        handleError(error);
                }
        }
 
        return false;
}

doDetach()

void clues::Tracee::doDetach ( )

protected

Actually perform a detach without checking tracee state.

This can throw if the current trace state doesn't allow detaching.

Definition at line 206 of file Tracee.cxx.

                      {
        try {
                m_ptrace.detach();
                changeState(State::DETACHED);
        } catch (const cosmos::ApiError &error) {
                handleError(error);
        }
 
        m_ptrace = cosmos::Tracee{};
        m_flags = {};
        m_initial_attacher.reset();
}

dropFD()

void clues::Tracee::dropFD ( const cosmos::FileNum fd ) const

protected

Drop a file descriptor from the tracking of the Tracee's thread group.

Definition at line 1039 of file Tracee.cxx.

                                                {
        if (m_process_data->fd_info_map.erase(fd) != 0) {
                LOG_DEBUG_PID("removed fd " << cosmos::to_integral(fd) << " from registered mappings");
        } else {
                LOG_WARN_PID("closed fd " << cosmos::to_integral(fd) << " wasn't open before?!");
        }
}

engine()

const Engine & clues::Tracee::engine ( ) const

inline

Definition at line 280 of file Tracee.hxx.

                                     {
                return m_engine;
        }

executable()

const std::string & clues::Tracee::executable ( ) const

inline

Definition at line 78 of file Tracee.hxx.

                                            {
                return m_process_data->executable;
        }

exitData()

std::optional< cosmos::ChildState > clues::Tracee::exitData ( ) const

inline

Returns possible tracee exit data.

After the tracee is detached, if tracee exit was observed, this returns the tracee exit information (it's exit status or kill signal etc.).

Definition at line 169 of file Tracee.hxx.

                                                       {
                return m_exit_data;
        }

fdInfoMap()

const FDInfoMap & clues::Tracee::fdInfoMap ( ) const

inline

Provides access to the current knowledge about file descriptors in the tracee.

Definition at line 87 of file Tracee.hxx.

                                           {
                return m_process_data->fd_info_map;
        }

fillData()

template<typename FILLER>

void clues::Tracee::fillData ( ForeignPtr addr, FILLER & filler ) const

protected

Reads data from the Tracee starting at addr and feeds it to filler until it's saturated.

Reads data from the Tracee and feeds it to filler until it's saturated.

Definition at line 924 of file Tracee.cxx.

                                                           {
        long word;
 
        do {
                word = getData(addr);
 
                // get the next word
                addr++;
        } while (filler(word));
}

flags()

Flags clues::Tracee::flags ( ) const

inline

Definition at line 159 of file Tracee.hxx.

                            {
                return m_flags;
        }

getData()

long clues::Tracee::getData

(

const ForeignPtr

addr

)

const

Reads a word of data from the tracee's memory.

The word found at addr is returned from this function on success. On error an exception is thrown.

Definition at line 917 of file Tracee.cxx.

                                                {
        return m_ptrace.peekData(reinterpret_cast<const long*>(
                                cosmos::to_integral(addr)));
}

getInitialRegisters()

void clues::Tracee::getInitialRegisters ( )

protected

Definition at line 986 of file Tracee.cxx.

                                 {
        /*
         * TODO: we don't know on which ABI we're sitting on currently, we
         * could inspect the ELF binary? (like strace does?), but it's also
         * only kind of a heuristic.
         */
 
        try {
                RegisterSet<get_default_abi()> rs;
                getRegisters(rs);
                m_initial_regset = rs;
                if constexpr (rs.ABI == ABI::X86_64) {
                        /*
                         * detecting the X32 ABI is hard when fetching the
                         * initial registers. We need to check for the syscall
                         * bit and redo using the proper ABI in this case.
                         */
                        if ((cosmos::to_integral(rs.abiSyscallNr()) & X32_SYSCALL_BIT) != 0) {
                                RegisterSet<ABI::X32> rs_x32;
                                getRegisters(rs_x32);
                                m_initial_regset = rs_x32;
                        }
                }
        } catch (const cosmos::RuntimeError &) {
                if (get_default_abi() == ABI::X86_64) {
                        RegisterSet<ABI::I386> rs2;
                        getRegisters(rs2);
                        m_initial_regset = rs2;
                } else {
                        throw;
                }
        }
}

getInitialSyscallNr()

std::optional< SystemCallNr > clues::Tracee::getInitialSyscallNr ( const ABI abi ) const

protected

Returns the initial system call nr. stored in m_initial_regset, if available for abi.

Definition at line 818 of file Tracee.cxx.

                                                                         {
        auto visitor = [abi](const auto &rs) -> std::optional<SystemCallNr> {
                if (abi == rs.ABI)
                        return rs.syscallNr();
                return {};
        };
 
        return std::visit(visitor, m_initial_regset);
}

getRegisters()

template<ABI abi>

void clues::Tracee::getRegisters ( RegisterSet< abi > & rs )

protected

Reads the current register set from the process.

This is only possible it the tracee is currently in stopped state.

Definition at line 909 of file Tracee.cxx.

                                              {
        cosmos::InputMemoryRegion iovec;
        rs.fillIov(iovec);
 
        m_ptrace.getRegisterSet(rs.registerType(), iovec);
        rs.iovFilled(iovec);
}

getStateLabel()

const char * clues::Tracee::getStateLabel ( const State state )

static

Definition at line 114 of file Tracee.cxx.

                                                   {
        switch (state) {
                case State::UNKNOWN:              return "UNKNOWN";
                case State::RUNNING:              return "RUNNING";
                case State::SYSCALL_ENTER_STOP:   return "SYSCALL_ENTER_STOP";
                case State::SYSCALL_EXIT_STOP:    return "SYSCALL_EXIT_STOP";
                case State::SIGNAL_DELIVERY_STOP: return "SIGNAL_DELIVERY_STOP";
                case State::GROUP_STOP:           return "GROUP_STOP";
                case State::EVENT_STOP:           return "EVENT_STOP";
                case State::DEAD:                 return "DEAD";
                case State::DETACHED:             return "DETACHED";
                default:                          return "???";
        }
}

handleAttached()

void clues::Tracee::handleAttached ( )

protected

Definition at line 689 of file Tracee.cxx.

                            {
        m_flags.reset(Flag::WAIT_FOR_ATTACH_STOP);
 
        if (!m_flags[Flag::INJECTED_SIGSTOP]) {
                m_restart_mode = cosmos::Tracee::RestartMode::SYSCALL;
        }
 
        getInitialRegisters();
 
        if (m_process_data->fd_info_map.empty()) {
                auto &map = m_process_data->fd_info_map;
                /*
                 * this is a root tracee, either a direct child process or an
                 * initially attached foreign process
                 */
                try {
                        for (auto &info: get_fd_infos(pid())) {
                                map.insert({info.fd, std::move(info)});
                        }
                } catch (const cosmos::CosmosError &error) {
                        LOG_WARN_PID("failed to get initial FD infos: " << error.what());
                }
        }
 
        m_consumer.attached(*this);
 
        if (m_flags[Flag::ATTACH_THREADS_PENDING]) {
                try {
                        attachThreads();
                } catch (const std::exception &e) {
                        LOG_ERROR_PID("failed to attach to other threads: " << e.what());
                }
                m_flags.reset(Flag::ATTACH_THREADS_PENDING);
        }
}

handleError()

void clues::Tracee::handleError ( const cosmos::ApiError & error )

protected

Handle ApiErrors raised from ptrace() requests.

This function will potentially clean up object state but can also rethrow the exception, thus it must be called from a catch block.

Definition at line 219 of file Tracee.cxx.

                                                    {
        if (error.errnum() == cosmos::Errno::SEARCH) {
                // some execve() scenarios end up without a proper
                // exit notification. ignore them.
                if (!m_flags[Flag::WAIT_FOR_EXITED] &&
                                currentSystemCallNr() != SystemCallNr::EXECVE) {
                        LOG_WARN_PID("tracee found to be already dead upon detach()/interrupt()");
                }
                // already gone for some reason
                changeState(State::DEAD);
        } else {
                // shouldn't really happen, unless we're not a
                // tracee for the process at all anyway
                m_ptrace = cosmos::Tracee{};
                throw;
        }
}

handleEvent()

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

protected

Definition at line 536 of file Tracee.cxx.

                                           {
        LOG_INFO_PID("PTRACE_EVENT_" << get_ptrace_event_str(event) << " (" << signal << ")");
 
        using Event = cosmos::ptrace::Event;
 
        switch(event) {
        case Event::STOP: return handleStopEvent(signal);
        case Event::EXIT: return handleExitEvent();
        case Event::EXEC: return handleExecEvent(data.child.pid);
        case Event::CLONE:
        case Event::VFORK:
        case Event::VFORK_DONE:
        case Event::FORK:
                          return handleNewChildEvent(event);
        default: LOG_WARN_PID("PTRACE_EVENT unhandled");
        }
}

handleExecEvent()

void clues::Tracee::handleExecEvent ( const cosmos::ProcessID main_pid )

protected

Definition at line 620 of file Tracee.cxx.

                                                           {
        const auto old_exe = m_process_data->executable;
        const auto old_cmdline = m_process_data->cmdline;
 
        // in a multi-threaded conext we can receive this event under a
        // different PID than we currently have. Thus use a dedicated ptrace
        // wrapper here until we maybe call setPID() below..
        cosmos::Tracee ptrace{main_pid};
 
        std::optional<cosmos::ProcessID> old_pid;
 
        // for a regular execve() this returns the same pid as we have, ignore that
        if (const auto former_pid = ptrace.getPIDEventMsg(); former_pid != main_pid) {
                old_pid = former_pid;
        }
 
        if (old_pid) {
                auto old_tracee = m_engine.handleSubstitution(*old_pid);
                /*
                 * we will receive this event already under the new PID i.e.
                 * if we trace the main thread (which doesn't exec) and the
                 * exec'ing thread as well then we will receive this in main
                 * thread context.
                 *
                 * The "old" main thread no longer exists and we need to sync
                 * state with the actually exec()'ing thread.
                 *
                 * This is good for us currently, because if we have a
                 * ChildTracee running then it will be the main thread and
                 * this thread will stay the main thread in the newly
                 * executing process no matter what. Otherwise we'd have to
                 * abandon the ChildTracee, which holds a SubProc that needs
                 * to be wait()'ed on.
                 */
                if (old_tracee) {
                        syncState(*old_tracee);
                } else {
                        /*
                         * If the old main thread was not traced at all then
                         * `old_tracee` is not available here and we are
                         * already the correct Tracee (Engine takes care of
                         * that).
                         * We have to actively change our own PID, though.
                         */
                        setPID(ptrace.pid());
                }
        }
 
        // only update executable info here, since our PID might have changed
        // above
        updateExecInfo();
 
        /*
         * Check which file descriptors have been closed due to execve.
         */
        syncFDsAfterExec();
 
        m_consumer.newExecutionContext(*this, old_exe, old_cmdline, old_pid);
}

handleExitEvent()

void clues::Tracee::handleExitEvent ( )

protected

Definition at line 581 of file Tracee.cxx.

                             {
 
        EventConsumer::StatusFlags flags;
 
        /*
         * Detecting "lost to execve" is a bit of a heuristic:
         *
         * - regular exit happens due to exit_group(2). No SYSCALL_EXIT_STOP
         *   will be reported for this.
         * - exit due to signal. SIGNAL_DELIVERY_STOP should have been the
         *   last state we saw.
         * - anything else should be execve in multi-threaded process.
         */
 
        const auto wait_status = m_ptrace.getExitEventMsg();
 
        if (wait_status.exited() &&
                        (prevState() != State::SYSCALL_ENTER_STOP ||
                        !cosmos::in_list(*currentSystemCallNr(),
                                {SystemCallNr::EXIT_GROUP, SystemCallNr::EXIT}))) {
                // the exit status in case of an execve() by another thread is simply 0;
                // otherwise the exit status specified by the other thread
                //
                // it seems we cannot really differentiate the exact reason for
                // the exit here, see also "death under ptrace" in ptrace(2).
                //
                // in theory, provided we're tracing all threads of a process,
                // we could inspect all other threads if any has an exit or
                // execve() system call running, but this would still be racy
                // in a lot of ways.
                LOG_INFO_PID("multi-threading related EVENT_EXIT detected");
                flags.set(EventConsumer::StatusFlag::LOST_TO_MT_EXIT);
        }
 
        m_consumer.exited(*this, wait_status, flags);
 
        m_flags.set(Flag::WAIT_FOR_EXITED);
}

handleNewChildEvent()

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

protected

Definition at line 680 of file Tracee.cxx.

                                                              {
        // the engine will perform callbacks at m_consumer, since it is
        // responsible for creating the new Tracee instance.
        //
        // m_current_syscall should always be valid at this point, since the
        // new child must have been created some way.
        m_engine.handleAutoAttach(*this, m_ptrace.getPIDEventMsg(), event, *m_current_syscall);
}

handleSignal()

void clues::Tracee::handleSignal ( const cosmos::SigInfo & info )

protected

Definition at line 524 of file Tracee.cxx.

                                                   {
        LOG_INFO_PID("Signal: " << info.sigNr());
 
        if (m_flags[Flag::INJECTED_SIGCONT] && info.sigNr() == cosmos::signal::CONT) {
                // ignore injected SIGCONT
                m_flags.reset(Flag::INJECTED_SIGCONT);
                return;
        }
 
        m_consumer.signaled(*this, info);
}

handleStateMismatch()

void clues::Tracee::handleStateMismatch ( )

protected

Definition at line 371 of file Tracee.cxx.

                                 {
        LOG_ERROR_PID("encountered system call state mismatch: we believe "
                << (m_flags[Flag::SYSCALL_ENTERED] ? "we already entered " : "we did not enter ")
                << "a system call, but we got a "
                << (m_syscall_info->isEntry() ? "SyscallInfo::ENTRY" : "SyscallInfo::EXIT")
                << " event.");
 
        throw cosmos::RuntimeError{"system call state mismatch"};
}

handleStopEvent()

void clues::Tracee::handleStopEvent ( const cosmos::Signal signal )

protected

Definition at line 556 of file Tracee.cxx.

                                                      {
        if (m_flags[Flag::WAIT_FOR_ATTACH_STOP]) {
                // this is the initial ptrace-stop. now we can start tracing
                LOG_INFO_PID("initial ptrace-stop");
                handleAttached();
        } else if (cosmos::in_container(signal, STOPPING_SIGNALS)) {
                // must be a group stop, unless we're tracing
                // automatically-attached children, which is not yet
                // implemented
                changeState(State::GROUP_STOP);
                m_stop_signal = signal;
                m_consumer.stopped(*this);
        } else if (signal == cosmos::signal::TRAP) {
                // SIGTRAP has quite a blurry meaning in the ptrace()
                // API. From practical experiments and the original
                // strace code I could deduce that for some reason
                // PTRACE_EVENT_STOP combined with SIGTRAP is observed
                // when a SIGCONT is received by a tracee that is
                // currently in group-stop.
                // We then need to restart using system call tracing
                // to see the actual SIGCONT being delivered.
                m_restart_mode = cosmos::Tracee::RestartMode::SYSCALL;
        }
}

handleSystemCall()

void clues::Tracee::handleSystemCall ( )

protected

Definition at line 381 of file Tracee.cxx.

                              {
 
        m_syscall_info = SystemCallInfo{};
        auto &info = *m_syscall_info;
 
        // NOTE: this call can fail if the tracee was killed meanwhile
        m_ptrace.getSyscallInfo(info);
 
        if (m_flags[Flag::SYSCALL_ENTERED]) {
                if (!info.isExit()) {
                        handleStateMismatch();
                }
 
                changeState(State::SYSCALL_EXIT_STOP);
                handleSystemCallExit();
        } else {
                if (!info.isEntry()) {
                        handleStateMismatch();
                }
 
                m_syscall_info->updateSysNr();
 
                changeState(State::SYSCALL_ENTER_STOP);
                handleSystemCallEntry();
        }
 
        m_syscall_info.reset();
}

handleSystemCallEntry()

void clues::Tracee::handleSystemCallEntry ( )

protected

Definition at line 410 of file Tracee.cxx.

                                   {
        EventConsumer::StatusFlags flags;
 
        const SystemCallNr nr = m_syscall_info->sysNr();
        m_current_syscall = &m_syscall_db.get(nr);
 
        if (const auto last_abi = m_current_syscall->abi();
                        last_abi != ABI::UNKNOWN &&
                                last_abi != m_syscall_info->abi()) {
                flags.set(EventConsumer::StatusFlag::ABI_CHANGED);
        }
 
        verifyArch();
 
        if (nr == SystemCallNr::RESTART_SYSCALL) {
                if (m_interrupted_syscall) {
                        m_current_syscall = m_interrupted_syscall;
                        m_interrupted_syscall = nullptr;
                        flags.set(EventConsumer::StatusFlag::RESUMED);
                } else if (m_syscall_ctr != 0) {
                        // explicit restart_syscall done by user space?
                        LOG_WARN_PID("unknown system call is resumed");
                } else if (auto orig_syscall = getInitialSyscallNr(m_syscall_info->abi()); orig_syscall) {
                        // this happens when attaching to a non-child process
                        // and a system call like clock_nanosleep is
                        // interrupted as a result.
                        // we cannot know which system call is being resumed,
                        // since we have no history. restart_syscall() carries
                        // no additional context information pointing us to
                        // the kind of system call that is being resumed.
                        //
                        // it would be quite a feature, though, to know which
                        // system call is being resumed, as it happens quite
                        // often that a process is attached that behaves
                        // unusually e.g. because it blocks.
 
                        // m_initial_regset is obtained during the initial
                        // ptrace-event-stop. It seems it contains the
                        // currently running system call. This only works if
                        // the system call was not interrupted before already,
                        // though.
 
                        if (*orig_syscall != SystemCallNr::RESTART_SYSCALL && SystemCall::validNr(*orig_syscall)) {
                                m_current_syscall = &m_syscall_db.get(*orig_syscall);
                                flags.set(EventConsumer::StatusFlag::RESUMED);
                        }
                }
        } else if (m_interrupted_syscall && m_flags[Flag::SEEN_SIGRETURN]) {
                if (m_interrupted_syscall->callNr() == m_current_syscall->callNr()) {
                        /*
                         * no restart_syscall is used in this case, but we can
                         * still set the flag and cleanup state.
                         */
                        flags.set(EventConsumer::StatusFlag::RESUMED);
                } else {
                        LOG_WARN_PID("unknown system call is resumed after sigreturn");
                }
 
                m_flags.reset(Flag::SEEN_SIGRETURN);
                m_interrupted_syscall = nullptr;
        }
 
        m_current_syscall->setEntryInfo(*this, *m_syscall_info);
        m_syscall_ctr++;
        m_consumer.syscallEntry(*this, *m_current_syscall, flags);
}

handleSystemCallExit()

void clues::Tracee::handleSystemCallExit ( )

protected

Definition at line 477 of file Tracee.cxx.

                                  {
        EventConsumer::StatusFlags flags;
        auto &syscall = *m_current_syscall;
 
        syscall.setExitInfo(*this, *m_syscall_info);
 
        if (auto error = syscall.error(); error && error->hasKernelErrorCode()) {
                // system call was interrupted, remember it for later
                m_interrupted_syscall = m_current_syscall;
                flags.set(EventConsumer::StatusFlag::INTERRUPTED);
        }
 
        m_consumer.syscallExit(*this, syscall, flags);
 
        auto is_sigreturn = [](const SystemCall &call) -> bool {
                switch (call.callNr()) {
                        case SystemCallNr::RT_SIGRETURN: [[fallthrough]];
                        // although this looks legacy it is still used on the I386 ABI
                        case SystemCallNr::SIGRETURN: return true;
                        default: return false;
                }
        };
 
        /*
         * check if this is a sigreturn() system calling marking the end of
         * asynchronous signal handler execution and thus the end of the
         * interruption.
         */
        if (m_interrupted_syscall && is_sigreturn(syscall)) {
                /*
                 * to differentiate transparent restart and visible EINTR
                 * returns we need to check this syscall's return value. If it
                 * succeeds then it is a transparent restart, otherwise a
                 * visible EINTR.
                 */
                if (const auto error = syscall.error(); error &&
                                error->hasErrorCode() &&
                                error->errorCode() == cosmos::Errno::INTERRUPTED) {
                        m_interrupted_syscall = nullptr;
                } else {
                        m_flags.set(Flag::SEEN_SIGRETURN); 
                }
        }
 
        m_current_syscall = nullptr;
}

hasClonedThread()

bool clues::Tracee::hasClonedThread ( ) const

protected

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

Definition at line 237 of file Tracee.cxx.

                                   {
        if (!m_current_syscall)
                return false;
 
        const auto &syscall = *m_current_syscall;
 
        switch (syscall.callNr()) {
                case SystemCallNr::CLONE: {
                        auto &clone_sc = dynamic_cast<const CloneSystemCall&>(syscall);
                        return clone_sc.flags.flags()[cosmos::CloneFlag::THREAD];
                } case SystemCallNr::CLONE3: {
                        auto &clone3_sc = dynamic_cast<const Clone3SystemCall&>(syscall);
                        const auto &args = *clone3_sc.cl_args.args();
                        return args.flags()[cosmos::CloneFlag::THREAD];
                } default: {
                        return false;
                }
        }
}

interrupt()

void clues::Tracee::interrupt ( )

inlineprotected

Forces the traced process to stop.

Definition at line 328 of file Tracee.hxx.

                         {
                m_ptrace.interrupt();
        }

isChildProcess()

virtual bool clues::Tracee::isChildProcess ( ) const

inlinevirtual

Returns whether the tracee is a child process created by us.

If the tracee is a child process then the tracer needs to take care of its lifecycle, while non-related tracee's can just be detached from.

Reimplemented in clues::ChildTracee.

Definition at line 245 of file Tracee.hxx.

                                            {
                return false;
        }

isEnterStop()

bool clues::Tracee::isEnterStop ( ) const

inline

Definition at line 151 of file Tracee.hxx.

                                 {
                return state() == State::SYSCALL_ENTER_STOP;
        }

isExitStop()

bool clues::Tracee::isExitStop ( ) const

inline

Definition at line 155 of file Tracee.hxx.

                                {
                return state() == State::SYSCALL_EXIT_STOP;
        }

isInitiallyAttachedThread()

bool clues::Tracee::isInitiallyAttachedThread ( ) const

inline

Indicates whether this Tracee is an automatically attached thread.

If this is true then the Tracee was attached to due to the AttachThreads{true} setting.

Definition at line 269 of file Tracee.hxx.

                                               {
                return m_initial_attacher != std::nullopt;
        }

isThreadGroupLeader()

bool clues::Tracee::isThreadGroupLeader

(

)

const

Checks in the proc file system whether the Tracee is a thread group leader.

Calling this function is only safe during a ptrace stop.

This information is relevant for the execve in a multi-threaded process situation.

Sadly this bit is not easily accessible via system calls. The only way to determine it is from /proc/<pid>/status or implicitly e.g. a newly fork()'ed process is a thread-group leader while clone()'ed processes can be thread-group leaders (if its not a thread that has been created).

Definition at line 947 of file Tracee.cxx.

                                       {
        const auto path = cosmos::sprintf("/proc/%d/status",
                        cosmos::to_integral(m_ptrace.pid()));
        std::ifstream is{path};
 
        if (!is) {
                // Tracee disappeared?!
                return false;
        }
 
        std::string line;
 
        while (std::getline(is, line).good()) {
                auto parts = cosmos::split(line, ":",
                                cosmos::SplitFlags{cosmos::SplitFlag::STRIP_PARTS});
                if (parts[0] == "Tgid") {
                        auto tgid = std::strtol(parts[1].c_str(), nullptr, 10);
                        return cosmos::ProcessID{static_cast<int>(tgid)} == m_ptrace.pid();
                }
        }
 
        throw cosmos::RuntimeError{"failed to parse Tgid"};
 
        // nothing found?!
        return false;
}

maxBufferPrefetch()

size_t clues::Tracee::maxBufferPrefetch ( ) const

inline

Definition at line 99 of file Tracee.hxx.

                                         {
                return m_max_buffer_prefetch;
        }

pid()

cosmos::ProcessID clues::Tracee::pid ( ) const

inline

Definition at line 91 of file Tracee.hxx.

                                    {
                return m_ptrace.pid();
        }

prevState()

State clues::Tracee::prevState ( ) const

inline

Definition at line 147 of file Tracee.hxx.

                                {
                return m_prev_state;
        }

processEvent()

void clues::Tracee::processEvent ( const cosmos::ChildState & data )

protected

Process the given ptrace event.

This call will be invoked by the Engine class to drive the tracing logic.

Definition at line 837 of file Tracee.cxx.

                                                      {
        m_inject_sig = {};
 
        if (data.exited() || data.killed() || data.dumped()) {
                changeState(State::DEAD);
                if (!m_flags[Flag::WAIT_FOR_EXITED]) {
                        m_consumer.disappeared(*this, data);
                }
                m_exit_data = data;
                return;
        } else if (data.trapped()) {
                if (m_flags[Flag::DETACH_AT_NEXT_STOP]) {
                        doDetach();
                        return;
                }
 
                if (data.signal == cosmos::signal::SYS_TRAP) {
                        try {
                                handleSystemCall();
                        } catch (const std::exception &ex) {
                                /*
                                 * TODO: we need some way to robustly deal
                                 * with unexpected errors during tracing.
                                 *
                                 * we could offer an API to lib clients to let
                                 * them decide what to do.
                                 */
                                throw;
                        }
                } else if (data.signal->isPtraceEventStop()) {
                        changeState(State::EVENT_STOP);
                        const auto [signr, event] = cosmos::ptrace::decode_event(*data.signal);
                        handleEvent(data, event, cosmos::Signal{signr});
                } else {
                        changeState(State::SIGNAL_DELIVERY_STOP);
                        cosmos::SigInfo info;
                        m_ptrace.getSigInfo(info);
                        handleSignal(info);
                        m_inject_sig = *data.signal;
                }
        } else if (data.signaled()) {
                // it seems this branch is never hit, signals are
                // always handled as a TRAP, never as regular events
                // when tracing.
                // TODO: but for direct child processes that we want to stop
                // tracing this could happen after detaching.
                LOG_WARN_PID("seeing non-trap signal delivery stop");
                changeState(State::SIGNAL_DELIVERY_STOP);
                cosmos::SigInfo info;
                m_ptrace.getSigInfo(info);
                handleSignal(info);
                m_inject_sig = *data.signal;
        } else {
                LOG_WARN_PID("Other Tracee event?");
        }
 
        if (m_state == State::DEAD || m_state == State::DETACHED)
                return;
 
        // NOTE: this can fail with ESRCH if the tracee got killed meanwhile
        restart(m_restart_mode, m_inject_sig);
 
        if (m_restart_mode != cosmos::Tracee::RestartMode::LISTEN) {
                const auto resumed = m_state == State::GROUP_STOP;
                changeState(State::RUNNING);
                if (resumed) {
                        m_consumer.resumed(*this);
                }
        }
}

readBlob()

void clues::Tracee::readBlob	(	const ForeignPtr	addr,
		char *	buffer,
		const size_t	bytes ) const

Reads an arbitrary binary blob of fixed length from the tracee.

Definition at line 981 of file Tracee.cxx.

                                                                                   {
        BlobFiller filler{bytes, buffer};
        fillData(addr, filler);
}

readString()

void clues::Tracee::readString	(	const ForeignPtr	addr,
		std::string &	out ) const

Reads a zero-terminated C-string from the tracee.

Read from the tracee's address space starting at addr into the C++ string object out.

Definition at line 935 of file Tracee.cxx.

                                                                   {
        return readVector(addr, out);
}

readStruct()

template<typename T, bool CHECK_TRIVIAL = true>

bool clues::Tracee::readStruct ( const ForeignPtr addr, T & out ) const

inline

Reads a system call struct from the tracee's address space into out.

Returns

true if out could be filled, false otherwise (e.g. nullptr was encouneterd).

Definition at line 221 of file Tracee.hxx.

                                                             {
                // the address of the struct in the tracee's address space
                if (addr == ForeignPtr::NO_POINTER)
                        // null address specification
                        return false;
 
                if constexpr (CHECK_TRIVIAL) {
                        static_assert(std::is_trivial_v<T> == true);
                }
 
                readBlob(addr, reinterpret_cast<char*>(&out), sizeof(T));
                return true;
        }

readVector()

template<typename VECTOR>

void clues::Tracee::readVector	(	const ForeignPtr	pointer,
		VECTOR &	out ) const

Reads in a zero terminated array of data items into the STL-vector like parameter out.

Definition at line 940 of file Tracee.cxx.

                                                                {
        out.clear();
 
        ContainerFiller<VECTOR> filler{out};
        fillData(addr, filler);
}

restart()

void clues::Tracee::restart ( const cosmos::Tracee::RestartMode mode = cosmos::Tracee::RestartMode::CONT, const std::optional< cosmos::Signal > signal = {} )

inlineprotected

Restarts the traced process, optionally delivering signal.

Definition at line 333 of file Tracee.hxx.

                                                                 {}) {
                m_ptrace.restart(mode, signal);
        }

seize()

void clues::Tracee::seize ( const cosmos::ptrace::Opts opts )

inlineprotected

Makes the tracee a tracee.

Definition at line 344 of file Tracee.hxx.

                                                {
                m_ptrace.seize(opts);
        }

setMaxBufferPrefetch()

void clues::Tracee::setMaxBufferPrefetch ( const size_t bytes )

inline

Sets an upper limit for the retrieval of variable-length buffer parameters in system calls.

System calls like read() and write() process variable-length raw buffer data, which can be quite large. Fetching the complete buffer contents from tracee memory for all these system calls can affect tracing performance, especially when the full buffer data is not actually needed by the tracer application.

By default only a small part of the buffer data will be automatically fetched by specializations of SystemCall. You can set this to 0 to completely disable prefetching of buffer data or to SIZE_MAX to always fetch the complete buffers from tracees. In case the buffer data has not been completely pre-fetched, but the application is interested in the buffer data for a specific system call only, then the application can explicitly fetch the rest of the data from the tracee during a system call stop event.

This is a per-tracee setting to allow tracee-specific variations of this setting.

Definition at line 123 of file Tracee.hxx.

                                                      {
                m_max_buffer_prefetch = bytes;
        }

setOptions()

void clues::Tracee::setOptions ( const cosmos::ptrace::Opts opts )

inlineprotected

Applies the given trace flags.

Definition at line 339 of file Tracee.hxx.

                                                     {
                m_ptrace.setOptions(opts);
        }

setPID()

void clues::Tracee::setPID ( const cosmos::ProcessID tracee )

protected

Sets the tracee PID.

Definition at line 129 of file Tracee.cxx.

                                                {
        m_ptrace = cosmos::Tracee{tracee};
}

state()

State clues::Tracee::state ( ) const

inline

Definition at line 143 of file Tracee.hxx.

                            {
                return m_state;
        }

stopSignal()

std::optional< cosmos::Signal > clues::Tracee::stopSignal ( ) const

inline

For state() == State::GROUP_STOP this returns the stopping signal that caused it.

Definition at line 137 of file Tracee.hxx.

                                                     {
                return m_stop_signal;
        }

syncFDsAfterExec()

void clues::Tracee::syncFDsAfterExec ( )

protected

Definition at line 309 of file Tracee.cxx.

                              {
        /*
         * We could mimic what the kernel does by inspecting the file
         * descriptor flags. To prevent any inconsistencies and because it
         * shouldn't bee too expensive to do this for each execve(),
         * synchronize the state with what is found in /proc/<pid>/fd.
         */
        try {
                auto left_fds = clues::get_currently_open_fds(m_ptrace.pid());
 
                auto &fd_info_map = m_process_data->fd_info_map;
 
                for (auto it = fd_info_map.begin(); it != fd_info_map.end(); it++) {
                        if (left_fds.count(it->first) == 0) {
                                it = fd_info_map.erase(it);
                        }
                }
        } catch (const cosmos::ApiError &ex) {
                /* It seems the process died.
                 * The Tracee will be cleaned up soon anyway, so let's keep
                 * the file descriptors we've seen last time to avoid further
                 * confusion.
                 */
                LOG_WARN_PID("unable to get currently open fds: " << ex.what());
        }
}

syncState()

void clues::Tracee::syncState ( Tracee & other )

protected

Definition at line 828 of file Tracee.cxx.

                                    {
        m_syscall_info = other.m_syscall_info;
        m_syscall_db = std::move(other.m_syscall_db);
        m_current_syscall = other.m_current_syscall;
        m_interrupted_syscall = other.m_interrupted_syscall;
        m_syscall_ctr = other.m_syscall_ctr;
        other.changeState(State::DEAD);
}

syscallCtr()

size_t clues::Tracee::syscallCtr ( ) const

inline

Returns the number of system calls observed so far.

This counts the number of system call entries observed while tracing this PID.

Definition at line 132 of file Tracee.hxx.

                                  {
                return m_syscall_ctr;
        }

trackFD()

void clues::Tracee::trackFD ( FDInfo && info ) const

protected

Track a new file descriptor for this Tracee's thread group.

This function is intended in the context of SystemCall exit based on the knowledge of concrete SystemCall implementations.

Definition at line 1024 of file Tracee.cxx.

                                        {
        const auto fd = info.fd;
        auto res = m_process_data->fd_info_map.insert(
                std::make_pair(fd, std::move(info))
        );
 
        if (!res.second) {
                LOG_WARN_PID("FD " << cosmos::to_integral(fd) << " was already open?!");
                // bail out
                return;
        }
 
        LOG_DEBUG_PID("new file descriptor tracking for fd " << cosmos::to_integral(fd));
}

unshareProcessData()

void clues::Tracee::unshareProcessData ( )

protected

Definition at line 1020 of file Tracee.cxx.

                                {
        m_process_data = std::make_shared<ProcessData>(*m_process_data);
}

updateCmdLine()

void clues::Tracee::updateCmdLine ( )

protected

Definition at line 284 of file Tracee.cxx.

                           {
        // the cmdline file contains null terminator separated strings
        // the tracee controls this data and could place crafted data here.
        //
        // obtain the data from here instead of from execve() has the
        // following advantages:
        // - it works the same for newly created tracee's as for tracee's
        // we're attaching to during runtime.
        // - we can obtain the information without having to find the correct
        // syscall-exit stop context that caused a ptrace-exec event stop.
        const auto path = cosmos::sprintf("/proc/%d/cmdline", cosmos::to_integral(m_ptrace.pid()));
 
        m_process_data->cmdline.clear();
 
        std::ifstream is{path};
        if (!is) {
                // see updateExecutable() for the rationale here
                return;
        }
        std::string arg;
        while (std::getline(is, arg, '\0').good()) {
                m_process_data->cmdline.push_back(arg);
        }
}

updateExecInfo()

void clues::Tracee::updateExecInfo ( )

inlineprotected

Definition at line 318 of file Tracee.hxx.

                              {
                updateExecutable();
                updateCmdLine();
        }

updateExecutable()

void clues::Tracee::updateExecutable ( )

protected

Definition at line 257 of file Tracee.cxx.

                              {
        // obtain the executable name from proc.
        // as long as we're tracing the PID there is no race involved.
        // this information is more reliable than what we see in execve(),
        // since symlinks or other magic might be involved.
        const auto path = cosmos::sprintf("/proc/%d/exe", cosmos::to_integral(m_ptrace.pid()));
        try {
                m_process_data->executable = cosmos::fs::read_symlink(path);
        } catch (const cosmos::ApiError &e) {
                // likely ENOENT, tracee disappeared
                // but can this even happen while we're tracing it? and even
                // if it happens, then no more tracing will happen, so the
                // information is no longer relevant.
                //
                // As a fallback we could rely on the less precise information
                // from evecve-entry. The issue is that the execve-event-stop
                // happens before system-call-exit-stop and also that in
                // multi-threaded contexts, the actual execve system call data
                // might be in a wholly different tracee, or one that we're
                // not even tracing.
                //
                // so let's ignore this for the moment, assuming that this is
                // not a relevant situation anyway.
                m_process_data->executable.clear();
        }
}

verifyArch()

void clues::Tracee::verifyArch ( )

protected

Verifies the tracee's architecture according to m_syscall_info, throws on mismatch.

Definition at line 777 of file Tracee.cxx.

                        {
        /*
         * A Tracee can change "personality" during its lifetime, thus every
         * system call has to be observed for changes in ABI. In theory the
         * same binary could even employ multiple calling conventions at the
         * same time.
         *
         * The usual situation is that 32-bit programs can also be executed on
         * 64-bit operating systems. This is not only the case on x86_64 but
         * also on powerpc64, arm64 etc. On x86 we even have three different
         * ABIs: i386, x86_64 and x32. The latter is using the amd64
         * instruction set but only 32-bit data types.
         *
         * To support these different ABIs we use an abstract SystemCallNr
         * which is the same for all ABIs, allowing us to identify the correct
         * system calls. Differences between ABIs might still need to be taken
         * into account by concrete SystemCall instances (e.g. differently
         * sized structures when running 32-bit emulation binaries).
         */
        using Arch = cosmos::ptrace::Arch;
        switch (m_syscall_info->arch()) {
                case Arch::I386:
                        if (cosmos::arch::X86_64) {
                                // 32-bit emulation, should work out of the box
                        }
                        return;
                case Arch::X86_64:
                        if (!cosmos::arch::X86_64) {
                                throw cosmos::RuntimeError{"tracing 64-bit binaries with a 32-bit tracer is not supported"};
                        }
                        return;
                case Arch::AARCH64:
                        if (!cosmos::arch::AARCH64) {
                                throw cosmos::RuntimeError{"tracing 64-bit binaries with a 32-bit tracer is not supported"};
                        }
                        return;
                default:
                        throw cosmos::RuntimeError{"tracing this architecture/ABI is not currently supported"};
        }
}

Friends And Related Symbol Documentation

Engine

friend class Engine

friend

Definition at line 40 of file Tracee.hxx.

SystemCall

friend class SystemCall

friend

Definition at line 41 of file Tracee.hxx.

Member Data Documentation

m_consumer

EventConsumer& clues::Tracee::m_consumer

protected

Callback interface receiving our information.

Definition at line 436 of file Tracee.hxx.

m_current_syscall

SystemCall* clues::Tracee::m_current_syscall = nullptr

protected

Holds state for the currently executing system call.

Definition at line 452 of file Tracee.hxx.

m_engine

Engine& clues::Tracee::m_engine

protected

The engine that manages this tracee.

Definition at line 434 of file Tracee.hxx.

m_exit_data

std::optional<cosmos::ChildState> clues::Tracee::m_exit_data

protected

If tracee exit was observed then this contains the final exit data.

Definition at line 460 of file Tracee.hxx.

m_flags

Flags clues::Tracee::m_flags

protected

These keep track of various state on the tracer side.

Definition at line 442 of file Tracee.hxx.

m_initial_attacher

std::optional<cosmos::ProcessID> clues::Tracee::m_initial_attacher

protected

If this Tracee was automatically attached due to AttachThreads{true} then this contains the ProcessID of the initial Thread that caused this.

Definition at line 462 of file Tracee.hxx.

m_initial_regset

AnyRegisterSet clues::Tracee::m_initial_regset

protected

Register set observed during initial attach event stop.

Definition at line 466 of file Tracee.hxx.

m_inject_sig

std::optional<cosmos::Signal> clues::Tracee::m_inject_sig

protected

signal to inject upon next restart of the tracee.

Definition at line 458 of file Tracee.hxx.

m_interrupted_syscall

SystemCall* clues::Tracee::m_interrupted_syscall = nullptr

protected

Previous system call, if it has been interrupted.

Definition at line 454 of file Tracee.hxx.

m_max_buffer_prefetch

size_t clues::Tracee::m_max_buffer_prefetch = 128

protected

Number of bytes system calls will fetch for variable-length data buffers.

Definition at line 472 of file Tracee.hxx.

m_prev_state

State clues::Tracee::m_prev_state = State::UNKNOWN

protected

The previous Tracee state we've seen (except RUNNING).

Definition at line 440 of file Tracee.hxx.

m_process_data

ProcessDataPtr clues::Tracee::m_process_data

protected

Shared process data.

Definition at line 470 of file Tracee.hxx.

m_ptrace

cosmos::Tracee clues::Tracee::m_ptrace

protected

libcosmos API for the Tracee.

Definition at line 444 of file Tracee.hxx.

m_ptrace_opts

cosmos::ptrace::Opts clues::Tracee::m_ptrace_opts

protected

The options we've set for ptrace().

Definition at line 446 of file Tracee.hxx.

m_restart_mode

cosmos::Tracee::RestartMode clues::Tracee::m_restart_mode = cosmos::Tracee::RestartMode::CONT

protected

current RestartMode to use.

Definition at line 456 of file Tracee.hxx.

m_state

State clues::Tracee::m_state = State::UNKNOWN

protected

The current state the tracee is in.

Definition at line 438 of file Tracee.hxx.

m_stop_signal

std::optional<cosmos::Signal> clues::Tracee::m_stop_signal

protected

For State::GROUP_STOP this contains the signal that caused it.

Definition at line 468 of file Tracee.hxx.

m_syscall_ctr

size_t clues::Tracee::m_syscall_ctr = 0

protected

Number of system calls observed.

Definition at line 464 of file Tracee.hxx.

m_syscall_db

SystemCallDB clues::Tracee::m_syscall_db

protected

Reusable database object for tracing system calls.

Definition at line 450 of file Tracee.hxx.

m_syscall_info

std::optional<SystemCallInfo> clues::Tracee::m_syscall_info

protected

The current system call information, if any.

Definition at line 448 of file Tracee.hxx.

STOPPING_SIGNALS

std::array<cosmos::Signal, 4> clues::Tracee::STOPPING_SIGNALS

staticconstexprprotected

Initial value:

= {
                cosmos::signal::STOP, cosmos::signal::TERM_STOP,
                cosmos::signal::TERM_INPUT, cosmos::signal::TERM_OUTPUT
        }

Array of signals that cause tracee stop.

Stopping signals are treated specially during tracing since they result in a group-stop state change. This constexpr array is used to identify them.

Definition at line 292 of file Tracee.hxx.

                                                                      {
                cosmos::signal::STOP, cosmos::signal::TERM_STOP,
                cosmos::signal::TERM_INPUT, cosmos::signal::TERM_OUTPUT
        };

---

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

• include/Tracee.hxx
• src/Tracee.cxx