diff options
Diffstat (limited to 'devdocs/c/program%2Fsignal.html')
| -rw-r--r-- | devdocs/c/program%2Fsignal.html | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/devdocs/c/program%2Fsignal.html b/devdocs/c/program%2Fsignal.html new file mode 100644 index 00000000..4dfb42f4 --- /dev/null +++ b/devdocs/c/program%2Fsignal.html @@ -0,0 +1,78 @@ + <h1 id="firstHeading" class="firstHeading">signal</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><signal.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void (*signal( int sig, void (*handler) (int))) (int);</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Sets the error handler for signal <code>sig</code>. The signal handler can be set so that default handling will occur, signal is ignored, or a user-defined function is called.</p> +<p>When signal handler is set to a function and a signal occurs, it is implementation defined whether <code>signal<span class="br0">(</span>sig, <a href="http://en.cppreference.com/w/c/program/SIG_strategies"><span class="kw499">SIG_DFL</span></a><span class="br0">)</span></code> will be executed immediately before the start of signal handler. Also, the implementation can prevent some implementation-defined set of signals from occurring while the signal handler runs.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> sig </td> <td> - </td> <td> the signal to set the signal handler to. It can be an implementation-defined value or one of the following values: <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="sig_types" title="c/program/SIG types"> <span class="t-lines"><span>SIGABRT</span><span>SIGFPE</span><span>SIGILL</span><span>SIGINT</span><span>SIGSEGV</span><span>SIGTERM</span></span></a></div> </td> <td> defines signal types <br> <span class="t-mark">(macro constant)</span> </td> +</tr> </table> </td> +</tr> <tr class="t-par"> <td> handler </td> <td> - </td> <td> the signal handler. This must be one of the following: <ul> +<li> +<code><a href="sig_strategies" title="c/program/SIG strategies">SIG_DFL</a></code> macro. The signal handler is set to default signal handler. </li> +<li> +<code><a href="sig_strategies" title="c/program/SIG strategies">SIG_IGN</a></code> macro. The signal is ignored. </li> +<li>pointer to a function. The signature of the function must be equivalent to the following: </li> +</ul> <table class="t-dcl-begin"> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">void fun(int sig);</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p>Previous signal handler on success or <code><a href="sig_err" title="c/program/SIG ERR">SIG_ERR</a></code> on failure (setting a signal handler can be disabled on some implementations).</p> +<h3 id="Signal_handler"> Signal handler</h3> <p>The following limitations are imposed on the user-defined function that is installed as a signal handler.</p> +<p>If the user defined function returns when handling <code><a href="sig_types" title="c/program/SIG types">SIGFPE</a></code>, <code><a href="sig_types" title="c/program/SIG types">SIGILL</a></code> or <code><a href="sig_types" title="c/program/SIG types">SIGSEGV</a></code>, the behavior is undefined.</p> +<p>If the signal handler is called as a result of <code><a href="abort" title="c/program/abort">abort</a></code> or <code><a href="raise" title="c/program/raise">raise</a></code>, the behavior is undefined if the signal handler calls <code><a href="raise" title="c/program/raise">raise</a></code>.</p> +<p>If the signal handler is called NOT as a result of <code><a href="abort" title="c/program/abort">abort</a></code> or <code><a href="raise" title="c/program/raise">raise</a></code> (in other words, the signal handler is <i>asynchronous</i>), the behavior is undefined if</p> +<ul> +<li> the signal handler calls any function within the standard library, except </li> +<ul> +<li> <code><a href="abort" title="c/program/abort">abort</a></code> </li> +<li> <code><a href="_exit" title="c/program/ Exit">_Exit</a></code> </li> +<li> <code><a href="quick_exit" title="c/program/quick exit">quick_exit</a></code> </li> +<li> <code>signal</code> with the first argument being the number of the signal currently handled (async handler can re-register itself, but not other signals). </li> +<li> atomic functions from <a href="../thread#Atomic_operations" title="c/thread"><code><stdatomic.h></code></a> if the atomic arguments are lock-free </li> +<li> <code><a href="../atomic/atomic_is_lock_free" title="c/atomic/atomic is lock free">atomic_is_lock_free</a></code> (with any kind of atomic arguments) </li> +</ul> +<li> the signal handler refers to any object with static <span class="t-rev-inl t-since-c11"><span>or thread-local</span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> <a href="../language/storage_duration" title="c/language/storage duration">storage duration</a> <span class="t-rev-inl t-since-c11"><span>that is not a lock-free <a href="../language/atomic" title="c/language/atomic">atomic</a></span><span><span class="t-mark-rev t-since-c11">(since C11)</span></span></span> other than by assigning to a static <code><span class="kw4">volatile</span> <a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw498">sig_atomic_t</span></a></code>. </li> +</ul> <p>On entry to the signal handler, the state of the floating-point environment and the values of all objects is unspecified, except for</p> +<ul> +<li> objects of type <code><span class="kw4">volatile</span> <a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw498">sig_atomic_t</span></a></code> </li> +<li> objects of lock-free atomic types <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +<li> side effects made visible through <code><a href="../atomic/atomic_signal_fence" title="c/atomic/atomic signal fence">atomic_signal_fence</a></code> <span class="t-mark-rev t-since-c11">(since C11)</span> </li> +</ul> <p>On return from a signal handler, the value of any object modified by the signal handler that is not <code><span class="kw4">volatile</span> <a href="http://en.cppreference.com/w/c/program/sig_atomic_t"><span class="kw498">sig_atomic_t</span></a></code> or lock-free atomic<span class="t-mark-rev t-since-c11">(since C11)</span> is undefined.</p> +<p>The behavior is undefined if <code>signal</code> is used in a multithreaded program. It is not required to be thread-safe.</p> +<h3 id="Notes"> Notes</h3> <p>POSIX requires that <code>signal</code> is thread-safe, and <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_04">specifies a list of async-signal-safe library functions</a> that may be called from any signal handler.</p> +<p>Besides <code>abort</code> and <code>raise</code>, POSIX specifies that <code>kill</code>, <code>pthread_kill</code>, and <code>sigqueue</code> generate synchronous signals.</p> +<p>POSIX recommends <a rel="nofollow" class="external text" href="http://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html"><code>sigaction</code></a> instead of <code>signal</code>, due to its underspecified behavior and significant implementation variations, regarding signal delivery while a signal handler is executed.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <signal.h> +#include <stdio.h> + +volatile sig_atomic_t gSignalStatus; + +void signal_handler(int signal) +{ + gSignalStatus = signal; +} + +int main(void) +{ + signal(SIGINT, signal_handler); + + printf("SignalValue: %d\n", gSignalStatus); + printf("Sending signal: %d\n", SIGINT); + raise(SIGINT); + printf("SignalValue: %d\n", gSignalStatus); +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">SignalValue: 0 +Sending signal: 2 +SignalValue: 2</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.14.1.1 The signal function (p: 193-194) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.14.1.1 The signal function (p: 266-267) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.14.1.1 The signal function (p: 247-248) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.7.1.1 The signal function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="raise" title="c/program/raise"> <span class="t-lines"><span>raise</span></span></a></div> </td> <td> runs the signal handler for particular signal <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/utility/program/signal" title="cpp/utility/program/signal">C++ documentation</a></span> for <code>signal</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/program/signal" class="_attribution-link">https://en.cppreference.com/w/c/program/signal</a> + </p> +</div> |