clues::item::StatParameter Class Reference

The stat structure used in stat() & friends. More...

#include <fs.hxx>

Inheritance diagram for clues::item::StatParameter:

Public Member Functions
std::string	str () const override
	Returns a human readable string representation of the item.
const std::optional< cosmos::FileStatus > &	status () const
	Access to full FileStatus information.
Public Member Functions inherited from clues::item::PointerOutValue
	PointerOutValue (const std::string_view short_name, const std::string_view long_name={}, const ItemType type=ItemType::PARAM_OUT)
Public Member Functions inherited from clues::item::PointerValue
	PointerValue (const ItemType type, const std::string_view short_name, const std::string_view long_name)
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
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.
bool	isOldStat () const
	Whether this is related to one of the OLDSTAT family of system calls.
bool	isStat64 () const
	Whether this is related to one of the STAT64 family of system calls.
bool	isRegularStat () const
	Whether this is related to one of the STAT family of system calls.
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::FileStatus >	m_stat
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

The stat structure used in stat() & friends.

Definition at line 189 of file fs.hxx.

Constructor & Destructor Documentation

StatParameter()

clues::item::StatParameter::StatParameter ( )

inlineexplicit

Definition at line 192 of file fs.hxx.

                                 :
                        PointerOutValue{"stat", "struct stat"} {
        }

Member Function Documentation

isOldStat()

bool clues::item::StatParameter::isOldStat ( ) const

protected

Whether this is related to one of the OLDSTAT family of system calls.

Definition at line 217 of file fs.cxx.

                                    {
        using enum SystemCallNr;
 
        switch (m_call->callNr()) {
                case OLDSTAT: [[fallthrough]];
                case OLDLSTAT: [[fallthrough]];
                case OLDFSTAT: return true;
                default: return false;
        }
}

isRegularStat()

bool clues::item::StatParameter::isRegularStat ( ) const

protected

Whether this is related to one of the STAT family of system calls.

Definition at line 240 of file fs.cxx.

                                        {
        using enum SystemCallNr;
 
        switch (m_call->callNr()) {
                case SystemCallNr::STAT: [[fallthrough]];
                case SystemCallNr::LSTAT: [[fallthrough]];
                case SystemCallNr::FSTAT: return true;
                default: return false;
        }
}

isStat64()

bool clues::item::StatParameter::isStat64 ( ) const

protected

Whether this is related to one of the STAT64 family of system calls.

Definition at line 228 of file fs.cxx.

                                   {
        using enum SystemCallNr;
 
        switch (m_call->callNr()) {
                case STAT64: [[fallthrough]];
                case LSTAT64: [[fallthrough]];
                case FSTAT64: [[fallthrough]];
                case FSTATAT64: return true;
                default: return false;
        }
}

processValue()

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

inlineoverrideprotectedvirtual

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 209 of file fs.hxx.

                                                   {
                m_stat.reset();
        }

status()

const std::optional< cosmos::FileStatus > & clues::item::StatParameter::status ( ) const

inline

Access to full FileStatus information.

This optional can be unset if the system call never occurred or if reading the data from the Tracee failed.

Definition at line 203 of file fs.hxx.

                                                            {
                return m_stat;
        }

str()

std::string clues::item::StatParameter::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 174 of file fs.cxx.

                                   {
        if (!m_stat) {
                if (isZero()) {
                        return "NULL";
                } else {
                        return "<invalid>";
                }
        }
 
        std::stringstream ss;
 
        const auto st = *m_stat->raw();
        using namespace std::string_literals;
 
        const auto is_old_stat = isOldStat();
 
        ss
                << "{"
                << "ino=" << st.st_ino << ", "
                << "dev=" << format::device_id(m_stat->device()) << ", "
                << "mode=" << format::file_type(m_stat->type()) << "|" << format::file_mode_numeric(m_stat->mode().mask()) << ", "
                << "nlink=" << m_stat->numLinks() << ", "
                << "uid=" << st.st_uid << ", "
                << "gid=" << st.st_gid << ", "
                << (m_stat->type().isCharDev() || m_stat->type().isBlockDev() ? "rdev="s + format::device_id(m_stat->representedDevice()) + ", " : "")
                << "size=" << st.st_size << ", ";
 
        if (!is_old_stat) {
                /*
                 * these fields do not exist in oldstat syscalls
                 */
                ss << "blksize=" << st.st_blksize << ", " << "blocks=" << st.st_blocks << ", ";
        }
 
        ss
                << "atim=" << format::timespec(m_stat->accessTime(), is_old_stat) << ", "
                << "mtim=" << format::timespec(m_stat->modTime(), is_old_stat) << ", "
                << "ctim=" << format::timespec(m_stat->statusTime(), is_old_stat)
                << "}";
 
        return ss.str();
}

updateData()

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

overrideprotectedvirtual

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 251 of file fs.cxx.

                                                 {
        if (!m_stat) {
                m_stat = std::make_optional<cosmos::FileStatus>();
        }
 
#if defined(COSMOS_X86_64) || defined(COSMOS_AARCH64)
        /*
         * on 64-bit platforms life is simple, we directly copy the data into
         * a cosmos::FileStatus struct.
         * make sure the raw kernel data structure `stat64` matches `struct
         * stat` and then copy everything into it.
         */
        static_assert(sizeof(*m_stat->raw()) == sizeof(stat64));
#else
        /*
         * on modern 32-bit we can still do the same for the stat64 family of
         * system calls, but only if the tracer is 32-bit as well...
         */
        static_assert(sizeof(*m_stat->raw()) == sizeof(stat32_64));
#endif
 
        auto fetch_and_copy = [this, &proc]<typename STAT>() {
                STAT st;
                if (!proc.readStruct(asPtr(), st)) {
                        m_stat.reset();
                        return;
                }
 
                auto &raw = *m_stat->raw();
                /*
                 * to be layout agnostic simply copy over field-by-field
                 */
                raw.st_dev = st.dev;
                raw.st_ino = st.ino;
                raw.st_mode = st.mode;
                raw.st_nlink = st.nlink;
                raw.st_uid = st.uid;
                raw.st_gid = st.gid;
                raw.st_rdev = st.rdev;
                raw.st_size = st.size;
 
                if constexpr (std::is_same_v<STAT, old_kernel_stat>) {
                        /* the old kernel stat is missing a lot of stuff */
                        raw.st_atim.tv_sec = st.atime;
                        raw.st_atim.tv_nsec = 0;
                        raw.st_mtim.tv_sec = st.mtime;
                        raw.st_mtim.tv_nsec = 0;
                        raw.st_ctim.tv_sec = st.ctime;
                        raw.st_ctim.tv_nsec = 0;
                        raw.st_blksize = 0;
                        raw.st_blocks = 0;
                }
 
                if constexpr (!std::is_same_v<STAT, old_kernel_stat>) {
                        raw.st_blksize = st.blksize;
                        raw.st_blocks = st.blocks;
                        raw.st_atim.tv_sec = st.atime;
                        raw.st_atim.tv_nsec = st.atime_nsec;
                        raw.st_mtim.tv_sec = st.mtime;
                        raw.st_mtim.tv_nsec = st.mtime_nsec;
                        raw.st_ctim.tv_sec = st.ctime;
                        raw.st_ctim.tv_nsec = st.ctime_nsec;
                }
        };
 
        switch (m_call->abi()) {
                case ABI::X86_64: [[fallthrough]];
                case ABI::X32:    [[fallthrough]];
                case ABI::AARCH64: {
                        /*
                         * there's only one type of stat
                         * directly read into libcosmos's FileStatus
                         */
                        if (!proc.readStruct(asPtr(), *m_stat->raw())) {
                                m_stat.reset();
                        }
                        break;
                } case ABI::I386: {
                        /*
                         * on 32-bit platforms things get messy, we have three
                         * different possibilities using three different data
                         * structures.
                         */
                        if (isOldStat()) {
                                fetch_and_copy.operator()<old_kernel_stat>();
                        } else if (isStat64()) {
                                fetch_and_copy.operator()<stat32_64>();
                        } else if (isRegularStat()) {
                                // regular 32-bit stat
                                fetch_and_copy.operator()<stat32>();
                        } else {
                                throw cosmos::RuntimeError{"unexpected syscall nr for struct stat"};
                        }
                        break;
                } default: throw cosmos::RuntimeError{"unexpected ABI for struct stat"};
        }
}

Member Data Documentation

m_stat

std::optional<cosmos::FileStatus> clues::item::StatParameter::m_stat

protected

Definition at line 226 of file fs.hxx.

---

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

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