Access to System Call Data. More...

#include <SystemCall.hxx>

Inheritance diagram for clues::SystemCall:

Public Types
using	ParameterVector = std::vector<SystemCallItemPtr>
	Vector of the parameters required for a system call.

Public Member Functions
	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
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 Member Functions
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 bool	check2ndPass (const Tracee &)
	Check whether a second pass needs to be made processing parameters.

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

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)

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

Friends
std::ostream &	operator<< (std::ostream &o, const SystemCall &sc)

Detailed Description

Access to System Call Data.

This type stores properties that are common to all system calls:

the system call number.
an ordered list of parameters the system call expects, represented by the abstract SystemCallItem base class.
a human readable name to identify the system call.

The stream output operator<< allows to generically output information about a system call.

Definition at line 47 of file SystemCall.hxx.

Member Typedef Documentation

◆ ParameterVector

using clues::SystemCall::ParameterVector = std::vector<SystemCallItemPtr>

Vector of the parameters required for a system call.

Definition at line 52 of file SystemCall.hxx.

Constructor & Destructor Documentation

◆ SystemCall()

clues::SystemCall::SystemCall ( const SystemCallNr nr )

Instantiates a new SystemCall object with given properties.

Parameters

[in] nr The unique well-known number of this system call.

Definition at line 36 of file SystemCall.cxx.

                                            :
                m_nr{nr}, m_name{SystemCall::name(nr)} {
}

◆ ~SystemCall()

virtual clues::SystemCall::~SystemCall ( )

inlinevirtual

Definition at line 63 of file SystemCall.hxx.

63{}

Member Function Documentation

◆ abi()

ABI clues::SystemCall::abi ( ) const

inline

Returns the system call ABi seen during system call entry.

Definition at line 110 of file SystemCall.hxx.

                        {
                return m_abi;
        }

◆ addParameters() [1/2]

void clues::SystemCall::addParameters ( )

inlineprotected

Definition at line 159 of file SystemCall.hxx.

159{}

◆ addParameters() [2/2]

template<typename T, typename... Targs>

void clues::SystemCall::addParameters	(	T &	par,
		Targs &...	rest )

inlineprotected

Definition at line 162 of file SystemCall.hxx.

                                                   {
                par.setSystemCall(*this);
                m_pars.push_back(&par);
                addParameters(rest...);
        }

◆ callNr()

SystemCallNr clues::SystemCall::callNr ( ) const

inline

Returns the system call table number for this system call.

Definition at line 90 of file SystemCall.hxx.

90{ return m_nr; }

◆ check2ndPass()

virtual bool clues::SystemCall::check2ndPass ( const Tracee & )

inlineprotectedvirtual

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 in clues::CloneSystemCall, clues::FcntlSystemCall, clues::FutexSystemCall, clues::MmapSystemCall, clues::OpenAtSystemCall, and clues::OpenSystemCall.

Definition at line 186 of file SystemCall.hxx.

186{ return false; };

◆ currentInfo()

const SystemCallInfo * clues::SystemCall::currentInfo ( ) const

inline

Access the current SystemCallInfo if currently processing syscall entry/exit.

Access to information is intended for a couple of SystemCallItem implementation that are context dependent on parameters that have not yet been parsed (e.g. size information follows after pointer to buffer/structure during system call entry.

Definition at line 134 of file SystemCall.hxx.

                                                  {
                return m_info;
        }

◆ dropFD()

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

protected

Definition at line 190 of file SystemCall.cxx.

                                                                   {
        proc.dropFD(num);
}

◆ error()

std::optional< ErrnoResult > clues::SystemCall::error ( ) const

inline

Access to the errno result seen for this system call.

Definition at line 97 of file SystemCall.hxx.

97{ return m_error; }

clues::SystemCall::m_error

std::optional< ErrnoResult > m_error

If the system call fails, this is the error code.

Definition SystemCall.hxx:224

◆ fillParameters()

void clues::SystemCall::fillParameters	(	const Tracee &	proc,
		const SystemCallInfo &	info )

protected

Definition at line 40 of file SystemCall.cxx.

                                                                              {
        const auto args = info.entryInfo()->args();
        std::vector<std::pair<SystemCallItem*, Word>> deferred;
 
        for (size_t numpar = 0; numpar < m_pars.size(); numpar++) {
                auto &par = *m_pars[numpar];
                if (item::is_unused_par(par))
                        continue;
 
                const auto word = Word{static_cast<Word>(args[numpar])};
 
                if (par.deferFill()) {
                        deferred.push_back({&par, word});
                        continue;
                }
 
                par.fill(proc, word);
        }
 
        for (const auto &[item, word]: deferred) {
                item->fill(proc, word);
        }
}

◆ hasErrorCode()

bool clues::SystemCall::hasErrorCode ( ) const

inline

Definition at line 105 of file SystemCall.hxx.

                                  {
                return !hasResultValue();
        }

◆ hasOutParameter()

bool clues::SystemCall::hasOutParameter ( ) const

Definition at line 80 of file SystemCall.cxx.

                                       {
        for (auto &par: m_pars) {
                if (par->needsUpdate())
                        return true;
        }
 
        return false;
}

◆ hasResultValue()

bool clues::SystemCall::hasResultValue ( ) const

inline

Definition at line 101 of file SystemCall.hxx.

                                    {
                return m_error == std::nullopt;
        }

◆ is32BitEmulationABI()

bool clues::SystemCall::is32BitEmulationABI ( ) const

inline

Definition at line 114 of file SystemCall.hxx.

                                         {
                return get_default_abi() == ABI::X86_64 && abi() == ABI::I386;
        }

◆ name() [1/2]

std::string_view clues::SystemCall::name ( ) const

inline

Returns the system call's human readable name.

Definition at line 86 of file SystemCall.hxx.

86{ return m_name; }

◆ name() [2/2]

const char * clues::SystemCall::name ( const SystemCallNr nr )

static

Returns the name of the given system call or "<unknown>" if unknown.

The returned string has static storage duration.

Definition at line 28 of file SystemCall.cxx.

                                                  {
        return SYSTEM_CALL_NAMES[cosmos::to_integral(nr)].data();
}

◆ numPars()

size_t clues::SystemCall::numPars ( ) const

inline

Returns the number of parameters for this system call.

Definition at line 88 of file SystemCall.hxx.

88{ return m_pars.size(); }

◆ parameters()

const ParameterVector & clues::SystemCall::parameters ( ) const

inline

Access to the parameters associated with this system call.

Definition at line 93 of file SystemCall.hxx.

93{ return m_pars; }

◆ prepareNewSystemCall()

virtual void clues::SystemCall::prepareNewSystemCall ( )

inlineprotectedvirtual

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

Reimplemented in clues::CloneSystemCall, clues::FcntlSystemCall, clues::FutexSystemCall, clues::MmapSystemCall, clues::OpenAtSystemCall, and clues::OpenSystemCall.

Definition at line 189 of file SystemCall.hxx.

189{}

◆ result()

SystemCallItemPtr clues::SystemCall::result ( ) const

inline

Access to the return value parameter associated with this system call.

Definition at line 95 of file SystemCall.hxx.

95{ return hasResultValue() ? m_return : nullptr; }

clues::SystemCall::m_return

SystemCallItemPtr m_return

The return value of the system call.

Definition SystemCall.hxx:222

◆ setEntryInfo()

void clues::SystemCall::setEntryInfo	(	const Tracee &	proc,
		const SystemCallInfo &	info )

Update the stored parameter values from the given tracee.

The given tracee is about to start the system call in question. Introspect the parameter values and store them in the current object's ParameterVector.

Definition at line 64 of file SystemCall.cxx.

                                                                            {
        m_abi = info.abi();
        m_error.reset();
        m_info = &info;
 
        prepareNewSystemCall();
 
        fillParameters(proc, info);
 
        if (check2ndPass(proc)) {
                fillParameters(proc, info);
        }
 
        m_info = nullptr;
}

◆ setExitInfo()

void clues::SystemCall::setExitInfo	(	const Tracee &	proc,
		const SystemCallInfo &	info )

Update possible out and return parameter values from the given tracee.

The given tracee just finished the system call in question. Introspect the return value and update out or in-out parameters as applicable.

Definition at line 89 of file SystemCall.cxx.

                                                                           {
        m_info = &info;
        const auto exit_info = *info.exitInfo();
 
        if (exit_info.isValue()) {
                m_return->fill(proc, Word{static_cast<Word>(*exit_info.retVal())});
        } else {
                m_error = ErrnoResult{*exit_info.errVal()};
        }
 
        for (auto &par: m_pars) {
                if (par->needsUpdate()) {
                        par->updateData(proc);
                }
        }
 
        if (exit_info.isValue()) {
                updateFDTracking(proc);
        }
 
        m_info = nullptr;
}

◆ setParameters()

template<typename... Targs>

void clues::SystemCall::setParameters ( Targs &... args )

inlineprotected

Definition at line 169 of file SystemCall.hxx.

                                           {
                m_pars.clear();
                addParameters(args...);
        }

◆ setReturnItem()

void clues::SystemCall::setReturnItem ( SystemCallItem & ret )

inlineprotected

Sets the return value system call item.

A pointer to the return parameter definition for this syscall. The pointer ownership will be moved to the new SystemCall instance, i.e. it will be deleted during destruction of SystemCall. For system calls where there is no return value (exit), a synthetic parameter instance should be passed to avoid having to deal with the possibility of no return value existing.

Definition at line 151 of file SystemCall.hxx.

                                                {
                m_return = &ret;
                m_return->setSystemCall(*this);
                if (!ret.isReturnValue()) {
                        throw cosmos::RuntimeError{"added non-return-value as return item"};
                }
        }

◆ trackFD()

void clues::SystemCall::trackFD	(	const Tracee &	proc,
		FDInfo &&	info )

protected

Definition at line 194 of file SystemCall.cxx.

                                                          {
        proc.trackFD(std::move(info));
}

◆ updateFDTracking()

virtual void clues::SystemCall::updateFDTracking ( const Tracee & proc )

inlineprotectedvirtual

Update file descriptor tracking.

This function is called upon successful system call exit to track any potential new file descriptors or stop tracking of existing file descriptors.

Specializations of SystemCall that create or close file descriptors need to overwrite this function and call proc.trackFD() or proc.dropFD() accordingly.

Reimplemented in clues::Clone3SystemCall, clues::CloseSystemCall, clues::FcntlSystemCall, clues::FutexSystemCall, clues::OpenAtSystemCall, clues::OpenSystemCall, and clues::PipeSystemCall.

Definition at line 201 of file SystemCall.hxx.

201{ (void)proc; }

◆ validNr()

bool clues::SystemCall::validNr ( const SystemCallNr nr )

static

Returns whether the given system call number is in a valid range.

Definition at line 32 of file SystemCall.cxx.

                                              {
        return cosmos::to_integral(nr) < SYSTEM_CALL_NAMES.size();
}

Friends And Related Symbol Documentation

◆ operator<<

std::ostream & operator<<	(	std::ostream &	o,
		const SystemCall &	sc )

friend

Definition at line 200 of file SystemCall.cxx.

                                                                 {
        o << sc.name() << " (" << cosmos::to_integral(sc.callNr()) << "): " << sc.numPars() << " parameters";
 
        for (const auto &par: sc.m_pars) {
                o << "\n\t" << *par;
        }
 
        o << "\n\tResult -> " << *(sc.m_return);
 
        return o;
}

Member Data Documentation

◆ m_abi

ABI clues::SystemCall::m_abi = ABI::UNKNOWN

protected

The current system call ABI which is in effect.

Definition at line 228 of file SystemCall.hxx.

◆ m_error

std::optional<ErrnoResult> clues::SystemCall::m_error

protected

If the system call fails, this is the error code.

Definition at line 224 of file SystemCall.hxx.

◆ m_info

const SystemCallInfo* clues::SystemCall::m_info = nullptr

protected

Current system call info during entry/exit processing, nullptr otherwise.

Definition at line 220 of file SystemCall.hxx.

◆ m_name

const std::string_view clues::SystemCall::m_name

protected

The basic name of the system call.

Definition at line 218 of file SystemCall.hxx.

◆ m_nr

SystemCallNr clues::SystemCall::m_nr

protected

The raw system call number of the system call.

Definition at line 216 of file SystemCall.hxx.

◆ m_pars

ParameterVector clues::SystemCall::m_pars

protected

The array of system call parameters, if any.

Definition at line 226 of file SystemCall.hxx.

◆ m_return

SystemCallItemPtr clues::SystemCall::m_return

protected

The return value of the system call.

Definition at line 222 of file SystemCall.hxx.

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

include/SystemCall.hxx
src/SystemCall.cxx

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ ParameterVector

Constructor & Destructor Documentation

◆ SystemCall()

◆ ~SystemCall()

Member Function Documentation

◆ abi()

◆ addParameters() [1/2]

◆ addParameters() [2/2]

◆ callNr()

◆ check2ndPass()

◆ currentInfo()

◆ dropFD()

◆ error()

◆ fillParameters()

◆ hasErrorCode()

◆ hasOutParameter()

◆ hasResultValue()

◆ is32BitEmulationABI()

◆ name() [1/2]

◆ name() [2/2]

◆ numPars()

◆ parameters()

◆ prepareNewSystemCall()

◆ result()

◆ setEntryInfo()

◆ setExitInfo()

◆ setParameters()

◆ setReturnItem()

◆ trackFD()

◆ updateFDTracking()

◆ validNr()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ m_abi

◆ m_error

◆ m_info

◆ m_name

◆ m_nr

◆ m_pars

◆ m_return