Signal information struct used when receiving signals. More...

#include <SigInfo.hxx>

Classes
struct	BusData
	Additional data delivered with SIGBUS signals. More...

struct	ChildData
	Additional data found in SigInfo with SIGCHILD. More...

struct	CustomData
	Additional custom SigInfo data. More...

struct	FaultData
	Additional data found in SigInfo for one of the memory fault / trap signals. More...

struct	FPEData
	Extra data delivered with SIGFPE signals. More...

struct	IllData
	Additional data delivered with SIGILL signals. More...

struct	MsgQueueData
	Additional data found in SigInfo with Source::MESGQ. More...

struct	PollData
	Additional data found in SigInfo with SIGPOLL. More...

struct	ProcessCtx
	Information about the process a signal is from or about. More...

struct	QueueSigData
	Additional data found in SigInfo with Source::QUEUE. More...

struct	SegfaultData
	Additional data delivered with SIGSEGV signals. More...

struct	SysData
	Additional data found in SigInfo delivered with SIGSYS. More...

struct	TimerData
	Additional data found in SigInfo with Source::TIMER. More...

struct	UserSigData
	Additional data found in SigInfo with Source::USER. More...

Public Types
enum class	Source : int { USER = SI_USER , KERNEL = SI_KERNEL , QUEUE = SI_QUEUE , TIMER = SI_TIMER , MESGQ = SI_MESGQ , ASYNCIO = SI_ASYNCIO , QSIGIO = SI_SIGIO , TKILL = SI_TKILL }
	The source of a signal. More...

Public Member Functions
	SigInfo ()
	Creates a zero-initialized SigInfo wrapper.

	SigInfo (const no_init_t)
	Leaves the underlying data structure uninitialized.

Signal	sigNr () const
	Returns the signal number that occurred.

Source	source () const
	Returns the source of the signal.

bool	isTrustedSource () const
	Returns whether the signal was sent from a trusted source (i.e. the kernel).

bool	isFaultSignal () const
	Returns whether the signal is one of the fault signals.

std::optional< const UserSigData >	userSigData () const
	Returns the Source::USER specific data.

std::optional< const QueueSigData >	queueSigData () const
	Returns the Source::QUEUE specific data.

std::optional< const MsgQueueData >	msgQueueData () const
	Returns the Source::MSGQ specific data.

std::optional< const TimerData >	timerData () const
	Returns the Source::TIMER specific data.

std::optional< const SysData >	sysData () const
	Returns signal::BAD_SYS specific data.

std::optional< const ChildData >	childData () const
	Returns signal::CHILD specific data.

std::optional< const PollData >	pollData () const
	Returns signal::POLL specific data.

std::optional< const IllData >	illData () const
	Returns SIGILL specific data.

std::optional< const FPEData >	fpeData () const
	Returns SIGFPE specific data.

std::optional< const SegfaultData >	segfaultData () const
	Returns SIGSEGV specific data.

std::optional< const BusData >	busData () const
	Returns SIGBUS specific data.

void	clear ()
	Zeroes out the low level siginfo_t data structure.

const siginfo_t *	raw () const

siginfo_t *	raw ()

Protected Member Functions
Errno	error () const
	Returns an error code that is generally unused on Linux (always 0).

ProcessCtx	procCtx () const

ProcessID	pid () const

UserID	uid () const

Protected Attributes
siginfo_t	m_raw

Detailed Description

Signal information struct used when receiving signals.

This kernel data structure is union-like and most of its fields only have meaning - and sometimes different meanings - depending on the SigInfo::Source value. Thus most information is returned as a std::optional containing a separate SigInfo::<Kind>Data type which contains the specialized data relevant for the context.

TODO: check whether it makes sense to add TrapData for SIGTRAP. It is a bit unclear what exactly to expect, since ptrace(2) is insanely complex.

Definition at line 79 of file SigInfo.hxx.

Member Enumeration Documentation

◆ Source

enum class cosmos::SigInfo::Source : int

strong

The source of a signal.

Enumerator
USER	sent via kill().
KERNEL	sent by the kernel.
QUEUE	sent from user space via sigqueue().
TIMER	POSIX timer expired.
MESGQ	POSIX message queue state changed.
ASYNCIO	AIO completed.
QSIGIO	queued SIGIO (only up to Linux 2.2).
TKILL	sent by tkill() or tgkill().

Definition at line 83 of file SigInfo.hxx.

                          : int {
                USER    = SI_USER,    
                KERNEL  = SI_KERNEL,  
                QUEUE   = SI_QUEUE,   
                TIMER   = SI_TIMER,   
                MESGQ   = SI_MESGQ,   
                ASYNCIO = SI_ASYNCIO, 
                QSIGIO  = SI_SIGIO,   
                TKILL   = SI_TKILL,   
        };

Constructor & Destructor Documentation

◆ SigInfo() [1/2]

cosmos::SigInfo::SigInfo ( )

inline

Creates a zero-initialized SigInfo wrapper.

Definition at line 471 of file SigInfo.hxx.

                  {
                clear();
        }

◆ SigInfo() [2/2]

cosmos::SigInfo::SigInfo ( const no_init_t )

inline

Leaves the underlying data structure uninitialized.

When SigInfo is used as an output parameter only (the typical case) then you can invoke this constructor to avoid unnecessary zero-initialization.

Definition at line 481 of file SigInfo.hxx.

481{}

Member Function Documentation

◆ busData()

std::optional< const SigInfo::BusData > cosmos::SigInfo::busData ( ) const

Returns SIGBUS specific data.

This data is only available if sigNr() == signal::BUS.

Definition at line 181 of file SigInfo.cxx.

                                                         {
        if (sigNr() == signal::BUS) {
                using Reason = BusData::Reason;
                const auto reason = Reason{m_raw.si_code};
                return BusData{
                        {m_raw.si_addr},
                        reason,
                        in_list(reason, {Reason::MCE_ACTION_REQUIRED, Reason::MCE_ACTION_OPTIONAL}) ?
                                std::make_optional(m_raw.si_addr_lsb) :
                                std::nullopt
                };
        }
 
        return std::nullopt;
}

◆ childData()

std::optional< const SigInfo::ChildData > cosmos::SigInfo::childData ( ) const

Returns signal::CHILD specific data.

This data is only available for sigNr() == signal::CHILD.

Definition at line 82 of file SigInfo.cxx.

                                                             {
        if (sigNr() == signal::CHILD) {
                using Event = ChildData::Event;
                const auto event = Event{m_raw.si_code};
                /*
                 * since this siginfo_t is so hacky, let's hack it a bit on our own:
                 *
                 * the structure is reused in the waitid() system call, but
                 * not fully filled like when used with sigwaitinfo(). In this
                 * case there is no si_utime and no si_stime. To avoid
                 * duplicating this code just to leave out these two optionals
                 * the cosmos::proc::wait() sets si_errno to EINVAL (si_errno
                 * is also unused with waitid()).
                 */
                const auto is_waitid_res = error() == Errno::INVALID_ARG;
 
                return ChildData{
                        event,
                        this->procCtx(),
                        event == Event::EXITED ? std::make_optional(ExitStatus{m_raw.si_status}) : std::nullopt,
                        event == Event::EXITED ? std::nullopt : std::make_optional(Signal{SignalNr{m_raw.si_status}}),
                        is_waitid_res ? std::nullopt : std::make_optional(ClockTicks{m_raw.si_utime}),
                        is_waitid_res ? std::nullopt : std::make_optional(ClockTicks{m_raw.si_stime})
                };
        }
 
        return std::nullopt;
}

◆ clear()

void cosmos::SigInfo::clear ( )

inline

Zeroes out the low level siginfo_t data structure.

Definition at line 581 of file SigInfo.hxx.

                     {
                zero_object(m_raw);
        }

◆ error()

Errno cosmos::SigInfo::error ( ) const

inlineprotected

Returns an error code that is generally unused on Linux (always 0).

An exception is the case of SIGSYS generated by seccomp(2) filters.

Definition at line 599 of file SigInfo.hxx.

                            {
                return Errno{m_raw.si_errno};
        }

◆ fpeData()

std::optional< const SigInfo::FPEData > cosmos::SigInfo::fpeData ( ) const

Returns SIGFPE specific data.

This data is only available if sigNr() == signal::FPE.

Definition at line 151 of file SigInfo.cxx.

                                                         {
        if (sigNr() == signal::FPE) {
                return FPEData{
                        {m_raw.si_addr},
                        FPEData::Reason{m_raw.si_code}
                };
        }
 
        return std::nullopt;
}

◆ illData()

std::optional< const SigInfo::IllData > cosmos::SigInfo::illData ( ) const

Returns SIGILL specific data.

This data is only available if sigNr() == signal::ILL.

Definition at line 140 of file SigInfo.cxx.

                                                         {
        if (sigNr() == signal::ILL) {
                return IllData{
                        {m_raw.si_addr},
                        IllData::Reason{m_raw.si_code}
                };
        }
 
        return std::nullopt;
}

◆ isFaultSignal()

bool cosmos::SigInfo::isFaultSignal ( ) const

Returns whether the signal is one of the fault signals.

Definition at line 28 of file SigInfo.cxx.

                                  {
        /*
         * should we require isTrustedSource() as well here?
         *
         * I guess, formally yes, but there could be some situations
         * like in emulation or test environments, where other user
         * space processes send such signals.
         *
         * The kernel checks for privileges before it allows user
         * space to send a signal to another process, so this is less
         * of a security concern, more a concern of maintaining
         * integrity. If user space sends these signals then we cannot
         * know for sure that the data found in the siginfo_t is sane.
         */
        return in_list(sigNr(), {
                        signal::ILL, signal::FPE, signal::SEGV,
                        signal::BUS, signal::TRAP});
}

◆ isTrustedSource()

bool cosmos::SigInfo::isTrustedSource ( ) const

inline

Returns whether the signal was sent from a trusted source (i.e. the kernel).

Only the kernel is allowed to set an si_code >= 0. This is an indicator whether we can fully trust the integrity of the data contained in the siginfo_t.

An exception is when a process sends itself a signal, but this can also be considered a trusted source in all but very special cases (like executing untrusted code in another thread?).

Definition at line 519 of file SigInfo.hxx.

                                     {
                return m_raw.si_code >= 0;
        }

◆ msgQueueData()

std::optional< const SigInfo::MsgQueueData > cosmos::SigInfo::msgQueueData ( ) const

Returns the Source::MSGQ specific data.

Definition at line 63 of file SigInfo.cxx.

                                                                   {
        if (source() == SigInfo::Source::MESGQ) {
                return MsgQueueData{this->procCtx(), CustomData{m_raw.si_value}};
        }
 
        return std::nullopt;
}

◆ pid()

ProcessID cosmos::SigInfo::pid ( ) const

inlineprotected

Definition at line 607 of file SigInfo.hxx.

                              {
                return ProcessID{m_raw.si_pid};
        }

◆ pollData()

std::optional< const SigInfo::PollData > cosmos::SigInfo::pollData ( ) const

Returns signal::POLL specific data.

This data is only available for sigNr() == signal::POLL.

Definition at line 125 of file SigInfo.cxx.

                                                           {
        // SIGIO and SIGPOLL are the same on Linux, but just to be sure ...
        if (sigNr() == signal::IO_EVENT || sigNr() == signal::POLL) {
                return PollData{
                        PollData::Reason{m_raw.si_code},
                        FileNum{m_raw.si_fd},
                        /* there are conflicting types, PollEvents is short
                         * but in sigaction it's a long */
                        PollEvents{static_cast<short>(m_raw.si_band)}
                };
        }
 
        return std::nullopt;
}

◆ procCtx()

ProcessCtx cosmos::SigInfo::procCtx ( ) const

inlineprotected

Definition at line 603 of file SigInfo.hxx.

                                   {
                return ProcessCtx{pid(), uid()};
        }

◆ queueSigData()

std::optional< const SigInfo::QueueSigData > cosmos::SigInfo::queueSigData ( ) const

Returns the Source::QUEUE specific data.

Definition at line 55 of file SigInfo.cxx.

                                                                   {
        if (source() == SigInfo::Source::QUEUE) {
                return QueueSigData{this->procCtx(), CustomData{m_raw.si_value}};
        }
 
        return std::nullopt;
}

◆ raw() [1/2]

siginfo_t * cosmos::SigInfo::raw ( )

inline

Definition at line 589 of file SigInfo.hxx.

                         {
                return &m_raw;
        }

◆ raw() [2/2]

const siginfo_t * cosmos::SigInfo::raw ( ) const

inline

Definition at line 585 of file SigInfo.hxx.

                                     {
                return &m_raw;
        }

◆ segfaultData()

std::optional< const SigInfo::SegfaultData > cosmos::SigInfo::segfaultData ( ) const

Returns SIGSEGV specific data.

This data is only available if sigNr() == signal::SEGV.

Definition at line 162 of file SigInfo.cxx.

                                                                   {
        if (sigNr() == signal::SEGV) {
                using Reason = SegfaultData::Reason;
                const auto reason = Reason{m_raw.si_code};
                return SegfaultData{
                        {m_raw.si_addr},
                        reason,
                        reason == Reason::BOUND_ERROR ?
                                std::make_optional(SegfaultData::Bound{m_raw.si_lower, m_raw.si_upper}) :
                                std::nullopt,
                        reason == Reason::PROT_KEY_ERROR ?
                                std::make_optional(SegfaultData::ProtectionKey{m_raw.si_pkey}) :
                                std::nullopt
                };
        }
 
        return std::nullopt;
}

◆ sigNr()

Signal cosmos::SigInfo::sigNr ( ) const

inline

Returns the signal number that occurred.

Definition at line 484 of file SigInfo.hxx.

                             {
                return Signal{SignalNr{m_raw.si_signo}};
        }

◆ source()

SigInfo::Source cosmos::SigInfo::source ( ) const

Returns the source of the signal.

For some special signals SigSource::KERNEL is implied if isTrustedSource() returns true. These special signals are SIGFPE, SIGBUS, SIGILL, SIGSEGV, SIGBUS, SIGTRAP, SIGCHILD, SIGPOLL/SIGIO and SIGSYS.

These signals use the si_code field for special data, but their source is the kernel, if isTrustedSource() returns true. Implying SigSource::KERNEL in these situations allows us to always return a value here instead of a std::optional, which could be empty in these cases.

Since other user space processes are allowed to set arbitrary Source values smaller than 0 it can happen that values outside the defined Source constants are returned here. The interpretation of source() is application specific in these cases (or should be ignored, if not expected).

Definition at line 12 of file SigInfo.cxx.

                                    {
        const std::initializer_list<Signal> SPECIAL_SIGS{
                signal::FPE, signal::BUS, signal::ILL, signal::SEGV,
                signal::BUS, signal::TRAP, signal::CHILD, signal::POLL,
                signal::BAD_SYS};
 
        // the lower level system call `rt_sigqueueinfo` allows userspace to
        // send arbitrary codes < 0, thus the signal number alone doesn't mean
        // the kernel was the source.
        if (isTrustedSource() && in_list(this->sigNr(), SPECIAL_SIGS)) {
                return Source::KERNEL;
        }
 
        return Source{m_raw.si_code};
}

◆ sysData()

std::optional< const SigInfo::SysData > cosmos::SigInfo::sysData ( ) const

Returns signal::BAD_SYS specific data.

This data is only available for sigNr() == signal::BAD_SYS.

Definition at line 111 of file SigInfo.cxx.

                                                         {
        if (sigNr() == signal::BAD_SYS) {
                return SysData{
                        SysData::Reason{m_raw.si_code},
                        m_raw.si_call_addr,
                        m_raw.si_syscall,
                        ptrace::Arch{m_raw.si_arch},
                        this->error()
                };
        }
 
        return std::nullopt;
}

◆ timerData()

std::optional< const SigInfo::TimerData > cosmos::SigInfo::timerData ( ) const

Returns the Source::TIMER specific data.

Definition at line 71 of file SigInfo.cxx.

                                                             {
        if (source() == SigInfo::Source::TIMER) {
                return TimerData{
                        TimerData::TimerID{m_raw.si_timerid},
                        m_raw.si_overrun
                };
        }
 
        return std::nullopt;
}

◆ uid()

UserID cosmos::SigInfo::uid ( ) const

inlineprotected

Definition at line 611 of file SigInfo.hxx.

                           {
                return UserID{m_raw.si_uid};
        }

◆ userSigData()

std::optional< const SigInfo::UserSigData > cosmos::SigInfo::userSigData ( ) const

Returns the Source::USER specific data.

Definition at line 47 of file SigInfo.cxx.

                                                                 {
        if (source() == SigInfo::Source::USER) {
                return UserSigData{this->procCtx()};
        }
 
        return std::nullopt;
}

Member Data Documentation

◆ m_raw

siginfo_t cosmos::SigInfo::m_raw

protected

Definition at line 617 of file SigInfo.hxx.

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

include/proc/SigInfo.hxx
src/proc/SigInfo.cxx

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Source

Constructor & Destructor Documentation

◆ SigInfo() [1/2]

◆ SigInfo() [2/2]

Member Function Documentation

◆ busData()

◆ childData()

◆ clear()

◆ error()

◆ fpeData()

◆ illData()

◆ isFaultSignal()

◆ isTrustedSource()

◆ msgQueueData()

◆ pid()

◆ pollData()

◆ procCtx()

◆ queueSigData()

◆ raw() [1/2]

◆ raw() [2/2]

◆ segfaultData()

◆ sigNr()

◆ source()

◆ sysData()

◆ timerData()

◆ uid()

◆ userSigData()

Member Data Documentation

◆ m_raw