nuttx/Documentation/reference/user/07_signals.rst

=================
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 group\ s depend of NuttX
  configuration settings. See also the\ `NuttX
  Tasking <https://cwiki.apache.org/confluence/display/NUTTX/NuttX+Tasking>`__\ page
  and the\ `Tasks vs. Threads
  FAQ <https://cwiki.apache.org/confluence/display/NUTTX/Tasks+vs.+Threads+FAQ>`__\ for
  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:

- :c:func:`sigemptyset`
- :c:func:`sigfillset`
- :c:func:`sigaddset`
- :c:func:`sigdelset`
- :c:func:`sigismember`
- :c:func:`sigaction`
- :c:func:`sigignore`
- :c:func:`sigset`
- :c:func:`sigprocmask`
- :c:func:`sighold`
- :c:func:`sigrelse`
- :c:func:`sigpending`
- :c:func:`sigsuspend`
- :c:func:`sigpause`
- :c:func:`sigwaitinfo`
- :c:func:`sigtimedwait`
- :c:func:`sigqueue`
- :c:func:`kill`
- :c:func:`pause`

.. c:function:: int sigemptyset(sigset_t *set)

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

  :param set: Signal set to initialize.

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

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

.. c:function:: int sigfillset(sigset_t *set);

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

  :param set: Signal set to initialize

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

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

.. c:function:: int sigaddset(sigset_t *set, int signo);

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

  :param set: Signal set to add signal to
  :param signo: Signal to add

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

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

.. c:function:: int sigdelset(sigset_t *set, int signo);

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

  :param set: Signal set to delete the signal from
  :param signo: Signal to delete

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

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

.. c:function:: int  sigismember(const sigset_t *set, int signo);

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

  :param set: Signal set to test
  :param signo: Signal to test for

  :return:
    -  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.

.. c:function:: 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().

  :param sig: Signal of interest
  :param act: Location of new handler
  :param oact: Location to store old handler

  :return: 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``.

.. c:function:: int sigignore(int signo);

  Sets the disposition of ``signo`` to ``SIG_IGN``.

  :param signo: The signal number to act on

  :return:
    -  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.

.. c:function:: 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.

  :param signo: The signal number to operate on
  :param disp: The new disposition of the signal

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

.. c:function:: 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.

  :param 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.

  :param set: Location of the new signal mask
  :param oset: Location to store the old signal mask

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

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

.. c:function:: int sighold(int signo);

  Adds ``signo`` to the calling process's signal mask

  :param signo: Identifies the signal to be blocked.

  :return:
    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.

.. c:function:: int sigrelse(int signo);

  Removes ``signo`` from the calling process's signal mask

  :param signo: Identifies the signal to be unblocked.

  :return:
    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.

.. c:function:: 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."

  :param set: The location to return the pending signal set.

  :return: 0 (``OK``) or -1 (``ERROR``)

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

.. c:function:: 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).

  :param set: The value of the signal **mask** to use while suspended.

  :return: -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).

.. c:function:: 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.

  :param set: Identifies the signal to be unblocked while waiting.

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

.. c:function:: 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.

.. c:function:: 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.

  :param set: The set of pending signals to wait for.
  :param info: The returned signal values
  :param timeout: The amount of time to wait

  :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. 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.

.. c:function:: 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."

  :param tid: ID of the task to receive signal
  :param signo: Signal number
  :param value: Value to pass to task with signal

  :return:
    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.

.. c:function:: 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."

  :param 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
  :param signo: The signal number to send. If signo is zero, no signal is
    sent, but all error checking is performed.

  :return: 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.

.. c:function:: int pause(void);

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

  :return: 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.