SignalAction(), SignalAction_r()

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

The address of a signal stub handler. This is a small piece of code in the user's space that interfaces the user's signal handler to the kernel. The library provides a standard one, __signalstub(). This argument can be NULL if act is also NULL.

signo

The signal whose action you want to set or get; see “POSIX and QNX Neutrino 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 sig, 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 let 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.

---

You should call the POSIX sigaction() function or the ANSI signal() function instead of using these kernel calls directly.

---

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().

---

It isn't safe to use floating-point operations in signal handlers. 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 Neutrino signals

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

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.

---

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

---

The POSIX and UNIX signals include:

^a One possible cause for a SIGILL signal is trying to perform an operation that requires I/O privileges. A thread can request these privileges by calling ThreadCtl(), specifying the _NTO_TCTL_IO flag:

ThreadCtl( _NTO_TCTL_IO, 0 );

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 process doesn't have permission to change the signal actions of the specified process.

ESRCH

The process indicated by pid doesn't exist.

Classification:

QNX Neutrino

See also:

abort(), ChannelCreate(), kill(), longjmp(), struct sigaction, siginfo_t, siglongjmp(), signal(), sigaction(), SignalKill(), SignalProcmask(), sigqueue(), sigsetjmp(), SyncMutexLock(), ThreadCreate(), wait(), waitpid()

“Process termination” in the “Processes” chapter of the QNX Neutrino Programmer's Guide