clues::SystemCallItem Class Reference

Base class for any kind of system call parameter or return value. More...

#include <SystemCallItem.hxx>

Inheritance diagram for clues::SystemCallItem:

Public Types
enum class	Flag { DEFER_FILL = 1 << 0 }
using	Flags = cosmos::BitMask<Flag>

Public Member Functions
	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
virtual std::string	str () const
	Returns a human readable string representation of the item.
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
virtual void	processValue (const Tracee &)
	Processes the value stored in m_val acc. to the actual item type.
virtual void	updateData (const Tracee &t)
	Called upon exit of the system call to update possible out parameters.
void	setSystemCall (const SystemCall &sc)
	Sets the system call context this item is a part of.

Protected Attributes
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.

Detailed Description

Base class for any kind of system call parameter or return value.

Concrete types need to derive from this and override virtual methods as needed.

Definition at line 33 of file SystemCallItem.hxx.

Member Typedef Documentation

Flags

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

Definition at line 47 of file SystemCallItem.hxx.

Member Enumeration Documentation

Flag

enum class clues::SystemCallItem::Flag

strong

Enumerator
DEFER_FILL	Only fill in this item after all other items have been filled. This helps to model context-dependent parameters that rely on the values of parameters appearing at a later position.

Definition at line 38 of file SystemCallItem.hxx.

                        {

                DEFER_FILL = 1 << 0
        };

Constructor & Destructor Documentation

SystemCallItem()

clues::SystemCallItem::SystemCallItem ( const ItemType type, const std::string_view short_name = {}, const std::string_view long_name = {} )

inlineexplicit

Constructs a new SystemCallItem.

Parameters

[in]	type	The type of item.
[in]	short_name	A short friendly name for this item (one word)
[in]	long_name	A longer name for this item, optional

Definition at line 60 of file SystemCallItem.hxx.

                                                  {},
                const std::string_view long_name = {}) :
                        m_type{type},
                        m_short_name{short_name},
                        m_long_name{long_name}
        {}

~SystemCallItem()

virtual clues::SystemCallItem::~SystemCallItem ( )

inlinevirtual

Definition at line 69 of file SystemCallItem.hxx.

{}

Member Function Documentation

asPtr()

ForeignPtr clues::SystemCallItem::asPtr ( ) const

inline

Definition at line 133 of file SystemCallItem.hxx.

                                 {
                return valueAs<ForeignPtr>();
        }

deferFill()

bool clues::SystemCallItem::deferFill ( ) const

inline

Definition at line 141 of file SystemCallItem.hxx.

                               {
                return m_flags[Flag::DEFER_FILL];
        }

fill()

void clues::SystemCallItem::fill	(	const Tracee &	proc,
		const Word	word )

Fills the item from the given register data.

Definition at line 9 of file SystemCallItem.cxx.

                                                             {
        m_val = word;
        processValue(proc);
}

flags()

Flags clues::SystemCallItem::flags ( ) const

inline

Definition at line 137 of file SystemCallItem.hxx.

                            {
                return m_flags;
        }

hasLongName()

auto clues::SystemCallItem::hasLongName ( ) const

inline

Definition at line 90 of file SystemCallItem.hxx.

{ return !m_long_name.empty(); }

isIn()

bool clues::SystemCallItem::isIn ( ) const

inline

Definition at line 73 of file SystemCallItem.hxx.

{ return m_type == ItemType::PARAM_IN; }

isInOut()

bool clues::SystemCallItem::isInOut ( ) const

inline

Definition at line 75 of file SystemCallItem.hxx.

{ return m_type == ItemType::PARAM_IN_OUT; }

isOut()

bool clues::SystemCallItem::isOut ( ) const

inline

Definition at line 74 of file SystemCallItem.hxx.

{ return m_type == ItemType::PARAM_OUT; }

isReturnValue()

bool clues::SystemCallItem::isReturnValue ( ) const

inline

Definition at line 76 of file SystemCallItem.hxx.

{ return m_type == ItemType::RETVAL; }

isZero()

bool clues::SystemCallItem::isZero ( ) const

inline

Returns whether the parameter is set to 0 / NULL.

Definition at line 101 of file SystemCallItem.hxx.

                            {
                return value() == Word::ZERO;
        }

longName()

std::string_view clues::SystemCallItem::longName ( ) const

inline

Returns the friendly long name for this item, if available, else the short name.

Definition at line 87 of file SystemCallItem.hxx.

                                        {
                return m_long_name.empty() ? shortName() : m_long_name; }

needsUpdate()

bool clues::SystemCallItem::needsUpdate ( ) const

inline

Returns whether the item needs to be updated after the system call is finished.

Definition at line 82 of file SystemCallItem.hxx.

{ return m_type != ItemType::PARAM_IN; }

processValue()

virtual void clues::SystemCallItem::processValue ( const Tracee & )

inlineprotectedvirtual

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 in clues::item::AccessModeParameter, clues::item::AtFlagsValue, clues::item::BufferPointer, clues::item::ClockID, clues::item::ClockNanoSleepFlags, clues::item::CloneArgs, clues::item::CloneFlagsValue, clues::item::DirEntries, clues::item::DNotifySettings, clues::item::ExitStatusItem, clues::item::ExtFileDescOwner, clues::item::FcntlOperation, clues::item::FileDescFlagsValue, clues::item::FileDescOwner, clues::item::FileDescriptor, clues::item::FileModeParameter, clues::item::FileSealSettings, clues::item::FLockParameter, clues::item::FutexOperation, clues::item::FutexWakeOperation, clues::item::GenericPointerValue, clues::item::GroupID, clues::item::IntValueT< INT >, clues::item::IntValueT< int >, clues::item::IntValueT< int >, clues::item::IntValueT< off_t >, clues::item::IntValueT< off_t >, clues::item::IntValueT< size_t >, clues::item::IntValueT< size_t >, clues::item::IntValueT< uint32_t >, clues::item::IntValueT< uint32_t >, clues::item::IntValueT< unsigned int >, clues::item::IntValueT< unsigned int >, clues::item::IntValueT< unsigned long >, clues::item::IntValueT< unsigned long >, clues::item::LeaseType, clues::item::MapFlagsParameter, clues::item::MemoryProtectionParameter, clues::item::OldMmapArgs, clues::item::OpenFlagsValue, clues::item::PipeEnds, clues::item::PipeFlags, clues::item::PointerToScalar< INT >, clues::item::PointerToScalar< ForeignPtr >, clues::item::PointerToScalar< int >, clues::item::PointerToScalar< size_t >, clues::item::ProcessIDItem, clues::item::ReadWriteHint, clues::item::ResourceLimit, clues::item::ResourceType, clues::item::ResourceUsageItem, clues::item::SigActionParameter, clues::item::SignalNumber, clues::item::SigSetOperation, clues::item::SigSetParameter, clues::item::StatParameter, clues::item::StringArrayData, clues::item::StringData, clues::item::ThreadIDItem, clues::item::TimeSpecParameter, clues::item::UserID, clues::item::WaitOptionsItem, and clues::item::WaitStatusItem.

Definition at line 156 of file SystemCallItem.hxx.

{}

setSystemCall()

void clues::SystemCallItem::setSystemCall ( const SystemCall & sc )

inlineprotected

Sets the system call context this item is a part of.

Definition at line 178 of file SystemCallItem.hxx.

{ m_call = ≻ }

shortName()

std::string_view clues::SystemCallItem::shortName ( ) const

inline

Returns the friendly short name for this item.

Definition at line 85 of file SystemCallItem.hxx.

{ return m_short_name; }

str()

std::string clues::SystemCallItem::str ( ) const

virtual

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 in clues::item::AccessModeParameter, clues::item::AtFlagsValue, clues::item::BufferPointer, clues::item::ClockID, clues::item::ClockNanoSleepFlags, clues::item::CloneArgs, clues::item::CloneFlagsValue, clues::item::DirEntries, clues::item::DNotifySettings, clues::item::ExtFileDescOwner, clues::item::FcntlOperation, clues::item::FileDescFlagsValue, clues::item::FileDescOwner, clues::item::FileDescriptor, clues::item::FileModeParameter, clues::item::FileSealSettings, clues::item::FLockParameter, clues::item::FutexOperation, clues::item::FutexWakeOperation, clues::item::GenericPointerValue, clues::item::IntValueT< INT >, clues::item::IntValueT< int >, clues::item::IntValueT< int >, clues::item::IntValueT< off_t >, clues::item::IntValueT< off_t >, clues::item::IntValueT< size_t >, clues::item::IntValueT< size_t >, clues::item::IntValueT< uint32_t >, clues::item::IntValueT< uint32_t >, clues::item::IntValueT< unsigned int >, clues::item::IntValueT< unsigned int >, clues::item::IntValueT< unsigned long >, clues::item::IntValueT< unsigned long >, clues::item::LeaseType, clues::item::MapFlagsParameter, clues::item::MemoryProtectionParameter, clues::item::OldMmapArgs, clues::item::OpenFlagsValue, clues::item::PipeEnds, clues::item::PipeFlags, clues::item::PointerToScalar< INT >, clues::item::PointerToScalar< ForeignPtr >, clues::item::PointerToScalar< int >, clues::item::PointerToScalar< size_t >, clues::item::ProcessIDItem, clues::item::ReadWriteHint, clues::item::ResourceLimit, clues::item::ResourceType, clues::item::ResourceUsageItem, clues::item::SigActionParameter, clues::item::SignalNumber, clues::item::SigSetOperation, clues::item::SigSetParameter, clues::item::StatParameter, clues::item::StringArrayData, clues::item::StringData, clues::item::SuccessResult, clues::item::TimeSpecParameter, clues::item::UnknownItem, and clues::item::WaitOptionsItem.

Definition at line 14 of file SystemCallItem.cxx.

                                    {
        // by default simply return the register value as a string
        return std::to_string(cosmos::to_integral(m_val));
}

type()

auto clues::SystemCallItem::type ( ) const

inline

Definition at line 71 of file SystemCallItem.hxx.

{ return m_type; }

updateData()

virtual void clues::SystemCallItem::updateData ( const Tracee & t )

inlineprotectedvirtual

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 in clues::item::BufferPointer, clues::item::CloneArgs, clues::item::DirEntries, clues::item::FLockParameter, clues::item::GenericPointerValue, clues::item::PipeEnds, clues::item::PointerToScalar< INT >, clues::item::PointerToScalar< ForeignPtr >, clues::item::PointerToScalar< int >, clues::item::PointerToScalar< size_t >, clues::item::ResourceLimit, clues::item::ResourceUsageItem, clues::item::StatParameter, clues::item::StringData, clues::item::TimeSpecParameter, and clues::item::WaitStatusItem.

Definition at line 173 of file SystemCallItem.hxx.

                                                 {
                processValue(t);
        }

value()

Word clues::SystemCallItem::value ( ) const

inline

Returns the currently stored raw value of the item.

Definition at line 106 of file SystemCallItem.hxx.

{ return m_val; }

valueAs()

template<typename OTHER>

OTHER clues::SystemCallItem::valueAs ( ) const

inline

Helper to cast the strongly typed Word m_val to other strong enum types.

This also silences data loss warnings. On x86_64 Word is 64-bit wide, but many parameters are actually only 32-bit wide, so this warning comes up a lot. There shouldn't be many dangerous situations in this context as long as we select the correct target type.

Definition at line 117 of file SystemCallItem.hxx.

                              {
                const auto baseval = cosmos::to_integral(m_val);
                if constexpr (std::is_enum_v<OTHER>) {
                        const auto baseret = static_cast<typename std::underlying_type<OTHER>::type>(baseval);
                        return OTHER{baseret};
                }
 
                if constexpr (std::is_pointer_v<OTHER>) {
                        return reinterpret_cast<OTHER>(baseval);
                }
 
                if constexpr (!std::is_enum_v<OTHER> && !std::is_pointer_v<OTHER>) {
                        return static_cast<OTHER>(baseval);
                }
        }

Member Data Documentation

m_call

const SystemCall* clues::SystemCallItem::m_call = nullptr

protected

The system call context this item part of.

Definition at line 183 of file SystemCallItem.hxx.

m_flags

Flags clues::SystemCallItem::m_flags

protected

Flags influencing the processing of the item.

Definition at line 193 of file SystemCallItem.hxx.

m_long_name

std::string_view clues::SystemCallItem::m_long_name

protected

A human readable longer name for the item.

Definition at line 189 of file SystemCallItem.hxx.

m_short_name

std::string_view clues::SystemCallItem::m_short_name

protected

A human readable short name for the item, should be one word only.

Definition at line 187 of file SystemCallItem.hxx.

m_type

const ItemType clues::SystemCallItem::m_type

protected

The type of item.

Definition at line 185 of file SystemCallItem.hxx.

m_val

Word clues::SystemCallItem::m_val

protected

The raw register value for the item.

Definition at line 191 of file SystemCallItem.hxx.

---

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

• include/SystemCallItem.hxx
• src/SystemCallItem.cxx