Signal Interfaces

Tasks and Signals. NuttX provides signal interfaces for tasks and pthreads. Signals are used to alter the flow control of tasks by communicating asynchronous events within or between task contexts. Any task or interrupt handler can post (or send) a signal to a particular task using its task ID. The task being signaled will execute task-specified signal handler function the next time that the task has priority. The signal handler is a user-supplied function that is bound to a specific signal and performs whatever actions are necessary whenever the signal is received.

By default, here are no predefined actions for any signal. The default action for all signals (i.e., when no signal handler has been supplied by the user) is to ignore the signal. In this sense, all NuttX are real time signals by default. If the configuration option CONFIG_SIG_DEFAULT=y is included, some signals will perform their default actions dependent upon addition configuration settings as summarized in the following table:

Signal	Action	Additional Configuration
SIGUSR1	Abnormal Termination	CONFIG_SIG_SIGUSR1_ACTION
SIGUSR2	Abnormal Termination	CONFIG_SIG_SIGUSR2_ACTION
SIGALRM	Abnormal Termination	CONFIG_SIG_SIGALRM_ACTION
SIGPOLL	Abnormal Termination	CONFIG_SIG_SIGPOLL_ACTION
SIGSTOP	Suspend task	CONFIG_SIG_SIGSTOP_ACTION
SIGTSTP	Suspend task	CONFIG_SIG_SIGSTOP_ACTION
SIGCONT	Resume task	CONFIG_SIG_SIGSTOP_ACTION
SIGINT	Abnormal Termination	CONFIG_SIG_SIGKILL_ACTION
SIGKILL	Abnormal Termination	CONFIG_SIG_SIGKILL_ACTION

Tasks may also suspend themselves and wait until a signal is received.

Tasks Groups. NuttX supports both tasks and pthreads. The primary difference between tasks and pthreads is the tasks are much more independent. Tasks can create pthreads and those pthreads will share the resources of the task. The main task and its children pthreads together are referred as a task group. A task group is used in NuttX to emulate a POSIX process.

Note

Behavior of features related to task groups depend of NuttX configuration settings. See also theNuttX Taskingpage and theTasks vs. Threads FAQfor additional information on tasks and threads in NuttX.

Signaling Multi-threaded Task Groups. The behavior of signals in the multi-thread task group is complex. NuttX emulates a process model with task groups and follows the POSIX rules for signaling behavior. Normally when you signal the task group you would signal using the task ID of the main task that created the group (in practice, a different task should not know the IDs of the internal threads created within the task group); that ID is remembered by the task group (even if the main task thread exits).

Here are some of the things that should happen when you signal a multi-threaded task group:

• If a task group receives a signal then one and only one indeterminate thread in the task group which is not blocking the signal will receive the signal.

• If a task group receives a signal and more than one thread is waiting on that signal, then one and only one indeterminate thread out of that waiting group will receive the signal.

You can mask out that signal using ‘’sigprocmask()’’ (or ‘’pthread_sigmask()’’). That signal will then be effectively disabled and will never be received in those threads that have the signal masked. On creation of a new thread, the new thread will inherit the signal mask of the parent thread that created it. So you if block signal signals on one thread then create new threads, those signals will also be blocked in the new threads as well.

You can control which thread receives the signal by controlling the signal mask. You can, for example, create a single thread whose sole purpose it is to catch a particular signal and respond to it: Simply block the signal in the main task; then the signal will be blocked in all of the pthreads in the group too. In the one “signal processing” pthread, enable the blocked signal. This thread will then be only thread that will receive the signal.

Signal Interfaces. The following signal handling interfaces are provided by NuttX:

• sigemptyset()

• sigfillset()

• sigaddset()

• sigdelset()

• sigismember()

• sigaction()

• sigignore()

• sigset()

• sigprocmask()

• sighold()

• sigrelse()

• sigpending()

• sigsuspend()

• sigpause()

• sigwaitinfo()

• sigtimedwait()

• sigqueue()

• kill()

• pause()

int sigemptyset(sigset_t *set)

Initializes the signal set specified by set such that all signals are excluded.

Parameters:

• set – Signal set to initialize.

Returns:

0 (OK), or -1 (ERROR) if the signal set cannot be initialized.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sigfillset(sigset_t *set);

Initializes the signal set specified by set such that all signals are included.

Parameters:

• set – Signal set to initialize

Returns:

0 (OK), or -1 (ERROR) if the signal set cannot be initialized.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sigaddset(sigset_t *set, int signo);

Adds the signal specified by signo to the signal set specified by set.

Parameters:

• set – Signal set to add signal to

• signo – Signal to add

Returns:

0 (OK), or -1 (ERROR) if the signal number is invalid.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sigdelset(sigset_t *set, int signo);

Deletes the signal specified by signo from the signal set specified by set.

Parameters:

• set – Signal set to delete the signal from

• signo – Signal to delete

Returns:

0 (OK), or -1 (ERROR) if the signal number is invalid.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sigismember(const sigset_t *set, int signo);

Tests whether the signal specified by signo is a member of the set specified by set.

Parameters:

• set – Signal set to test

• signo – Signal to test for

Returns:

• 1 (TRUE), if the specified signal is a member of the set,

• 0 (OK or FALSE), if it is not, or

• -1 (ERROR) if the signal number is invalid.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sigaction(int signo, const struct sigaction *act, struct sigaction *oact);

Allows the calling task to examine and/or specify the action to be associated with a specific signal.

The structure sigaction, used to describe an action to be taken, is defined to include the following members:

• sa_u.sa_handler. A pointer to a signal-catching function.

• sa_u.sa_sigaction. An alternative form for the signal catching function.

• sa_mask. Additional set of signals to be blocked during execution of the signal-catching function.

• sa_flags: Special flags to affect behavior of a signal.

If the argument act is not NULL, it points to a structure specifying the action to be associated with the specified signal. If the argument oact is not NULL, the action previously associated with the signal is stored in the location pointed to by the argument oact. If the argument act is NULL, signal handling is unchanged by this function call; thus, the call can be used to inquire about the current handling of a given signal.

When a signal is caught by a signal-catching function installed by the sigaction() function, a new signal mask is calculated and installed for the duration of the signal-catching function. This mask is formed by taking the union of the current signal mask and the value of the sa_mask for the signal being delivered, and then including the signal being delivered. If and when the signal handler returns, the original signal mask is restored.

Signal catching functions execute in the same address environment as the task that called sigaction() to install the signal-catching function.

Once an action is installed for a specific signal, it remains installed until another action is explicitly requested by another call to sigaction().

Parameters:

• sig – Signal of interest

• act – Location of new handler

• oact – Location to store old handler

Returns:

0 (OK), or -1 (ERROR) if the signal number is invalid.

POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the POSIX implementation include:

• There are no default actions so the special value SIG_DFL is treated like SIG_IGN.

• All sa_flags in struct sigaction of act input are ignored (all treated like SA_SIGINFO). The one exception is if CONFIG_SCHED_CHILD_STATUS is defined; then SA_NOCLDWAIT is supported but only for SIGCHLD.

int sigignore(int signo);

Sets the disposition of signo to SIG_IGN.

Parameters:

• signo – The signal number to act on

Returns:

• Zero is returned upon successful completion, otherwise -1 (ERROR) is returned with the errno set appropriately. The errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number.

void (*sigset(int signo, void (*disp)(int)))(int);

Modifies signal dispositions. The signo argument specifies the signal. The disp argument specifies the signal’s disposition, which may be SIG_DFL, SIG_IGN, or the address of a signal handler. If disp is the address of a signal handler, the system will add signo to the calling process’s signal mask before executing the signal handler; when the signal handler returns, the system will restore the calling process’s signal mask to its state prior to the delivery of the signal. signo will be removed from the calling process’s signal mask.

NOTE: The value SIG_HOLD for disp is not currently supported.

Parameters:

• signo – The signal number to operate on

• disp – The new disposition of the signal

Returns:

• Upon successful completion, sigset() will the previous disposition of the signal. Otherwise, SIG_ERR will be returned and errno set to indicate the error.

int sigprocmask(int how, const sigset_t *set, sigset_t *oset);

Allows the calling task to examine and/or change its signal mask. If the set is not NULL, then it points to a set of signals to be used to change the currently blocked set. The value of how indicates the manner in which the set is changed.

If there are any pending unblocked signals after the call to sigprocmask(), those signals will be delivered before sigprocmask() returns.

If sigprocmask() fails, the signal mask of the task is not changed.

Parameters:

• how – How the signal mask will be changed. - SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by the set input parameter. - SIG_UNBLOCK The resulting set is the intersection of the current set and the complement of the signal set pointed to by the set input parameter. - SIG_SETMASK The resulting set is the signal set pointed to by the set input parameter.

• set – Location of the new signal mask

• oset – Location to store the old signal mask

Returns:

0 (OK), or -1 (ERROR) if how is invalid.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sighold(int signo);

Adds signo to the calling process’s signal mask

Parameters:

• signo – Identifies the signal to be blocked.

Returns:

Zero is returned upon successful completion, otherwise -1 (ERROR) is returned with the errno set appropriately. The errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number.

int sigrelse(int signo);

Removes signo from the calling process’s signal mask

Parameters:

• signo – Identifies the signal to be unblocked.

Returns:

Zero is returned upon successful completion, otherwise -1 (ERROR) is returned with the errno set appropriately. The errno value of EINVAL, for example, would indicate that signo argument is not a valid signal number.

int sigpending(sigset_t *set);

Stores the returns the set of signals that are blocked for delivery and that are pending for the calling task in the space pointed to by set.

If the task receiving a signal has the signal blocked via its sigprocmask, the signal will pend until it is unmasked. Only one pending signal (for a given signo) is retained by the system. This is consistent with POSIX which states: “If a subsequent occurrence of a pending signal is generated, it is implementation defined as to whether the signal is delivered more than once.”

Parameters:

• set – The location to return the pending signal set.

Returns:

0 (OK) or -1 (ERROR)

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sigsuspend(const sigset_t *set);

Replaces the signal mask with the set of signals pointed to by the argument set and then suspends the task until delivery of a signal to the task.

If the effect of the set argument is to unblock a pending signal, then no wait is performed.

The original signal mask is restored when sigsuspend() returns.

Waiting for an empty signal set stops a task without freeing any resources (a very bad idea).

Parameters:

• set – The value of the signal mask to use while suspended.

Returns:

-1 (ERROR) always

POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the POSIX specification include:

• POSIX does not indicate that the original signal mask is restored.

• POSIX states that sigsuspend() “suspends the task until delivery of a signal whose action is either to execute a signal-catching function or to terminate the task.” Only delivery of the signal is required in the present implementation (even if the signal is ignored).

int sigpause(int signo);

Removes signo from the calling process’s signal mask and suspend the calling process until a signal is received. The sigpause()) function will restore the process’s signal mask to its original state before returning.

Parameters:

• set – Identifies the signal to be unblocked while waiting.

Returns:

sigpause always returns -1 (ERROR). On a successful wait for a signal, the errno will be set to EINTR.

int sigwaitinfo(const sigset_t *set, struct siginfo *info);

Equivalent to sigtimedwait() with a NULL timeout parameter. (see below).

param set:

The set of pending signals to wait for.

param info:

The returned signal values

return:

Signal number that cause the wait to be terminated, otherwise -1 (ERROR) is returned.

POSIX Compatibility: Comparable to the POSIX interface of the same name.

int sigtimedwait(const sigset_t *set, struct siginfo *info, const struct timespec *timeout);

Selects the pending signal set specified by the argument set. If multiple signals are pending in set, it will remove and return the lowest numbered one. If no signals in set are pending at the time of the call, the calling task will be suspended until one of the signals in set becomes pending OR until the task interrupted by an unblocked signal OR until the time interval specified by timeout (if any), has expired. If timeout is NULL, then the timeout interval is forever.

If the info argument is non-NULL, the selected signal number is stored in the si_signo member and the cause of the signal is store in the si_code member. The content of si_value is only meaningful if the signal was generated by sigqueue(). The following values for si_code are defined in signal.h:

• SI_USER. Signal sent from kill, raise, or abort

• SI_QUEUE. Signal sent from sigqueue

• SI_TIMER. Signal is result of timer expiration

• SI_ASYNCIO. Signal is the result of asynchronous IO completion

• SI_MESGQ. Signal generated by arrival of a message on an empty message queue.

Parameters:

• set – The set of pending signals to wait for.

• info – The returned signal values

• timeout – The amount of time to wait

Returns:

Signal number that cause the wait to be terminated, otherwise -1 (ERROR) is returned.

POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the POSIX interface include:

• Values for si_codes differ

• No mechanism to return cause of ERROR. (It can be inferred from si_code in a non-standard way).

• POSIX states that “If no signal is pending at the time of the call, the calling task will be suspended until one or more signals in set become pending or until it is interrupted by an unblocked, caught signal.” The present implementation does not require that the unblocked signal be caught; the task will be resumed even if the unblocked signal is ignored.

int sigqueue(int tid, int signo, union sigval value);

Sends the signal specified by signo with the signal parameter value to the task specified by tid.

If the receiving task has the signal blocked via its sigprocmask, the signal will pend until it is unmasked. Only one pending signal (for a given signo) is retained by the system. This is consistent with POSIX which states: “If a subsequent occurrence of a pending signal is generated, it is implementation defined as to whether the signal is delivered more than once.”

Parameters:

• tid – ID of the task to receive signal

• signo – Signal number

• value – Value to pass to task with signal

Returns:

On success (at least one signal was sent), zero (OK) is returned. On error, -1 (ERROR) is returned, and `errno <#ErrnoAccess>`__ is set appropriately.

• EGAIN. The limit of signals which may be queued has been reached.

• EINVAL. signo was invalid.

• EPERM. The task does not have permission to send the signal to the receiving process.

• ESRCH. No process has a PID matching pid.

POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the POSIX interface include:

• Default action is to ignore signals.

• Signals are processed one at a time in order

• POSIX states that, “If signo is zero (the null signal), error checking will be performed but no signal is actually sent.” There is no null signal in the present implementation; a zero signal will be sent.

int kill(pid_t pid, int sig);

The kill() system call can be used to send any signal to any task.

If the receiving task has the signal blocked via its sigprocmask, the signal will pend until it is unmasked. Only one pending signal (for a given signo) is retained by the system. This is consistent with POSIX which states: “If a subsequent occurrence of a pending signal is generated, it is implementation defined as to whether the signal is delivered more than once.”

Parameters:

• pid – The id of the task to receive the signal. The POSIX kill() specification encodes process group information as zero and negative pid values. Only positive, non-zero values of pid are supported by this implementation. ID of the task to receive signal

• signo – The signal number to send. If signo is zero, no signal is sent, but all error checking is performed.

Returns:

OK or ERROR

POSIX Compatibility: Comparable to the POSIX interface of the same name. Differences from the POSIX interface include:

• Default action is to ignore signals.

• Signals are processed one at a time in order

• Sending of signals to ‘process groups’ is not supported in NuttX.

int pause(void);

Suspends the calling thread until delivery of a non-blocked signal.

Returns:

Since pause() suspends thread execution indefinitely unless interrupted a signal, there is no successful completion return value. A value of -1 (ERROR will always be returned and errno set to indicate the error (EINTR).

POSIX Compatibility: In the POSIX description of this function is the pause() function will suspend the calling thread until delivery of a signal whose action is either to execute a signal-catching function or to terminate the process. This implementation only waits for any non-blocked signal to be received.