Data type used with signal::set_action() for controlling asynchronous signal delivery. More...

#include <SigAction.hxx>

Public Types
enum class	Flag : int { NO_CHILD_STOP = SA_NOCLDSTOP , NO_CHILD_WAIT = SA_NOCLDWAIT , NO_DEFER = SA_NODEFER , ON_STACK = SA_ONSTACK , RESET_HANDLER = static_cast<int>(SA_RESETHAND) , RESTART = SA_RESTART , SIGINFO = SA_SIGINFO , RESTORER = 0x04000000 }
	Settings influencing the behaviour of `signal::set_action()`. More...

using	Flags = BitMask<Flag>
	A mask of settings for `set_action()`.

using	SimpleHandler = void (*)(const Signal)
	Simple signal handler for receiving only the Signal number.

using	InfoHandler = void (*)(const SigInfo&)
	Extended signal handler for receiving additional SigInfo data.

Public Member Functions
	SigAction ()
	Creates a zero-initialized object.

	SigAction (const no_init_t)
	Leaves underlying data uninitialized.

void	clear ()
	overwrite the underlying data structure with zeroes.

void	setFlags (const Flags flags)
	Set new flags.

Flags	getFlags () const
	Retrieve the current flags.

const SigSet &	mask () const
	Access the currently set signal mask.

SigSet &	mask ()
	Access and possibly change the configured signal mask.

void	setHandler (SimpleHandler handler)
	Sets a new SimpleHandler style signal handler function.

void	setHandler (InfoHandler handler)
	Sets a new InfoHandler style signal handler function.

std::optional< SimpleHandler >	getSimpleHandler () const
	Returns the currently set SimpleHandler, if any.

std::optional< InfoHandler >	getInfoHandler () const
	Returns the currently set InfoHandler, if any.

const struct sigaction *	raw () const
	Read-only low-level access to the underlying data structure.

Static Public Attributes
static const SimpleHandler	IGNORE = reinterpret_cast<SigAction::SimpleHandler>((void*)1)
	Special value of SimpleHandler to ignore signals.

static const SimpleHandler	DEFAULT = SigAction::SimpleHandler{nullptr}
	Special value of SimpleHandler to configure the default signal action as documented in `man 7 signal`.

static const SimpleHandler	UNKNOWN = reinterpret_cast<SigAction::SimpleHandler>((void*)2)
	Special value of SimpleHandler in case a custom non-libcosmos handler is installed.

Protected Member Functions
struct sigaction *	raw ()
	Read-write low-level access to the underlying data structure.

void	updateFromOld (InfoHandler info, SimpleHandler simple)

Protected Attributes
struct sigaction	m_raw
	Low level sigaction struct.

std::variant< SimpleHandler, InfoHandler >	m_handler
	The currently configured callback.

Friends
void	signal::set_action (const Signal, const SigAction &, SigAction *)

void	signal::get_action (const Signal, SigAction &)

Detailed Description

Data type used with signal::set_action() for controlling asynchronous signal delivery.

See also: cosmos::signal::set_action().

Definition at line 28 of file SigAction.hxx.

Member Typedef Documentation

◆ Flags

using cosmos::SigAction::Flags = BitMask<Flag>

A mask of settings for set_action().

Definition at line 66 of file SigAction.hxx.

◆ InfoHandler

using cosmos::SigAction::InfoHandler = void (*)(const SigInfo&)

Extended signal handler for receiving additional SigInfo data.

Definition at line 71 of file SigAction.hxx.

◆ SimpleHandler

using cosmos::SigAction::SimpleHandler = void (*)(const Signal)

Simple signal handler for receiving only the Signal number.

Definition at line 69 of file SigAction.hxx.

Member Enumeration Documentation

◆ Flag

enum class cosmos::SigAction::Flag : int

strong

Settings influencing the behaviour of signal::set_action().

Enumerator
NO_CHILD_STOP	For SIGCHLD don't receive notification about child stop/resume events.
NO_CHILD_WAIT	For SIGCHLD, don't turn children into zombies upon termination, the signal is still received though.
NO_DEFER	Don't automatically add the signal to the thread's signal mask while the handler is executing.
ON_STACK	Call the signal handler on an alternate signal stack provided by `sigaltstack()`, see cosmos::signal::set_altstack().
RESET_HANDLER	Upon entry to the signal handler reset the signal action to its default again.
RESTART	Automatically restart certain system calls upon signal delivery, otherwise they return with Errno::INTERRUPTED.
SIGINFO	The signal handler callback takes three arguments providing additional information (SigInfo).
RESTORER	Used internally by libc, not used by applications.

Definition at line 34 of file SigAction.hxx.

                        : int {
                NO_CHILD_STOP  = SA_NOCLDSTOP,
                NO_CHILD_WAIT  = SA_NOCLDWAIT,
                NO_DEFER       = SA_NODEFER,
                ON_STACK       = SA_ONSTACK,
                /*
                 * This is the highest bit of the `int` and conflicts with the
                 * signedness of `int` when being used in an enum. Cast it explicitly
                 * to int to get around that.
                 */
                RESET_HANDLER  = static_cast<int>(SA_RESETHAND),
                RESTART        = SA_RESTART,
                SIGINFO        = SA_SIGINFO,
                /* The rest here did not make it into the user space headers (yet?) */
                RESTORER       = 0x04000000, /*SA_RESTORER*/
#if 0
                UNSUPPORTED    = SA_UNSUPPORTED,
                EXPOSE_TAGBITS = SA_EXPOSE_TAGBITS,
#endif
        };

Constructor & Destructor Documentation

◆ SigAction() [1/2]

cosmos::SigAction::SigAction ( )

inline

Creates a zero-initialized object.

Definition at line 83 of file SigAction.hxx.

                    {
                clear();
        }

◆ SigAction() [2/2]

cosmos::SigAction::SigAction ( const no_init_t )

inlineexplicit

Leaves underlying data uninitialized.

This constructor should be used if the object will be used as an output parameter. Zero initializing it would be wasteful in this case.

Definition at line 93 of file SigAction.hxx.

93{}

Member Function Documentation

◆ clear()

void cosmos::SigAction::clear ( )

inline

overwrite the underlying data structure with zeroes.

Definition at line 96 of file SigAction.hxx.

                     {
                zero_object(m_raw);
        }

◆ getFlags()

Flags cosmos::SigAction::getFlags ( ) const

inline

Retrieve the current flags.

Definition at line 118 of file SigAction.hxx.

                               {
                return Flags{m_raw.sa_flags};
        }

◆ getInfoHandler()

std::optional< InfoHandler > cosmos::SigAction::getInfoHandler ( ) const

inline

Returns the currently set InfoHandler, if any.

Definition at line 170 of file SigAction.hxx.

                                                        {
                if (std::holds_alternative<InfoHandler>(m_handler)) {
                        return std::get<InfoHandler>(m_handler);
                }
 
                return {};
        }

◆ getSimpleHandler()

std::optional< SimpleHandler > cosmos::SigAction::getSimpleHandler ( ) const

inline

Returns the currently set SimpleHandler, if any.

If the object has been assigned by the kernel e.g. via signal::get_action() then a SigAction::UNKNOWN handler can be returned here, if the handler has been configured by non-libcosmos routines. In this case one can inspect low level pointer value found in raw()->sa_handler or raw()->sa_siginfo, respectively.

Definition at line 161 of file SigAction.hxx.

                                                            {
                if (std::holds_alternative<SimpleHandler>(m_handler)) {
                        return std::get<SimpleHandler>(m_handler);
                }
 
                return {};
        }

◆ mask() [1/2]

SigSet & cosmos::SigAction::mask ( )

inline

Access and possibly change the configured signal mask.

This signal mask will be active for the time of asynchronous signal handler execution. The signal that triggered the execution will always be blocked, unless Flags::NO_DEFER is set in Flags.

Definition at line 134 of file SigAction.hxx.

                       {
                auto mask = reinterpret_cast<SigSet*>(&m_raw.sa_mask);
                return *mask;
        }

◆ mask() [2/2]

const SigSet & cosmos::SigAction::mask ( ) const

inline

Access the currently set signal mask.

Definition at line 123 of file SigAction.hxx.

                                   {
                const auto mask = reinterpret_cast<const SigSet*>(&m_raw.sa_mask);
                return *mask;
        }

◆ raw() [1/2]

struct sigaction * cosmos::SigAction::raw ( )

inlineprotected

Read-write low-level access to the underlying data structure.

Definition at line 186 of file SigAction.hxx.

                                {
                return &m_raw;
        }

◆ raw() [2/2]

const struct sigaction * cosmos::SigAction::raw ( ) const

inline

Read-only low-level access to the underlying data structure.

Definition at line 179 of file SigAction.hxx.

                                            {
                return &m_raw;
        }

◆ setFlags()

void cosmos::SigAction::setFlags ( const Flags flags )

inline

Set new flags.

Note: This call does not allow to change the setting of Flags::SIGINFO. This flag is maintained internally by SigAction, since it needs to match the requested signal handler type.

Definition at line 106 of file SigAction.hxx.

                                         {
                const auto had_siginfo = (m_raw.sa_flags & SA_SIGINFO) != 0;
                m_raw.sa_flags = flags.raw();
 
                if (had_siginfo) {
                        m_raw.sa_flags |= SA_SIGINFO;
                } else {
                        m_raw.sa_flags &= ~SA_SIGINFO;
                }
        }

◆ setHandler() [1/2]

void cosmos::SigAction::setHandler ( InfoHandler handler )

Sets a new InfoHandler style signal handler function.

The Flag::SIGINFO setting will be switched on implicitly by this call.

Definition at line 158 of file SigAction.cxx.

                                              {
        // NOTE: don't use setFlags() here, since it doesn't allow changing
        // SA_SIGINFO!
        m_raw.sa_flags |= SA_SIGINFO;
        m_raw.sa_sigaction = &info_handler;
        m_handler = handler;
}

◆ setHandler() [2/2]

void cosmos::SigAction::setHandler ( SimpleHandler handler )

Sets a new SimpleHandler style signal handler function.

The Flag::SIGINFO setting will be switched off implicitly by this call.

Definition at line 138 of file SigAction.cxx.

                                                {
        if (handler == UNKNOWN) {
                cosmos_throw (UsageError("Cannot set UNKNOWN type handler"));
        }
 
        // NOTE: don't use setFlags() here, since it doesn't allow changing
        // SA_SIGINFO!
        m_raw.sa_flags &= ~SA_SIGINFO;
 
        if (handler == IGNORE) {
                m_raw.sa_handler = SIG_IGN;
        } else if (handler == DEFAULT) {
                m_raw.sa_handler = SIG_DFL;
        } else {
                m_raw.sa_handler = &simple_handler;
        }
 
        m_handler = handler;
}

◆ updateFromOld()

void cosmos::SigAction::updateFromOld	(	InfoHandler	info,
		SimpleHandler	simple )

protected

Definition at line 166 of file SigAction.cxx.

                                                                    {
        // we need to reflect the data found in m_raw into m_handler, if
        // anybody should get the idea to compare it.
 
        if (getFlags()[Flag::SIGINFO]) {
                if (m_raw.sa_sigaction != info_handler) {
                        // it's a custom handler not set by libcosmos routines
                        m_handler = UNKNOWN;
                } else {
                        // it's the old siginfo handler supplied to us
                        m_handler = info;
                }
        } else {
                if (m_raw.sa_handler == SIG_DFL) {
                        m_handler = DEFAULT;
                } else if (m_raw.sa_handler == SIG_IGN) {
                        m_handler = IGNORE;
                } else if (m_raw.sa_handler != simple_handler) {
                        // it's a custom handler not set by libcosmos routines
                        m_handler = UNKNOWN;
                } else {
                        // it's the old simple handler supplied to us
                        m_handler = simple;
                }
        }
}

Member Data Documentation

◆ DEFAULT

const SigAction::SimpleHandler cosmos::SigAction::DEFAULT = SigAction::SimpleHandler{nullptr}

static

Special value of SimpleHandler to configure the default signal action as documented in man 7 signal.

Definition at line 76 of file SigAction.hxx.

◆ IGNORE

const SigAction::SimpleHandler cosmos::SigAction::IGNORE = reinterpret_cast<SigAction::SimpleHandler>((void*)1)

static

Special value of SimpleHandler to ignore signals.

Definition at line 74 of file SigAction.hxx.

◆ m_handler

std::variant<SimpleHandler,InfoHandler> cosmos::SigAction::m_handler

protected

The currently configured callback.

Definition at line 198 of file SigAction.hxx.

◆ m_raw

struct sigaction cosmos::SigAction::m_raw

protected

Low level sigaction struct.

Definition at line 195 of file SigAction.hxx.

◆ UNKNOWN

const SigAction::SimpleHandler cosmos::SigAction::UNKNOWN = reinterpret_cast<SigAction::SimpleHandler>((void*)2)

static

Special value of SimpleHandler in case a custom non-libcosmos handler is installed.

Definition at line 78 of file SigAction.hxx.

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

include/proc/SigAction.hxx
src/proc/SigAction.cxx

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ Flags

◆ InfoHandler

◆ SimpleHandler

Member Enumeration Documentation

◆ Flag

Constructor & Destructor Documentation

◆ SigAction() [1/2]

◆ SigAction() [2/2]

Member Function Documentation

◆ clear()

◆ getFlags()

◆ getInfoHandler()

◆ getSimpleHandler()

◆ mask() [1/2]

◆ mask() [2/2]

◆ raw() [1/2]

◆ raw() [2/2]

◆ setFlags()

◆ setHandler() [1/2]

◆ setHandler() [2/2]

◆ updateFromOld()

Member Data Documentation

◆ DEFAULT

◆ IGNORE

◆ m_handler

◆ m_raw

◆ UNKNOWN