clues::item::CloneArgs Class Reference

Structure used in clone3(). More...

#include <clone.hxx>

Inheritance diagram for clues::item::CloneArgs:

Public Member Functions
const std::optional< cosmos::CloneArgs > &	args () const
	Returns an optional containing the cosmos::CloneArgs structure, if available.
cosmos::FileNum	pidfd () const
	Return the newly created PIDFD.
cosmos::FileNum	cgroup2fd () const
	Return the cgroup2 file descriptor for the child to be placed in.
cosmos::ThreadID	tid () const
	Return the new child's ThreadID stored in parent's memory.
std::string	str () const override
	Returns a human readable string representation of the item.
void	processValue (const Tracee &) override
	Processes the value stored in m_val acc. to the actual item type.
void	updateData (const Tracee &proc) override
	Called upon exit of the system call to update possible out parameters.
Public Member Functions inherited from clues::SystemCallItem
	SystemCallItem (const ItemType type, const std::string_view short_name={}, const std::string_view long_name={})
	Constructs a new SystemCallItem.
auto	type () const
bool	isIn () const
bool	isOut () const
bool	isInOut () const
bool	isReturnValue () const
void	fill (const Tracee &proc, const Word word)
	Fills the item from the given register data.
bool	needsUpdate () const
	Returns whether the item needs to be updated after the system call is finished.
std::string_view	shortName () const
	Returns the friendly short name for this item.
std::string_view	longName () const
	Returns the friendly long name for this item, if available, else the short name.
auto	hasLongName () const
bool	isZero () const
	Returns whether the parameter is set to 0 / NULL.
Word	value () const
	Returns the currently stored raw value of the item.
template<typename OTHER>
OTHER	valueAs () const
	Helper to cast the strongly typed Word m_val to other strong enum types.
ForeignPtr	asPtr () const
Flags	flags () const
bool	deferFill () const

Protected Member Functions
bool	verifySize () const
void	resetArgs ()
Protected Member Functions inherited from clues::SystemCallItem
void	setSystemCall (const SystemCall &sc)
	Sets the system call context this item is a part of.

Protected Attributes
std::optional< cosmos::CloneArgs >	m_args
cosmos::FileNum	m_pidfd = cosmos::FileNum::INVALID
cosmos::FileNum	m_cgroup2_fd = cosmos::FileNum::INVALID
cosmos::ThreadID	m_child_tid = cosmos::ThreadID::INVALID
std::vector< cosmos::ThreadID >	m_tid_array
Protected Attributes inherited from clues::SystemCallItem
const SystemCall *	m_call = nullptr
	The system call context this item part of.
const ItemType	m_type
	The type of item.
std::string_view	m_short_name
	A human readable short name for the item, should be one word only.
std::string_view	m_long_name
	A human readable longer name for the item.
Word	m_val
	The raw register value for the item.
Flags	m_flags
	Flags influencing the processing of the item.

Additional Inherited Members
Public Types inherited from clues::SystemCallItem
enum class	Flag { DEFER_FILL = 1 << 0 }
using	Flags = cosmos::BitMask<Flag>

Detailed Description

Structure used in clone3().

Definition at line 44 of file clone.hxx.

Constructor & Destructor Documentation

CloneArgs()

clues::item::CloneArgs::CloneArgs ( )

inlineexplicit

Definition at line 48 of file clone.hxx.

                             :
                        SystemCallItem{ItemType::PARAM_IN_OUT, "cl_args", "clone arguments"} {
 
        }

Member Function Documentation

args()

const std::optional< cosmos::CloneArgs > & clues::item::CloneArgs::args ( ) const

inline

Returns an optional containing the cosmos::CloneArgs structure, if available.

Warning

The returned structure is unaware that the contained pointers are for the Tracee, not the calling process. This means dereferencing any pointers in the structure will lead to memory issues.

Definition at line 60 of file clone.hxx.

                                                         {
                return m_args;
        }

cgroup2fd()

cosmos::FileNum clues::item::CloneArgs::cgroup2fd ( ) const

inline

Return the cgroup2 file descriptor for the child to be placed in.

If CLONE_INTO_CGROUP was set in flags then this returns the cgroup2 file descriptor into which the child is to be placed by the kernel. FileNum::INVALID otherwise.

Definition at line 79 of file clone.hxx.

                                        {
                return m_cgroup2_fd;
        }

pidfd()

cosmos::FileNum clues::item::CloneArgs::pidfd ( ) const

inline

Return the newly created PIDFD.

If CLONE_PIDFD was set in flags then this returns the resulting PIDFD assigned by the kernel. FileNum::INVALID otherwise.

Definition at line 69 of file clone.hxx.

                                    {
                return m_pidfd;
        }

processValue()

void clues::item::CloneArgs::processValue ( const Tracee & )

overridevirtual

Processes the value stored in m_val acc. to the actual item type.

This function is called for all parameter types upon entry to a system call, and for ItemType::RETVAL upon exit from a system call.

For parameters of ItemType::PARAM_OUT this callback can be used to reset any stored data to be filled in later when updateData() is called.

Reimplemented from clues::SystemCallItem.

Definition at line 82 of file clone.cxx.

                                               {
 
        resetArgs();
 
        if (!verifySize())
                return;
 
        m_args.emplace(cosmos::CloneArgs{});
 
        // ignore the check for trivial types, cosmos::CloneArgs has a
        // constructor to set the whole structure to zero, we can live with that
        // not happening here.
        if (!proc.readStruct<cosmos::CloneArgs, /*CHECK_TRIVIAL=*/false>(asPtr(), *m_args)) {
                m_args.reset();
                return;
        }
 
        const auto &args = *m_args;
        const auto raw = args.raw();
        const auto num_tids = raw->set_tid_size;
 
        if (num_tids > 0) {
                m_tid_array.resize(num_tids);
                try {
                        proc.readBlob(
                                        ForeignPtr{static_cast<uintptr_t>(raw->set_tid)},
                                        reinterpret_cast<char*>(m_tid_array.data()), num_tids * sizeof(cosmos::ThreadID));
                } catch (const std::exception &ex) {
                        // could be an invalid userspace pointer
                        m_tid_array.clear();
                }
        }
 
        if (args.isSet(cosmos::CloneFlag::INTO_CGROUP)) {
                m_cgroup2_fd = args.cgroup().raw();
        }
}

resetArgs()

void clues::item::CloneArgs::resetArgs ( )

protected

Definition at line 74 of file clone.cxx.

                          {
        m_pidfd = cosmos::FileNum::INVALID;
        m_cgroup2_fd = cosmos::FileNum::INVALID;
        m_child_tid = cosmos::ThreadID::INVALID;
        m_tid_array.clear();
        m_args.reset();
}

str()

std::string clues::item::CloneArgs::str ( ) const

overridevirtual

Returns a human readable string representation of the item.

This member function should be specialized in derived classes to output the item's data in a fashion suitable for the concrete item type.

Reimplemented from clues::SystemCallItem.

Definition at line 157 of file clone.cxx.

                               {
        if (!m_args) {
                if (isZero())
                        return "NULL";
                else
                        // verifySize() failed
                        return format::pointer(asPtr()) + " (size mismatch)";
        }
 
        auto uint2ptr = [](uint64_t val) -> ForeignPtr {
                return ForeignPtr{static_cast<uintptr_t>(val)};
        };
 
        std::stringstream ss;
        const auto &args = *m_args;
        const auto flags = args.flags();
        const auto raw = args.raw();
        using enum cosmos::CloneFlag;
 
        ss << "{";
        ss << "flags=" << clone_flags_str(flags);
        if (flags[PIDFD]) {
                ss << ", pidfd=" << format::pointer(uint2ptr(raw->pidfd), std::to_string(cosmos::to_integral(m_pidfd)));
        }
        if (flags[CHILD_CLEARTID] || flags[CHILD_SETTID]) {
                const auto child_tid_ptr = ForeignPtr{reinterpret_cast<uintptr_t>(args.childTID())};
                ss << ", child_tid=" << format::pointer(child_tid_ptr);
        }
        if (flags[PARENT_SETTID]) {
                const auto parent_tid_ptr = ForeignPtr{reinterpret_cast<uintptr_t>(args.parentTID())};
                ss << ", parent_tid=" << format::pointer(parent_tid_ptr,
                                std::to_string(cosmos::to_integral(m_child_tid)));
        }
        ss << ", exit_signal=" << format::signal(args.exitSignal().raw(), /*verbose=*/false);
        const auto stack_ptr = ForeignPtr{reinterpret_cast<uintptr_t>(args.stack())};
        ss << ", stack=" << format::pointer(stack_ptr);
        ss << ", stack_size=" << args.stackSize();
        if (flags[SETTLS]) {
                // this is a architecture dependent value, interpreting it as
                // a hex pointer should be good enough for now.
                ss << ", tls=" << format::pointer(uint2ptr(raw->tls));
        }
 
        const auto settid_ptr = uint2ptr(raw->set_tid);
        if (raw->set_tid_size) {
                std::stringstream ss2;
                std::string sep = "";
                for (const auto tid: m_tid_array) {
                        ss2 << sep;
                        ss2 << cosmos::to_integral(tid);
                        if (sep.empty())
                                sep = ", ";
                }
                ss << ", set_tid=" << format::pointer(settid_ptr, ss2.str()); 
        } else {
                /*
                 * don't evaluate the pointed-to data in this case, but it
                 * could still be interesting to know if some strange value is
                 * passed here alongside the 0 size.
                 */
                ss << ", set_tid=" << format::pointer(settid_ptr);
        }
        ss << ", set_tid_size=" << raw->set_tid_size;
 
        if (flags[INTO_CGROUP]) {
                ss << ", cgroup=" << cosmos::to_integral(m_cgroup2_fd);
        }
 
        ss << "}";
 
        return ss.str();
}

tid()

cosmos::ThreadID clues::item::CloneArgs::tid ( ) const

inline

Return the new child's ThreadID stored in parent's memory.

If PARENT_SETTID was set in flags then this returns the child's thread ID stored at the location specified by parent_tid. ThreadID::INVALID otherwise.

Definition at line 89 of file clone.hxx.

                                   {
                return m_child_tid;
        }

updateData()

void clues::item::CloneArgs::updateData ( const Tracee & t )

overridevirtual

Called upon exit of the system call to update possible out parameters.

This function is called for parameters of ItemType::PARAM_OUT and ItemType::PARAM_IN_OUT upon system call exit to update the data from the values returned from the system call.

The default implementation calls processValue() to allow to share the same data processing code for input and output for item types that support both.

This function is called regardless of system call success or error, so it can happen that there is no valid data returned by the kernel or pointers in userspace are broken. Implementations should take this into consideration when operating on the data.

Reimplemented from clues::SystemCallItem.

Definition at line 120 of file clone.cxx.

                                             {
 
        if (!m_args)
                return;
 
        const auto &args = *m_args;
        const auto raw = args.raw();
        const auto flags = args.flags();
        using enum cosmos::CloneFlag;
 
        if (flags[PIDFD]) {
                // read the assigned PID file descriptor from tracee memory.
                proc.readStruct(ForeignPtr{static_cast<uintptr_t>(raw->pidfd)}, m_pidfd);
        }
 
        if (flags[PARENT_SETTID]) {
                proc.readStruct(ForeignPtr{static_cast<uintptr_t>(raw->parent_tid)}, m_child_tid);
        }
}

verifySize()

bool clues::item::CloneArgs::verifySize ( ) const

protected

Definition at line 140 of file clone.cxx.

                                 {
        if (m_call->callNr() == SystemCallNr::CLONE3) {
                /* we need to make a forward lookup of the size argument,
                 * which follows the cl_args parameter */
                const auto info = *m_call->currentInfo()->entryInfo();
 
                if (info.args()[1] < sizeof(cosmos::CloneArgs)) {
                        return false;
                }
 
                return true;
        } else {
                // yet unknown system call?
                return false;
        }
}

Member Data Documentation

m_args

std::optional<cosmos::CloneArgs> clues::item::CloneArgs::m_args

protected

Definition at line 107 of file clone.hxx.

m_cgroup2_fd

cosmos::FileNum clues::item::CloneArgs::m_cgroup2_fd = cosmos::FileNum::INVALID

protected

Definition at line 109 of file clone.hxx.

m_child_tid

cosmos::ThreadID clues::item::CloneArgs::m_child_tid = cosmos::ThreadID::INVALID

protected

Definition at line 110 of file clone.hxx.

m_pidfd

cosmos::FileNum clues::item::CloneArgs::m_pidfd = cosmos::FileNum::INVALID

protected

Definition at line 108 of file clone.hxx.

m_tid_array

std::vector<cosmos::ThreadID> clues::item::CloneArgs::m_tid_array

protected

Definition at line 111 of file clone.hxx.

---

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

• include/items/clone.hxx
• src/items/clone.cxx