Mirrors_Framework/nuttx
1
0
Fork 0
mirror of https://github.com/apache/nuttx.git synced 2026-05-20 20:44:39 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
Files
master
nuttx/Documentation/reference/user/07_signals.rst
T
Adwait Godbole 16e2aa0922
Build Documentation / build-html (push) Has been cancelled
Details
docs: Update Signal Interfaces documentation 
Update the Signal Interfaces documentation to include all
signals with configurable default actions and group them
by behavior for improved readability.

This reflects the current implementation in
sched/signal/sig_default.c.

Signed-off-by: Adwait Godbole <adwaitngodbole@gmail.com>
2026-01-31 10:07:36 -03:00

558 lines
23 KiB
ReStructuredText
Raw Permalink Blame History

=================
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, there 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 additional configuration settings as
summarized in the following tables:
.. note::
The default actions listed below reflect the current implementation in
``sched/signal/sig_default.c``.
Abnormal Termination Signals
----------------------------
========== ==================== =========================
Signal Action Additional Configuration
========== ==================== =========================
SIGHUP Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGINT Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGQUIT Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGILL Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGTRAP Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGABRT Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGBUS Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGFPE Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGKILL Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGSEGV Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGTERM Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGXCPU Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGXFSZ Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGSYS Abnormal Termination CONFIG_SIG_SIGKILL_ACTION
SIGUSR1 Abnormal Termination CONFIG_SIG_SIGUSR1_ACTION
SIGUSR2 Abnormal Termination CONFIG_SIG_SIGUSR2_ACTION
SIGPIPE Abnormal Termination CONFIG_SIG_SIGPIPE_ACTION
SIGALRM Abnormal Termination CONFIG_SIG_SIGALRM_ACTION
SIGVTALRM Abnormal Termination CONFIG_SIG_SIGALRM_ACTION
SIGPROF Abnormal Termination CONFIG_SIG_SIGPROF_ACTION
SIGPOLL Abnormal Termination CONFIG_SIG_SIGPOLL_ACTION
========== ==================== =========================
Job Control Signals
-------------------
========== ==================== =========================
Signal Action Additional Configuration
========== ==================== =========================
SIGSTOP Suspend Task CONFIG_SIG_SIGSTOP_ACTION
SIGTSTP Suspend Task CONFIG_SIG_SIGSTOP_ACTION
SIGTTIN Suspend Task CONFIG_SIG_SIGSTOP_ACTION
SIGTTOU Suspend Task CONFIG_SIG_SIGSTOP_ACTION
SIGCONT Resume Task CONFIG_SIG_SIGSTOP_ACTION
========== ==================== =========================
Ignored By Default
------------------
========== ==================== =========================
Signal Action Additional Configuration
========== ==================== =========================
SIGURG Ignore Signal CONFIG_SIG_SIGURG_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.
Reference in New Issue View Git Blame Copy Permalink