Qore implements safe signal handling on UNIX platforms (not available on native Microsoft Windows ports). Signals do not interrupt Qore threads, rather Qore uses a special signal handling thread with TID 0, dedicated to handling signals. The signal handling thread uses very few resources; it stays blocked (using no processor time and very little memory) until a signal with a Qore signal handler is raised; it then executes the handler and resumes waiting for signals.

Because Qore\textquotesingle{}s signal handling thread is not a normal thread, it does not affect num\+\_\+threads() and does not appear in the list returned by thread\+\_\+list().

Internally, Qore masks (blocks) all signals in every thread except the signal handling thread. In the signal handling thread, all signals are unmasked, except those with Qore-\/language handlers, then an internal call to {\ttfamily sigwait() (3)} is made to receive and process signals raised one at a time.

Qore-\/language signal handlers are installed by passing a signal constant and a \mbox{\hyperlink{expressions_closure}{closure}} or \mbox{\hyperlink{expressions_call_reference}{call reference}} to the code to execute when the signal is raised to the set\+\_\+signal\+\_\+handler() function. Signal handlers are removed by passing a signal constant to the remove\+\_\+signal\+\_\+handler() function.

When a signal has been raised and the signal handler is called, the signal number is passed as the sole argument to the signal handler code.

{\bfseries{Signal Handling Functions}}  \tabulinesep=1mm
\begin{longtabu}spread 0pt [c]{*{2}{|X[-1]}|}
\hline
{\bfseries{Function Name}} &{\bfseries{Description}}  \\\cline{1-2}
set\+\_\+signal\+\_\+handler() &Sets up a Qore signal handler using a signal number and a call reference.  \\\cline{1-2}
remove\+\_\+signal\+\_\+handler() &Removes a Qore signal handler using a signal number.  \\\cline{1-2}
\end{longtabu}


See \mbox{\hyperlink{group__signal__constants}{Signal Constants}} for a list of signal constants and \mbox{\hyperlink{group__signal__constants_gab42117fc78cb6af6c22136a392943a55}{Qore\+::\+Name\+To\+Signal}} and \mbox{\hyperlink{group__signal__constants_gab6a540f14b42b4b137c2fe1ad70fa0b6}{Qore\+::\+Signal\+To\+Name}} for two hash constants that can be used to map signal names to numbers and vice-\/versa. Note that signal constants are system-\/dependent; not all signals will be available in all systems; in case of doubt, see your system documentation for information on which signals are available.

The above functions are atomic, meaning that when they return to the caller, the signal handling thread has already acknowledged the changes.

It is not possible to set signal masks per thread; all signals are delivered to the signal handling thread. Signals not handled with a Qore signal handler are handled with their default action. It is not possible to catch {\ttfamily SIGPIPE}. {\ttfamily SIGPIPE} is always ignored in \mbox{\hyperlink{namespace_qore}{Qore}}.

Some issues to be aware of in signal handlers\+:
\begin{DoxyItemize}
\item Thread-\/local storage is not persistent in signal handlers; it is deleted after every signal handler is run.
\item A signal handler that does not terminate will block the execution of further signal handlers and will block signal handling changes (such as updating the signal mask), resulting in a Qore process that must be killed manually. Because all Qore signal handling code is executed serially in a single thread, Qore signal handlers should execute and return quickly to give time to execute other handlers.
\item Signal handlers may install or remove signal handlers using set\+\_\+signal\+\_\+handler() or remove\+\_\+signal\+\_\+handler(), however in this case, changes to signal handling are made after the signal handler returns.
\item Signal handlers cannot call fork(); any attempt to call fork() in a signal handler will result in an an exception.
\item fork() (called externally to a signal handler) is handled as follows\+: the signal handling thread is terminated, fork() is executed, all signals are masked in the primary thread in the new process, then the signal handling thread is resumed in the parent process only. The signal handler thread cannot be reliably started in the child process because pthread\+\_\+create() is not async-\/signal safe, therefore signal handling is disabled in the child process. No signals can be received or handled while the signal handling thread is terminated.
\item Unhandled exceptions in signal handlers will simply be displayed on \mbox{\hyperlink{group__io__constants_ga697e4968984d273562f14bfed155b4a8}{stderr}} as an unhandled exception and will have no other effect on Qore or Qore code (in particular, unhandled exceptions will not cause the signal handling thread to terminate).
\item If a signal handler executes the \mbox{\hyperlink{statements_thread_exit}{thread\+\_\+exit statement}}, execution of the signal handler will terminate immediately, but the signal handling thread will not be stopped. Execution of further signal handlers (including that for the same signal being handled when \mbox{\hyperlink{statements_thread_exit}{thread\+\_\+exit}} is executed) will not be affected.

\begin{DoxyRefDesc}{Bug}
\item[\mbox{\hyperlink{bug__bug000002}{Bug}}]it seems that \mbox{\hyperlink{group__signal__constants_gaa481ec3f81e7c5d8009706eedea394ff}{SIGWINCH}} and \mbox{\hyperlink{group__signal__constants_gaa64b81edb492442c84993c3e2d60999a}{SIGINFO}} cannot be handled on Darwin in Qore\textquotesingle{}s dedicated signal-\/handling thread; the signals are never delivered to Qore\textquotesingle{}s signal handling thread for some reason despite setting the internal signal masks appropriately. These signals can be handled normally in the main thread on Darwin (in other programs using traditional non-\/threading signal APIs), but do not work with Qore (on Darwin only when using the pthread\+\_\+sigmask() and a dedicated signal-\/handling thread), possibly due to a bug related to signal handling and threading on Darwin. \end{DoxyRefDesc}

\end{DoxyItemize}