Thin wrapper class around the ptrace() system call. More...

#include <Tracee.hxx>

Public Types
enum class	RestartMode { CONT = to_integral(ptrace::Request::CONT) , DETACH = to_integral(ptrace::Request::DETACH) , SYSCALL = to_integral(ptrace::Request::SYSCALL) , SINGLESTEP = to_integral(ptrace::Request::SINGLESTEP) , LISTEN = to_integral(ptrace::Request::LISTEN) }
	Different ways to restart a tracee. More...

Public Member Functions
	Tracee (const ProcessID pid=ProcessID::INVALID)

ProcessID	pid () const

bool	valid () const

void	seize (const ptrace::Opts opts)
	Seize a tracee.

void	attach ()
	Attach to a process, making it a tracee.

void	detach ()
	Detach from and restart the tracee.

void	restart (const RestartMode mode, const std::optional< Signal > signal={})
	Continues a traced process, optionally delivering `signal`.

void	interrupt ()
	Interrupt the tracee.

void	setOptions (const ptrace::Opts opts)
	Set tracing options for the given tracee.

long	peekData (const long *addr) const
	Read one word of data from the tracee's memory.

void	pokeData (const long *addr, long value)
	Write one word of data into the tracee's memory.

long	peekUser (const long *offset) const
	Read one word of data from the tracee's user area.

void	pokeUser (const long *offset, long value)
	Change one word of data in the tracee's user area.

void	getRegisters (struct user_regs_struct &out) const
	Copy the tracee's general purpose registers into the provided structure.

void	setRegisters (const struct user_regs_struct &out)
	Modify the tracee's general purpose registers.

void	getFloatRegisters (struct user_fpregs_struct &out) const
	Copy the tracee's floating point registers into the provided structure.

void	setFloatRegisters (const struct user_fpregs_struct &out)
	Modify the tracee's floating point registers.

void	getRegisterSet (const ptrace::RegisterType type, InputMemoryRegion &iovec) const
	Retrieve a set of registers from the tracee.

void	setRegisterSet (const ptrace::RegisterType type, OutputMemoryRegion &iovec)
	Modify a set of registers in the tracee.

void	getSigInfo (SigInfo &info) const
	Obtain information about the signal that caused the stop.

void	setSigInfo (const SigInfo &info)
	Set signal information for the tracee.

std::vector< SigInfo >	peekSigInfo (const ptrace::PeekSigInfo &settings)
	Obtains SigInfo structures pending for the tracee.

void	getSigMask (SigSet &set) const
	Obtain the tracee's mask of blocked signals.

void	setSigMask (const SigSet &set)
	Change the tracee's mask of blocked signals.

ProcessID	getPIDEventMsg () const
	Returns the PID of a newly created child of the tracee in the context of a ptrace-event-stop.

ExitStatus	getExitEventMsg () const
	Returns the exit code of the tracee in the context of a ptrace-event-stop.

uint16_t	getSeccompRetDataEventMsg () const
	Returns the SECCOMP_RET_DATA in the context of a ptrace-event-stop.

void	getSeccompFilter (std::vector< struct sock_filter > &instructions, const unsigned long prog_index) const
	Retrieve a classic seccomp BPF program installed in the tracee.

void	getSyscallInfo (ptrace::SyscallInfo &info) const
	Returns system call information in the context of the current ptrace stop.

Protected Member Functions
unsigned long	getEventMsg () const
	Returns the current event message for a ptrace-event-stop.

template<typename ADDR = void, typename DATA = void>
std::optional< long >	request (const ptrace::Request req, ADDR addr=nullptr, DATA data=nullptr) const

template<typename DATA = void*>
std::optional< long >	request (const ptrace::Request req, std::nullptr_t, DATA data=nullptr) const

Protected Attributes
ProcessID	m_pid

Detailed Description

Thin wrapper class around the ptrace() system call.

This is a type safe wrapper around the ptrace() system call. An instance of this type always operates on the same process supplied during construction time. There are no resources managed by this class.

The ptrace() API is highly complex and this class can only offer some basic wrappers and documentation about it.

Definition at line 41 of file Tracee.hxx.

Member Enumeration Documentation

◆ RestartMode

enum class cosmos::Tracee::RestartMode

strong

Different ways to restart a tracee.

This is a sub-set of the commands from ptrace::Request that deal with restarting the tracee in different ways. All of these requests optionally accept a signal to inject, except for RestartMode::LISTEN.

Definition at line 51 of file Tracee.hxx.

                               {
                CONT              = to_integral(ptrace::Request::CONT),
                DETACH            = to_integral(ptrace::Request::DETACH),
                SYSCALL           = to_integral(ptrace::Request::SYSCALL),
                SINGLESTEP        = to_integral(ptrace::Request::SINGLESTEP),
#ifdef PTRACE_SYSEMU
                SYSEMU            = to_integral(ptrace::Request::SYSEMU),
                SYSEMU_SINGLESTEP = to_integral(ptrace::Request::SYSEMU_SINGLESTEP),
#endif
                LISTEN            = to_integral(ptrace::Request::LISTEN)
        };

Constructor & Destructor Documentation

◆ Tracee()

cosmos::Tracee::Tracee ( const ProcessID pid = ProcessID::INVALID )

inlineexplicit

Definition at line 65 of file Tracee.hxx.

                                                                :
                        m_pid{pid}
        {}

Member Function Documentation

◆ attach()

void cosmos::Tracee::attach ( )

inline

Attach to a process, making it a tracee.

This is the old method of making a process a tracee. Tracers attached to this way don't support all ptrace() operations and it is not recommended to use this method anymore.

The tracee will be sent a SIGSTOP signal, the tracer needs to wait on the tracee to assert it has entered stop state as a result of the attach operation. The synthetic SIGSTOP event should be suppressed by the tracer.

This method of attaching to the tracee has inherent race conditions. Other signals can concurrently occur while the tracer attempts to attach to it. Events other than SIGSTOP should be reinjected until SIGSTOP is observed. This does not reliably work if SIGSTOP itself is occurring in parallel, making attach() unreliable.

Definition at line 110 of file Tracee.hxx.

                      {
                this->request(ptrace::Request::ATTACH);
        }

◆ detach()

void cosmos::Tracee::detach ( )

inline

Detach from and restart the tracee.

The tracee will be restarted (if currently in a tracing stop), the process will no longer be traced. This method can be used regardless of whether the tracee was seize()'d or attach()'d to.

Definition at line 120 of file Tracee.hxx.

                      {
                this->request(ptrace::Request::DETACH);
        }

◆ getEventMsg()

unsigned long cosmos::Tracee::getEventMsg ( ) const

inlineprotected

Returns the current event message for a ptrace-event-stop.

The interpretation of the returned value depends on the ptrace::Event that has been reported. If there is no (matching) ptrace-event, then the return value seems to be undefined.

Definition at line 409 of file Tracee.hxx.

                                          {
                unsigned long msg = 0;
                this->request(ptrace::Request::GETEVENTMSG, nullptr, &msg);
                return msg;
        }

◆ getExitEventMsg()

ExitStatus cosmos::Tracee::getExitEventMsg ( ) const

inline

Returns the exit code of the tracee in the context of a ptrace-event-stop.

This request is only valid during a ptrace-event-stop when ptrace::Event::EXIT is reported.

The return value is the exit status of the exited tracee process.

Definition at line 331 of file Tracee.hxx.

                                           {
                const auto status = getEventMsg();
                return static_cast<ExitStatus>(status);
        }

◆ getFloatRegisters()

void cosmos::Tracee::getFloatRegisters ( struct user_fpregs_struct & out ) const

inline

Copy the tracee's floating point registers into the provided structure.

This is similar to getRegisters() but provides the floating point registers instead.

Preferably use getRegisterSet() instead.

Definition at line 243 of file Tracee.hxx.

                                                                     {
                // NOTE: see getRegisters() about Sparc architecture
                this->request(ptrace::Request::GETFPREGS, nullptr, &out);
        }

◆ getPIDEventMsg()

ProcessID cosmos::Tracee::getPIDEventMsg ( ) const

inline

Returns the PID of a newly created child of the tracee in the context of a ptrace-event-stop.

This request is only valid during a ptrace-event-stop and when ptrace::Event::FORK, ptrace::EVENT::VFORK, ptrace::Event::VFORK_DONE or ptrace::Event::CLONE is reported.

The return value is the PID of the newly created child process.

Definition at line 319 of file Tracee.hxx.

                                         {
                const auto pid = getEventMsg();
                return static_cast<ProcessID>(pid);
        }

◆ getRegisters()

void cosmos::Tracee::getRegisters ( struct user_regs_struct & out ) const

inline

Copy the tracee's general purpose registers into the provided structure.

You need to include sys/user.h and check out the data structure found in there for details. This is a low level structure specially designed for GDB and also not available on all architectures.

Preferably use getRegisterSet() instead.

Definition at line 219 of file Tracee.hxx.

                                                              {
                // NOTE: on Sparc the address needs to be passed as third
                // argument, not as fourth. If we should ever want to support
                // it, we'd need an #ifdef of some sort.
                this->request(ptrace::Request::GETREGS, nullptr, &out);
        }

◆ getRegisterSet()

void cosmos::Tracee::getRegisterSet	(	const ptrace::RegisterType	type,
		InputMemoryRegion &	iovec ) const

inline

Retrieve a set of registers from the tracee.

This retrieves binary data based on an I/O vector. For ptrace::RegisterType::GENERAL_PURPOSE the target data structure is found in elf.h called elf_gregset_t.

The kernel will update iovec to reflect the actual amount of data that has been returned.

Definition at line 265 of file Tracee.hxx.

                                                                                           {
                this->request(ptrace::Request::GETREGSET, type, iovec.asIovec());
        }

◆ getSeccompFilter()

void cosmos::Tracee::getSeccompFilter	(	std::vector< struct sock_filter > &	instructions,
		const unsigned long	prog_index ) const

Retrieve a classic seccomp BPF program installed in the tracee.

prog_index is the index of the program to return, where index 0 is the most recently installed program. If the index is greater than the number of installed programs then an ApiError with Errno::NO_ENTRY is thrown.

If instructions is empty then the call will first ask the kernel how big the given program is, to dimension instructions accordingly. In a second call the program is retrieved into the vector.

If instructions is non-empty then the provided size will be used. Note that there seems to be error handling missing in the kernel to detect when the provided vector is too small. This means a too small vector could lead to memory corruption in the process.

Definition at line 14 of file Tracee.cxx.

                                                                                                               {
 
        if (instructions.empty()) {
                const auto num_progs = this->request(ptrace::Request::SECCOMP_GET_FILTER, prog_index);
                instructions.resize(*num_progs);
        }
 
        struct sock_fprog fprog;
        fprog.len = instructions.size();
        fprog.filter = instructions.data();
 
        const auto num_progs = this->request(ptrace::Request::SECCOMP_GET_FILTER, prog_index, &fprog);
 
        /*
         * This ptrace request actually seems to be missing a size check in
         * the kernel. We do communicate the number of filters we have in
         * fprog.len, but the kernel simply copies into the sock_fprog
         * whatever amount of data it has. This could lead to memory
         * corruption or a SIGSEGV.
         * TODO: test what exactly happens.
         */
 
        if (*num_progs < 0 || static_cast<unsigned long>(*num_progs) >= instructions.size()) {
                cosmos_throw (RuntimeError("seccomp filter array size inconsistency"));
        }
}

◆ getSeccompRetDataEventMsg()

uint16_t cosmos::Tracee::getSeccompRetDataEventMsg ( ) const

inline

Returns the SECCOMP_RET_DATA in the context of a ptrace-event-stop.

This request is only valid during a ptrace-event-stop when ptrace::Event::SECCOMP is reported.

The return value is the 16-bit value known as SECCOMP_RET_DATA, see seccomp(2).

Definition at line 344 of file Tracee.hxx.

                                                   {
                const auto seccomp_ret_data = getEventMsg();
                return static_cast<uint16_t>(seccomp_ret_data);
        }

◆ getSigInfo()

void cosmos::Tracee::getSigInfo ( SigInfo & info ) const

Obtain information about the signal that caused the stop.

Definition at line 61 of file Tracee.cxx.

                                           {
        this->request(ptrace::Request::GETSIGINFO, nullptr, info.raw());
}

◆ getSigMask()

void cosmos::Tracee::getSigMask ( SigSet & set ) const

inline

Obtain the tracee's mask of blocked signals.

Definition at line 302 of file Tracee.hxx.

                                           {
                this->request(ptrace::Request::GETSIGMASK, sizeof(*set.raw()), set.raw());
        }

◆ getSyscallInfo()

void cosmos::Tracee::getSyscallInfo ( ptrace::SyscallInfo & info ) const

Returns system call information in the context of the current ptrace stop.

This request is only valid during syscall-entry-stop, syscall-exit-stop or ptrace-event-stop for ptrace::Event::SECCOMP.

Depending on the type of stop that occurred info will contain different data, thus only certain parts of the struct are accessible via std::optional return values.

Definition at line 53 of file Tracee.cxx.

                                                         {
        const auto obtained = this->request(ptrace::Request::GET_SYSCALL_INFO, sizeof(*info.raw()), info.raw());
 
        if (*obtained < 0 || static_cast<unsigned long>(*obtained) > sizeof(*info.raw())) {
                cosmos_throw (RuntimeError("excess SYSCALL_INFO data, truncation occurred!"));
        }
}

◆ interrupt()

void cosmos::Tracee::interrupt ( )

inline

Interrupt the tracee.

This works only on tracees attached via seize(). As a result to the interrupt the tracee can enter:

syscall-exit-stop if ptrace::Request::SYSCALL is in effect. The interrupted system call is restarted when the tracee is restarted.
if the tracee was already stopped by a signal and ptrace::Request::LISTEN was sent to it then a ptrace-event-stop is reported with the stop signal.
if another ptrace-stop is triggered in parallel, then this stop happens.
otherwise a ptrace-event-stop for signal SIGTRAP happens.

Definition at line 156 of file Tracee.hxx.

                         {
                this->request(ptrace::Request::INTERRUPT);
        }

◆ peekData()

long cosmos::Tracee::peekData ( const long * addr ) const

inline

Read one word of data from the tracee's memory.

addr specifies the address in the tracee's memory to read a word from.

The size of the word is defined by the type of operating system and architecture of the system. On Linux no differentiation between TEXT and DATA is made, thus only DATA is offered here.

Definition at line 179 of file Tracee.hxx.

                                              {
                return *(this->request(ptrace::Request::PEEKDATA, addr));
        }

◆ peekSigInfo()

std::vector< SigInfo > cosmos::Tracee::peekSigInfo ( const ptrace::PeekSigInfo & settings )

Obtains SigInfo structures pending for the tracee.

Based on settings obtain a numer of SigInfo structures pending for the tracee. settings define how many SigInfo will be retrieved at max and from what position in the signal queue.

There is no way to know how many entries exist currently (this information can also rapidly change). If no more SigInfo structures exist at the given position then a short or zero item count is returned.

Definition at line 69 of file Tracee.cxx.

                                                                        {
        const auto raw_settings = settings.raw();
        std::vector<SigInfo> ret;
        ret.resize(raw_settings->nr);
 
        const auto num_entries = this->request(
                        ptrace::Request::PEEKSIGINFO, raw_settings, ret.data());
 
        ret.resize(*num_entries);
 
        return ret;
}

◆ peekUser()

long cosmos::Tracee::peekUser ( const long * offset ) const

inline

Read one word of data from the tracee's user area.

The user area refers to the kernel's struct user which contains data about registers and other information about the process. This data is highly OS and architecture specific and could yield unexpected results.

The given parameter is an offset into struct user where to read from. The offset typically needs to be word-aligned.

Definition at line 198 of file Tracee.hxx.

                                                {
                return *(this->request(ptrace::Request::PEEKUSER, offset));
        }

◆ pid()

ProcessID cosmos::Tracee::pid ( ) const

inline

Definition at line 69 of file Tracee.hxx.

                              {
                return m_pid;
        }

◆ pokeData()

void cosmos::Tracee::pokeData	(	const long *	addr,
		long	value )

inline

Write one word of data into the tracee's memory.

Definition at line 184 of file Tracee.hxx.

                                                    {
                this->request(ptrace::Request::POKEDATA, addr, value);
        }

◆ pokeUser()

void cosmos::Tracee::pokeUser	(	const long *	offset,
		long	value )

inline

Change one word of data in the tracee's user area.

This changes on word of data in the tracee's user area.

See also: peekUser(). offset typically needs to be word-aligned.

Definition at line 207 of file Tracee.hxx.

                                                      {
                this->request(ptrace::Request::POKEUSER, offset, value);
        }

◆ request() [1/2]

template<typename ADDR = void*, typename DATA = void*>

std::optional< long > cosmos::Tracee::request	(	const ptrace::Request	req,
		ADDR	addr = nullptr,
		DATA	data = nullptr ) const

inlineprotected

Definition at line 416 of file Tracee.hxx.

                                                                                                           {
                // First cast to const void* then remove const, this allows to
                // pass in const pointers. The compiler cannot understand that
                // ptrace() won't change the pointed-to data according to
                // contract.
                return cosmos::ptrace::trace(req, m_pid,
                                const_cast<void*>(reinterpret_cast<const void*>(addr)),
                                const_cast<void*>(reinterpret_cast<const void*>(data)));
        }

◆ request() [2/2]

template<typename DATA = void*>

std::optional< long > cosmos::Tracee::request	(	const ptrace::Request	req,
		std::nullptr_t	,
		DATA	data = nullptr ) const

inlineprotected

Definition at line 431 of file Tracee.hxx.

                                                                                                    {
                return request(req, static_cast<void*>(nullptr), data);
        }

◆ restart()

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

inline

Continues a traced process, optionally delivering signal.

If the current ptrace stop state doesn't allow injection of a signal, then none should be specified. Generally only a signal-stop state allows injection of signals.

If signal information has been overwritten by using ptrace::set_siginfo(), then the signal passed here must match, otherwise the behaviour will be undefined.

Definition at line 134 of file Tracee.hxx.

                                                                                {}) {
                // data here takes the plain signal number, 0 means "don't inject a signal".
                this->request(static_cast<ptrace::Request>(mode),
                                nullptr,
                                mode != RestartMode::LISTEN && signal ? signal->raw() : SignalNr{0});
        }

◆ seize()

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

inline

Seize a tracee.

This is the modern way of making a process a tracee. This does not stop the process. The seize property is inherited to matching child processes of the tracee if one of the options Opt::TRACEFORK, Opt::TRACEVFORK or Opt::TRACECLONE is set on the tracee.

Initial tracing options are set atomically alongside the SEIZE request.

Definition at line 88 of file Tracee.hxx.

                                          {
                this->request(ptrace::Request::SEIZE, nullptr, opts.raw());
        }

◆ setFloatRegisters()

void cosmos::Tracee::setFloatRegisters ( const struct user_fpregs_struct & out )

inline

Modify the tracee's floating point registers.

See also: setRegisters().

Definition at line 252 of file Tracee.hxx.

                                                                     {
                this->request(ptrace::Request::SETFPREGS, nullptr, &out);
        }

◆ setOptions()

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

inline

Set tracing options for the given tracee.

This call completely defines the options in effect for the given tracee. These options can be inherited by new tracees that are auto-attached via the TRACEFORK, TRACEVFORK and TRACECLONE options.

Definition at line 166 of file Tracee.hxx.

                                               {
                this->request(ptrace::Request::SETOPTIONS, nullptr, opts.raw());
        }

◆ setRegisters()

void cosmos::Tracee::setRegisters ( const struct user_regs_struct & out )

inline

Modify the tracee's general purpose registers.

Some register modifications may be disallowed by the kernel to maintain integrity of the tracee.

Definition at line 231 of file Tracee.hxx.

                                                              {
                // NOTE: see getRegisters() about Sparc architecture
                this->request(ptrace::Request::SETREGS, nullptr, &out);
        }

◆ setRegisterSet()

void cosmos::Tracee::setRegisterSet	(	const ptrace::RegisterType	type,
		OutputMemoryRegion &	iovec )

inline

Modify a set of registers in the tracee.

Definition at line 270 of file Tracee.hxx.

                                                                                      {
                this->request(ptrace::Request::SETREGSET, type, iovec.asIovec());
        }

◆ setSigInfo()

void cosmos::Tracee::setSigInfo ( const SigInfo & info )

Set signal information for the tracee.

This will affect only signals that would normally be delivered to the tracee and were caught by the tracer. These signals can be hard to tell from synthetic signals generated by ptrace() itself.

When changing the signal information this way then the signal passed to restart() needs to match, to prevent undefined behaviour.

Definition at line 65 of file Tracee.cxx.

                                           {
        this->request(ptrace::Request::SETSIGINFO, nullptr, info.raw());
}

◆ setSigMask()

void cosmos::Tracee::setSigMask ( const SigSet & set )

inline

Change the tracee's mask of blocked signals.

Definition at line 307 of file Tracee.hxx.

                                           {
                this->request(ptrace::Request::SETSIGMASK, sizeof(*set.raw()), set.raw());
        }

◆ valid()

bool cosmos::Tracee::valid ( ) const

inline

Definition at line 73 of file Tracee.hxx.

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

Member Data Documentation

◆ m_pid

ProcessID cosmos::Tracee::m_pid

protected

Definition at line 437 of file Tracee.hxx.

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

include/proc/Tracee.hxx
src/proc/Tracee.cxx

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ RestartMode

Constructor & Destructor Documentation

◆ Tracee()

Member Function Documentation

◆ attach()

◆ detach()

◆ getEventMsg()

◆ getExitEventMsg()

◆ getFloatRegisters()

◆ getPIDEventMsg()

◆ getRegisters()

◆ getRegisterSet()

◆ getSeccompFilter()

◆ getSeccompRetDataEventMsg()

◆ getSigInfo()

◆ getSigMask()

◆ getSyscallInfo()

◆ interrupt()

◆ peekData()

◆ peekSigInfo()

◆ peekUser()

◆ pid()

◆ pokeData()

◆ pokeUser()

◆ request() [1/2]

◆ request() [2/2]

◆ restart()

◆ seize()

◆ setFloatRegisters()

◆ setOptions()

◆ setRegisters()

◆ setRegisterSet()

◆ setSigInfo()

◆ setSigMask()

◆ valid()

Member Data Documentation

◆ m_pid