mingw/html/lib/sigtrap.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>sigtrap - Perl pragma to enable simple signal handling</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:" />
   8 </head>
   9
  10 <body style="background-color: white">
  11 <table border="0" width="100%" cellspacing="0" cellpadding="3">
  12 <tr><td class="block" style="background-color: #cccccc" valign="middle">
  13 <big><strong><span class="block">&nbsp;sigtrap - Perl pragma to enable simple signal handling</span></strong></big>
  14 </td></tr>
  15 </table>
  16
  17 <p><a name="__index__"></a></p>
  18 <!-- INDEX BEGIN -->
  19
  20 <ul>
  21
  22         <li><a href="#name">NAME</a></li>
  23         <li><a href="#synopsis">SYNOPSIS</a></li>
  24         <li><a href="#description">DESCRIPTION</a></li>
  25         <li><a href="#options">OPTIONS</a></li>
  26         <ul>
  27
  28                 <li><a href="#signal_handlers">SIGNAL HANDLERS</a></li>
  29                 <li><a href="#signal_lists">SIGNAL LISTS</a></li>
  30                 <li><a href="#other">OTHER</a></li>
  31         </ul>
  32
  33         <li><a href="#examples">EXAMPLES</a></li>
  34 </ul>
  35 <!-- INDEX END -->
  36
  37 <hr />
  38 <p>
  39 </p>
  40 <h1><a name="name">NAME</a></h1>
  41 <p>sigtrap - Perl pragma to enable simple signal handling</p>
  42 <p>
  43 </p>
  44 <hr />
  45 <h1><a name="synopsis">SYNOPSIS</a></h1>
  46 <pre>
  47     use sigtrap;
  48     use sigtrap qw(stack-trace old-interface-signals);  # equivalent
  49     use sigtrap qw(BUS SEGV PIPE ABRT);
  50     use sigtrap qw(die INT QUIT);
  51     use sigtrap qw(die normal-signals);
  52     use sigtrap qw(die untrapped normal-signals);
  53     use sigtrap qw(die untrapped normal-signals
  54                     stack-trace any error-signals);
  55     use sigtrap 'handler' =&gt; \&amp;my_handler, 'normal-signals';
  56     use sigtrap qw(handler my_handler normal-signals
  57                     stack-trace error-signals);</pre>
  58 <p>
  59 </p>
  60 <hr />
  61 <h1><a name="description">DESCRIPTION</a></h1>
  62 <p>The <strong>sigtrap</strong> pragma is a simple interface to installing signal
  63 handlers.  You can have it install one of two handlers supplied by
  64 <strong>sigtrap</strong> itself (one which provides a Perl stack trace and one which
  65 simply <a href="#item_die"><code>die()</code></a>s), or alternately you can supply your own handler for it
  66 to install.  It can be told only to install a handler for signals which
  67 are either untrapped or ignored.  It has a couple of lists of signals to
  68 trap, plus you can supply your own list of signals.</p>
  69 <p>The arguments passed to the <a href="file://C|\msysgit\mingw\html/pod/perlfunc.html#item_use"><code>use</code></a> statement which invokes <strong>sigtrap</strong>
  70 are processed in order.  When a signal name or the name of one of
  71 <strong>sigtrap</strong>'s signal lists is encountered a handler is immediately
  72 installed, when an option is encountered it affects subsequently
  73 installed handlers.</p>
  74 <p>
  75 </p>
  76 <hr />
  77 <h1><a name="options">OPTIONS</a></h1>
  78 <p>
  79 </p>
  80 <h2><a name="signal_handlers">SIGNAL HANDLERS</a></h2>
  81 <p>These options affect which handler will be used for subsequently
  82 installed signals.</p>
  83 <dl>
  84 <dt><strong><a name="item_stack_2dtrace"><strong>stack-trace</strong></a></strong>
  85
  86 <dd>
  87 <p>The handler used for subsequently installed signals outputs a Perl stack
  88 trace to STDERR and then tries to dump core.  This is the default signal
  89 handler.</p>
  90 </dd>
  91 </li>
  92 <dt><strong><a name="item_die"><strong>die</strong></a></strong>
  93
  94 <dd>
  95 <p>The handler used for subsequently installed signals calls <a href="#item_die"><code>die</code></a>
  96 (actually <code>croak</code>) with a message indicating which signal was caught.</p>
  97 </dd>
  98 </li>
  99 <dt><strong><a name="item_handler_your_2dhandler"><strong>handler</strong> <em>your-handler</em></a></strong>
 100
 101 <dd>
 102 <p><em>your-handler</em> will be used as the handler for subsequently installed
 103 signals.  <em>your-handler</em> can be any value which is valid as an
 104 assignment to an element of <a href="file://C|\msysgit\mingw\html/pod/perlvar.html#item__sig"><code>%SIG</code></a>.</p>
 105 </dd>
 106 </li>
 107 </dl>
 108 <p>
 109 </p>
 110 <h2><a name="signal_lists">SIGNAL LISTS</a></h2>
 111 <p><strong>sigtrap</strong> has a few built-in lists of signals to trap.  They are:</p>
 112 <dl>
 113 <dt><strong><a name="item_normal_2dsignals"><strong>normal-signals</strong></a></strong>
 114
 115 <dd>
 116 <p>These are the signals which a program might normally expect to encounter
 117 and which by default cause it to terminate.  They are HUP, INT, PIPE and
 118 TERM.</p>
 119 </dd>
 120 </li>
 121 <dt><strong><a name="item_error_2dsignals"><strong>error-signals</strong></a></strong>
 122
 123 <dd>
 124 <p>These signals usually indicate a serious problem with the Perl
 125 interpreter or with your script.  They are ABRT, BUS, EMT, FPE, ILL,
 126 QUIT, SEGV, SYS and TRAP.</p>
 127 </dd>
 128 </li>
 129 <dt><strong><a name="item_old_2dinterface_2dsignals"><strong>old-interface-signals</strong></a></strong>
 130
 131 <dd>
 132 <p>These are the signals which were trapped by default by the old
 133 <strong>sigtrap</strong> interface, they are ABRT, BUS, EMT, FPE, ILL, PIPE, QUIT,
 134 SEGV, SYS, TERM, and TRAP.  If no signals or signals lists are passed to
 135 <strong>sigtrap</strong>, this list is used.</p>
 136 </dd>
 137 </li>
 138 </dl>
 139 <p>For each of these three lists, the collection of signals set to be
 140 trapped is checked before trapping; if your architecture does not
 141 implement a particular signal, it will not be trapped but rather
 142 silently ignored.</p>
 143 <p>
 144 </p>
 145 <h2><a name="other">OTHER</a></h2>
 146 <dl>
 147 <dt><strong><a name="item_untrapped"><strong>untrapped</strong></a></strong>
 148
 149 <dd>
 150 <p>This token tells <strong>sigtrap</strong> to install handlers only for subsequently
 151 listed signals which aren't already trapped or ignored.</p>
 152 </dd>
 153 </li>
 154 <dt><strong><a name="item_any"><strong>any</strong></a></strong>
 155
 156 <dd>
 157 <p>This token tells <strong>sigtrap</strong> to install handlers for all subsequently
 158 listed signals.  This is the default behavior.</p>
 159 </dd>
 160 </li>
 161 <dt><strong><a name="item_signal"><em>signal</em></a></strong>
 162
 163 <dd>
 164 <p>Any argument which looks like a signal name (that is,
 165 <code>/^[A-Z][A-Z0-9]*$/</code>) indicates that <strong>sigtrap</strong> should install a
 166 handler for that name.</p>
 167 </dd>
 168 </li>
 169 <dt><strong><a name="item_number"><em>number</em></a></strong>
 170
 171 <dd>
 172 <p>Require that at least version <em>number</em> of <strong>sigtrap</strong> is being used.</p>
 173 </dd>
 174 </li>
 175 </dl>
 176 <p>
 177 </p>
 178 <hr />
 179 <h1><a name="examples">EXAMPLES</a></h1>
 180 <p>Provide a stack trace for the old-interface-signals:</p>
 181 <pre>
 182     use sigtrap;</pre>
 183 <p>Ditto:</p>
 184 <pre>
 185     use sigtrap qw(stack-trace old-interface-signals);</pre>
 186 <p>Provide a stack trace on the 4 listed signals only:</p>
 187 <pre>
 188     use sigtrap qw(BUS SEGV PIPE ABRT);</pre>
 189 <p>Die on INT or QUIT:</p>
 190 <pre>
 191     use sigtrap qw(die INT QUIT);</pre>
 192 <p>Die on HUP, INT, PIPE or TERM:</p>
 193 <pre>
 194     use sigtrap qw(die normal-signals);</pre>
 195 <p>Die on HUP, INT, PIPE or TERM, except don't change the behavior for
 196 signals which are already trapped or ignored:</p>
 197 <pre>
 198     use sigtrap qw(die untrapped normal-signals);</pre>
 199 <p>Die on receipt one of an of the <strong>normal-signals</strong> which is currently
 200 <strong>untrapped</strong>, provide a stack trace on receipt of <strong>any</strong> of the
 201 <strong>error-signals</strong>:</p>
 202 <pre>
 203     use sigtrap qw(die untrapped normal-signals
 204                     stack-trace any error-signals);</pre>
 205 <p>Install <code>my_handler()</code> as the handler for the <strong>normal-signals</strong>:</p>
 206 <pre>
 207     use sigtrap 'handler', \&amp;my_handler, 'normal-signals';</pre>
 208 <p>Install <code>my_handler()</code> as the handler for the normal-signals, provide a
 209 Perl stack trace on receipt of one of the error-signals:</p>
 210 <pre>
 211     use sigtrap qw(handler my_handler normal-signals
 212                     stack-trace error-signals);</pre>
 213 <table border="0" width="100%" cellspacing="0" cellpadding="3">
 214 <tr><td class="block" style="background-color: #cccccc" valign="middle">
 215 <big><strong><span class="block">&nbsp;sigtrap - Perl pragma to enable simple signal handling</span></strong></big>
 216 </td></tr>
 217 </table>
 218
 219 </body>
 220
 221 </html>