Wrapper for the clone() and clone2() system calls. More...

#include <process.hxx>

Inheritance diagram for clues::CloneSystemCall:

Public Attributes
item::CloneFlagsValue	flags

item::GenericPointerValue	stack

std::optional< item::PointerToScalar< cosmos::ProcessID > >	parent_tid
	TID of the new child written out to a pid_t* in the parent.

std::optional< item::PointerToScalar< cosmos::FileNum > >	pidfd
	PID file descriptor referring to the new child.

std::optional< item::GenericPointerValue >	child_tid
	TID of the new child written out to a pid_* in the child.

std::optional< item::GenericPointerValue >	tls
	Thread-local-storage data for the new child.

item::ProcessIDItem	new_pid
	The new child's PID.

Protected Member Functions
bool	check2ndPass (const Tracee &) override
	Check whether a second pass needs to be made processing parameters.

void	prepareNewSystemCall () override
	Perform any necessary actions before processing a new system call entry event.

Protected Member Functions inherited from clues::SystemCall
void	fillParameters (const Tracee &proc, const SystemCallInfo &info)

void	setReturnItem (SystemCallItem &ret)
	Sets the return value system call item.

void	addParameters ()

template<typename T, typename... Targs>
void	addParameters (T &par, Targs &...rest)

template<typename... Targs>
void	setParameters (Targs &...args)

virtual void	updateFDTracking (const Tracee &proc)
	Update file descriptor tracking.

void	dropFD (const Tracee &proc, const cosmos::FileNum num)

void	trackFD (const Tracee &proc, FDInfo &&info)

Additional Inherited Members
Public Types inherited from clues::SystemCall
using	ParameterVector = std::vector<SystemCallItemPtr>
	Vector of the parameters required for a system call.

Public Member Functions inherited from clues::SystemCall
	SystemCall (const SystemCallNr nr)
	Instantiates a new SystemCall object with given properties.

	SystemCall (const SystemCall &other)=delete

SystemCall &	operator= (const SystemCall &other)=delete

void	setEntryInfo (const Tracee &proc, const SystemCallInfo &info)
	Update the stored parameter values from the given tracee.

void	setExitInfo (const Tracee &proc, const SystemCallInfo &info)
	Update possible out and return parameter values from the given tracee.

std::string_view	name () const
	Returns the system call's human readable name.

size_t	numPars () const
	Returns the number of parameters for this system call.

SystemCallNr	callNr () const
	Returns the system call table number for this system call.

const ParameterVector &	parameters () const
	Access to the parameters associated with this system call.

SystemCallItemPtr	result () const
	Access to the return value parameter associated with this system call.

std::optional< ErrnoResult >	error () const
	Access to the errno result seen for this system call.

bool	hasOutParameter () const

bool	hasResultValue () const

bool	hasErrorCode () const

ABI	abi () const
	Returns the system call ABi seen during system call entry.

bool	is32BitEmulationABI () const

const SystemCallInfo *	currentInfo () const
	Access the current SystemCallInfo if currently processing syscall entry/exit.

Static Public Member Functions inherited from clues::SystemCall
static const char *	name (const SystemCallNr nr)
	Returns the name of the given system call or "<unknown>" if unknown.

static bool	validNr (const SystemCallNr nr)
	Returns whether the given system call number is in a valid range.

Protected Attributes inherited from clues::SystemCall
SystemCallNr	m_nr
	The raw system call number of the system call.

const std::string_view	m_name
	The basic name of the system call.

const SystemCallInfo *	m_info = nullptr
	Current system call info during entry/exit processing, nullptr otherwise.

SystemCallItemPtr	m_return
	The return value of the system call.

std::optional< ErrnoResult >	m_error
	If the system call fails, this is the error code.

ParameterVector	m_pars
	The array of system call parameters, if any.

ABI	m_abi = ABI::UNKNOWN
	The current system call ABI which is in effect.

Detailed Description

Wrapper for the clone() and clone2() system calls.

For clone3() a separate wrapper type is used, since the two variants of clone system calls differ too much from each other.

Definition at line 61 of file process.hxx.

Constructor & Destructor Documentation

◆ CloneSystemCall()

clues::CloneSystemCall::CloneSystemCall ( )

inline

Definition at line 64 of file process.hxx.

                          :
                        SystemCall{SystemCallNr::CLONE},
                        stack{"stack", "stack address"},
                        new_pid{ItemType::RETVAL, "child pid"} {
                setReturnItem(new_pid);
                setParameters(flags, stack);
        }

Member Function Documentation

◆ check2ndPass()

bool clues::CloneSystemCall::check2ndPass ( const Tracee & )

overrideprotectedvirtual

Check whether a second pass needs to be made processing parameters.

This function can be overridden by the actual system call implementation to perform context-sensitive evaluation of system call parameters (e.g. for ioctl() style system calls) upon system call entry.

The implementation of this function is allowed to modify the amount and types of system call parameters and return parameter. In this case true must be returned to let the base class implementation reevaluate all system call parameters.

Reimplemented from clues::SystemCall.

Definition at line 64 of file process.cxx.

                                                  {
        // we need these two sizes to match, since a `pid_t*` is used in
        // clone() to store either the child pid or a pidfd at.
        static_assert( sizeof(int) == sizeof(pid_t), "sizeof(int) != sizeof(pid_t)" );
        using enum cosmos::CloneFlag;
        const auto clone_flags = this->flags.flags();
 
        auto maybe_add_unused_par = [this](const size_t need_index) {
                while (need_index > m_pars.size()) {
                        addParameters(item::unused);
                }
        };
 
        auto maybe_add_settid_par = [this, clone_flags, maybe_add_unused_par](const size_t pos) {
                if (clone_flags[CHILD_SETTID]) {
                        child_tid.emplace(item::GenericPointerValue{"child_tid", "pointer to child TID in child's memory"});
                        maybe_add_unused_par(pos);
                        addParameters(*child_tid);
                }
        };
 
        auto maybe_add_settls_par = [this, clone_flags, maybe_add_unused_par](const size_t pos) {
                if (clone_flags[SETTLS]) {
                        tls.emplace(item::GenericPointerValue{"tls", "ABI-specific thread-local-storage data"});
 
                        maybe_add_unused_par(pos);
                        addParameters(*tls);
                }
        };
 
        // these two are mutual-exclusive in the old clone() system call
        if (clone_flags[PARENT_SETTID]) {
                parent_tid.emplace(item::PointerToScalar<cosmos::ProcessID>{
                                "parent_tid", "pointer to child TID in parent's memory"});
                addParameters(*parent_tid);
        } else if (clone_flags[PIDFD]) {
                pidfd.emplace(item::PointerToScalar<cosmos::FileNum>{
                                "pidfd", "pointer to pidfd in parent's memory (alternative use of parent_tid)"});
                addParameters(*pidfd);
        }
 
        /*
         * Things are messy with clone(), the order of parameters differs
         * between ABIs and we might need to skip some parameters by adding
         * item::unused.
         *
         * The man page is a bit sketchy on the ABI details. In the kernel
         * source we have to look for `CONFIG_CLONE_BACKWARDS*`, define in
         * "arch/.../KConfig" as CLONE_BACKWARDS*.
         *
         * The situation for the ABIs we support is as follows:
         *
         * X86_32 (I386), ARM, ARM64: CLONE_BACKWARDS
         * X86_64 (seems to include X32): no define
         *
         * CLONE_BACKWARDS means the final two arguments are tls /
         * child_tidptr.
         *
         * no define means the final two arguments are child_tidptr / tls.
         */
 
        if (const auto abi = this->abi(); abi == ABI::X86_64 || abi == ABI::X32) {
                maybe_add_settid_par(3);
                maybe_add_settls_par(4);
        } else if (abi == ABI::AARCH64 || abi == ABI::I386) {
                maybe_add_settls_par(3);
                maybe_add_settid_par(4);
        }
 
        return m_pars.size() > 2;
}

◆ prepareNewSystemCall()

void clues::CloneSystemCall::prepareNewSystemCall ( )

overrideprotectedvirtual

Perform any necessary actions before processing a new system call entry event.

Reimplemented from clues::SystemCall.

Definition at line 53 of file process.cxx.

                                           {
        /* drop all but the fixed initial two parameters */
        m_pars.erase(m_pars.begin() + 2, m_pars.end());
 
        /* args */
        parent_tid.reset();
        pidfd.reset();
        child_tid.reset();
        tls.reset();
}

Member Data Documentation

◆ child_tid

std::optional<item::GenericPointerValue> clues::CloneSystemCall::child_tid

TID of the new child written out to a pid_* in the child.

This is only filled in if CLONE_CHILD_SETTID is set.

This is only placed into the child's memory, not to the parent's. Thus we have no reliable way of retrieving the value, which is why we're not using PointerToScalar here.

Definition at line 99 of file process.hxx.

◆ flags

item::CloneFlagsValue clues::CloneSystemCall::flags

Definition at line 73 of file process.hxx.

◆ new_pid

item::ProcessIDItem clues::CloneSystemCall::new_pid

The new child's PID.

Definition at line 112 of file process.hxx.

◆ parent_tid

std::optional<item::PointerToScalar<cosmos::ProcessID> > clues::CloneSystemCall::parent_tid

TID of the new child written out to a pid_t* in the parent.

This is only filled in if CLONE_PARENT_SETTID is set.

Definition at line 84 of file process.hxx.

◆ pidfd

std::optional<item::PointerToScalar<cosmos::FileNum> > clues::CloneSystemCall::pidfd

PID file descriptor referring to the new child.

This is only filled in if CLONE_PIDFD is set.

Definition at line 89 of file process.hxx.

◆ stack

item::GenericPointerValue clues::CloneSystemCall::stack

Definition at line 74 of file process.hxx.

◆ tls

std::optional<item::GenericPointerValue> clues::CloneSystemCall::tls

Thread-local-storage data for the new child.

This is only filled in if CLONE_SETTLS is set.

The interpretation is highly ABI-specific, which is why we currently model it generically as a pointer.

Definition at line 107 of file process.hxx.

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

include/syscalls/process.hxx
src/syscalls/process.cxx

Public Attributes

Protected Member Functions

Additional Inherited Members