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