clues::item::FLockParameter Class Reference

Corresponds to struct flock Used with fcntl() F_*LK operations. More...

#include <fcntl.hxx>

Inheritance diagram for clues::item::FLockParameter:

Public Member Functions
std::string	str () const override
	Returns a human readable string representation of the item.
const std::optional< cosmos::FileLock > &	lock () const
	Access to the extracted FileLock data.
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 &proc) 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.
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::FileLock >	m_lock
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

Corresponds to struct flock Used with fcntl() F_*LK operations.

Definition at line 116 of file fcntl.hxx.

Constructor & Destructor Documentation

FLockParameter()

clues::item::FLockParameter::FLockParameter ( )

inlineexplicit

Definition at line 119 of file fcntl.hxx.

                                  :
                        // this can be PARAM_IN and PARAM_IN_OUT, but we
                        // simply claim it's always IN_OUT
                        PointerValue{ItemType::PARAM_IN_OUT, "flock", "struct flock"} {
        }

Member Function Documentation

lock()

const std::optional< cosmos::FileLock > & clues::item::FLockParameter::lock ( ) const

inline

Access to the extracted FileLock data.

This can be unassigned in case no system call was yet executed, or if fetching the data from the Tracee failed for some reason.

Definition at line 132 of file fcntl.hxx.

                                                        {
                return m_lock;
        }

processValue()

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

overrideprotectedvirtual

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 143 of file fcntl.cxx.

                                                    {
        /* all flock related operations provide input, so unconditionally
         * process it */
 
        /*
         * The situation with fcntl() and fcntl64() is quite messy. fcntl64()
         * only exists on 32-bit platforms like I386. The difference is only
         * in the data structure used with the GETLK and SETLK operations.
         *
         * On 64-bit targets, with the single `fcntl()` system call these
         * operations always take `struct flock` with 64-bit wide `off_t`. On
         * i386 `fcntl()` takes `struct flock` with 32-bit wide `off_t`
         * fields. `fcntl64` on the other hand can support both, the 32-bit
         * wide and 64-bit wide `off_t` fields. To differentiate this,
         * additional operations GETLK64, SETLK64 and SETLKW64 have been
         * introduced. These operations are _only_ supported in `fcntl64` on
         * 32-bit targets.
         *
         * To make things worse, the definition of F_GETLK and F_GETLK64 we
         * get from the userspace headers depends on the following factors:
         *
         * - in a 64-bit compilation environment they're both always
         *   set to 5,6,7, because `fcntl()` always uses struct
         *   flock64 with 64-bit wide `off_t.
         * - in a 32-bit compilation environment with
         *   _FILE_OFFSET_BITS=64 they're always set to 12,13,14 so
         *   that fcntl64 with struct flock64 is always used transparently.
         * - in a 32-bit compilation environment _without_
         *   _FILE_OFFSET_BITS=64 F_GETLK & friends are set to 5,6,7
         *   and F_GETLK64 & friends are set to 12,13,14 allowing to
         *   call regular fcntl() with 32-bit wide `off_t` and fcntl64() with
         *   32-bit or 64-bit `off_t`.
         *
         * Thus these constants are a moving target depending on a lot
         * of factors, which gets even more worse when a 64-bit tracer
         * is looking at a 32-bit emulation binary. For this reason we are
         * using our own literal values in FcntlOperation::Oper for the LK
         * family of operations.
         *
         * The rule of thumb when looking at the raw system call is that on
         * 64-bit targets either LK operation is always expecting a 64-bit
         * `off_t` struct. On a 32-bit target like I386 the literal values
         * 5,6,7 are always expecting a 32-bit `off_t` and the literal values
         * 12,13,14 are always expecting a 64-bit `off_t` (and are only
         * supported in `fcntl64()`).
         *
         * The OFD_ locks are not affected by this, they always use a 64-bit
         * wide `off_t` in `struct flock`.
         */
 
        cosmos::DeferGuard reset_lock{[this]() { m_lock.reset(); }};
 
        auto assign_data = [this, &reset_lock](const auto &lock) {
                if (!m_lock) {
                        m_lock = std::make_optional<cosmos::FileLock>(cosmos::FileLock::Type::READ_LOCK);
                }
 
                m_lock->l_type = lock.l_type;
                m_lock->l_whence = lock.l_whence;
                m_lock->l_start = lock.l_start;
                m_lock->l_len = lock.l_len;
                m_lock->l_pid = lock.l_pid;
                reset_lock.disarm();
        };
 
        auto fetch_lock = [this, assign_data, &proc]<typename FLOCK>() {
                FLOCK lock;
                if (proc.readStruct(asPtr(), lock)) {
                        assign_data(lock);
                }
        };
 
        if (const auto abi = m_call->abi(); abi != ABI::I386) {
                /*
                 * if the target ABI is 64-bit based then it's easy, simply
                 * use the only supported native 64-bit struct
                 */
                fetch_lock.operator()<kernel::flock64>();
                return;
        }
 
        // on i386 things get complicated
 
        if (const auto sysnr = m_call->callNr(); sysnr != SystemCallNr::FCNTL64) {
                /*
                 * for the old fcntl() call only the 32-bit `off_t` structure
                 * is supported. This one also has no alignment issues if the
                 * target is a 32-bit emulation binary.
                 */
                fetch_lock.operator()<kernel::flock32>();
                return;
        }
 
        /*
         * for the fcntl64() call both 32-bit and 64-bit `off_t` are supported
         * depending on the value found in the `op` parameter. Also we need to
         * consider alignment for flock64 in case we're dealing with an
         * emulation binary.
         */
        auto fcntl_sys = dynamic_cast<const FcntlSystemCall*>(m_call);
        if (!fcntl_sys)
                // alien system call?
                return;
 
        if (fcntl_sys->operation.isLock64()) {
                // either native 32-bit tracing or the target is a 32-bit
                // emulation binary, we need i386 alignment in both cases
                fetch_lock.operator()<kernel::flock64_i386>();
        } else {
                /*
                 * with the 32-bit flock no alignment issues should occur when
                 * tracing emulation binaries
                 */
                fetch_lock.operator()<kernel::flock32>();
        }
}

str()

std::string clues::item::FLockParameter::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 280 of file fcntl.cxx.

                                    {
        if (!m_lock) {
                return "<invalid>";
        }
 
        auto whence_str = [](short whence) {
                switch (whence) {
                        CASE_ENUM_TO_STR(SEEK_SET);
                        CASE_ENUM_TO_STR(SEEK_CUR);
                        CASE_ENUM_TO_STR(SEEK_END);
                        default: return "???";
                }
        };
 
        return cosmos::sprintf("{l_type=%s, l_whence=%s, l_start=%jd, l_len=%jd, l_pid=%d}",
                        lock_type_to_str(cosmos::to_integral(m_lock->type())).data(),
                        whence_str(cosmos::to_integral(m_lock->whence())),
                        m_lock->start(),
                        m_lock->start(),
                        cosmos::to_integral(m_lock->pid())
        );
}

updateData()

void clues::item::FLockParameter::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 260 of file fcntl.cxx.

                                                  {
        const auto fcntl_sc = dynamic_cast<const FcntlSystemCall*>(m_call);
        if (!fcntl_sc || fcntl_sc->operation.operation() != item::FcntlOperation::Oper::GETLK) {
                // only the F_GETLK operation causes changes on output
                return;
        }
 
        processValue(proc);
}

Member Data Documentation

m_lock

std::optional<cosmos::FileLock> clues::item::FLockParameter::m_lock

protected

Definition at line 144 of file fcntl.hxx.

---

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

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