SignalAction(), SignalAction_r()

QNX SDP8.0C Library ReferenceAPIDeveloper

Examine and/or specify actions for signals

Synopsis:

#include <sys/neutrino.h>

int SignalAction( pid_t pid,
                  void (*sigstub)(void),
                  int signo,
                  const struct sigaction *act,
                  struct sigaction *oact );

int SignalAction_r( pid_t pid,
                    void (*sigstub)(void),
                    int signo,
                    const struct sigaction *act,
                    struct sigaction *oact );

Arguments:

pid: A process ID, or 0 for the current process.
sigstub: Always pass &__signalstub.
signo: The signal whose action you want to set or get; see POSIX and QNX OS signals, below.
If the signal terminates a process, the cleanup of the terminated process occurs by default at the priority of the thread that sent the signal. If you OR the SIG_TERMER_NOINHERIT flag (defined in <signal.h>) into signo, the cleanup occurs at the priority of the thread that received the signal.
act: NULL, or a pointer to a sigaction structure that specifies the new action for the signal.
oact: NULL, or a pointer to a sigaction structure where the function can store the old action.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The SignalAction() and SignalAction_r() kernel calls allow the calling process examine or specify (or both) the action to be associated with a specific signal in the process pid. If pid is zero, the calling process is used. The argument signo specifies the signal.

Note:

You should call the POSIX sigaction() function or the ANSI signal() function instead of using these kernel calls directly.
A process can attach signal handlers only to itself. Only the kernel can query another process's signal actions.

These functions are identical except in the way they indicate errors. See the Returns section for details.

If act isn't NULL, then the specified signal is modified. If oact isn't NULL, the previous action is stored in the structure it points to. You can use various combinations of act and oact to query or set (or both) the action for a signal.

Signal handlers and actions are defined for the process and affect all threads in the process. For example, if one thread ignores a signal, then all threads ignore the signal.

You can target a signal at a thread, process or process group (see SignalKill()). When targeted at a process, at most one thread receives the signal. This thread must have the signal unblocked (see SignalProcmask()) to be a candidate for receiving it. All synchronously generated signals (e.g. SIGSEGV) are always delivered to the thread that caused them.

In a multithreaded process, if a signal terminates a thread, by default all threads and thus the process are terminated. You can override this standard POSIX behavior when you create the thread; see the PTHREAD_MULTISIG_ALLOW and PTHREAD_MULTISIG_DISALLOW flags in the entry for ThreadCreate().

Note:

The kernel saves and restores the FPU context on entering and leaving signal handlers, so it's safe to use floating-point operations in them.
If you use longjmp() to return from a signal handler, the signal remains masked. You can use siglongjmp() to restore the mask to the state saved by a previous call to sigsetjmp().

POSIX and QNX OS signals

The signals are defined in <signal.h>. The entire range of signals goes from _SIGMIN (1) to _SIGMAX (64):


Signal range	Description
1–40	40 POSIX regular signals (including traditional UNIX signals)
41–56	16 POSIX realtime signals (SIGRTMIN to SIGRTMAX)
57–64	Eight special-purpose QNX OS signals, some of which are named (e.g., SIGSELECT). They're always masked, and attempts to unmask them are ignored.

The following global variables are also declared in <signal.h>:

const char * const sys_siglist[]: An array of descriptions of the signals. You can use strsignal() to get the description of a signal.
const int sys_nsig: The number of entries in the sys_siglist array.

Note:

The sys_siglist array doesn't include the QNX OS signals, and strsignal() returns a pointer to an empty string for them.

The following table describes the POSIX signals, including the default action that the QNX OS performs to handle them. Here, default action means what happens if no handler for this specific signal is defined by the application writer, and the signal is not ignored or waited on with sigwaitinfo().


Signal	Description	Default action
SIGABRT	Abnormal termination, issued by functions such as abort()	Kill the process and write a dump file
SIGALRM	Alarm clock, issued by functions such as alarm()	Kill the process
SIGBUS	Bus error, or a memory parity error (a QNX OS-specific interpretation). If a second fault occurs while your process is in a signal handler for this fault, the process is terminated.	Kill the process and write a dump file
SIGCHLD or SIGCLD	A child process terminated	Ignore the signal, but still let the process's children become zombies
SIGCONT	Continue the process. You can't block this signal.	Make the process continue if it's STOPPED; otherwise ignore the signal
SIGDEADLK	A mutex deadlock occurred. QNX doesn't generate this signal, it's user-generated (i.e., generated by a user call to a function such as kill(), raise(), pthread_kill(), etc.). SIGDEADLK and SIGEMT refer to the same signal. Some utilities (e.g., gdb, ksh, slay, and kill) know about SIGEMT, but not SIGDEADLK.	Kill the process and write a dump file
SIGDOOM	Terminate the process due to insufficient resources (e.g., it's out of memory). This is similar to SIGKILL but you can ignore it.	Kill the process
SIGEMT	EMT instruction (emulation trap) SIGDEADLK and SIGEMT refer to the same signal. Some utilities (e.g., gdb, ksh, slay, and kill) know about SIGEMT, but not SIGDEADLK.	Kill the process and write a dump file
SIGFPE	Floating point exception	Kill the process and write a dump file
SIGHUP	Hangup; the session leader died, or the controlling terminal closed	Kill the process
SIGILL^a	Illegal hardware instruction. If a second fault occurs while your thread is in a signal handler for this fault, the process is terminated.	Kill the process and write a dump file
SIGINT	Interrupt; typically generated when you press CtrlC or CtrlBreak (you can change this with stty)	Kill the process
SIGIO	Asynchronous I/O	Kill the process
SIGIOT	I/O trap; a synonym for SIGABRT	Kill the process
SIGKILL	Kill. You can't block, ignore, or catch this signal.	Kill the process^b
SIGPIPE	Write on pipe with no reader	Kill the process
SIGPOLL	System V name for SIGIO	Kill the process
SIGPROF	Profiling timer expired. POSIX has marked this signal as obsolescent; QNX OS doesn't support profiling timers or send this signal.	Kill the process
SIGPWR	Power failure	Ignore the signal
SIGQUIT	Quit; typically generated when you press Ctrl\ (you can change this with stty)	Kill the process and write a dump file
SIGSEGV	Segmentation violation; an invalid memory reference was detected. If a second fault occurs while your process is in a signal handler for this fault, the process will be terminated.	Kill the process and write a dump file
SIGSTOP	Stop the process. You can't block, ignore, or catch this signal.	Stop the process^b
SIGSYS	Bad argument to system call	Kill the process and write a dump file
SIGTERM	Termination signal	Kill the process
SIGTRAP	Trace trap	Kill the process and write a dump file
SIGTSTP	Stop signal from tty; typically generated when you press CtrlZ (you can change this with stty)	Stop the process
SIGTTIN	Background read attempted from control terminal	Stop the process
SIGTTOU	Background write attempted to control terminal	Stop the process
SIGURG	Urgent condition on I/O channel	Ignore the signal
SIGUSR1	User-defined signal 1	Kill the process
SIGUSR2	User-defined signal 2	Kill the process
SIGVTALRM	Virtual timer expired. POSIX has marked this signal as obsolescent; QNX OS doesn't support virtual timers or send this signal.	Kill the process
SIGWINCH	The size of the terminal window changed	Ignore the signal
SIGXCPU	Soft CPU time limit exceeded see the RLIMIT_CPU resource for setrlimit())	Kill the process and write a dump file

Blocking states

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

SignalAction(): If an error occurs, -1 is returned and errno is set. Any other value returned indicates success.
SignalAction_r(): EOK is returned on success. This function does NOT set errno. If an error occurs, any value in the Errors section may be returned.

Errors:

EAGAIN: The system was unable to allocate a signal handler. This indicated critically low memory.
EFAULT: A fault occurred when the kernel tried to access the buffers provided.
EINVAL: The value of signo is less than 1 or greater than _SIGMAX, or you tried to set SIGKILL or SIGSTOP to something other than SIG_DFL.
EPERM: The pid didn't refer to the calling process.

Classification:

QNX OS


Safety:
Cancellation point	No
Signal handler	Yes
Thread	Yes

Page updated: August 09, 2024

^a One cause for a SIGILL signal is trying to perform an operation that requires I/O privileges. A thread can request these privileges by making sure the process has the PROCMGR_AID_IO ability enabled (see procmgr_ability()) and then calling ThreadCtl()) specifying the _NTO_TCTL_IO flag:

ThreadCtl( _NTO_TCTL_IO, 0 );

^b For signals that can't be ignored or caught, meaning application writers can't tell the OS to throw them away and can't define handlers for them or wait for them, they are always handled by the OS and, hence, the default action is always performed.