home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _10e9d6feb1fd7d51e8ad688334221472 < prev    next >
Text File  |  2000-03-23  |  8KB  |  198 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>sigtrap - Perl pragma to enable simple signal handling</TITLE>
  5. <LINK REL="stylesheet" HREF="../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> sigtrap - Perl pragma to enable simple signal handling</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  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. <H1><A NAME="name">NAME</A></H1>
  40. <P>sigtrap - Perl pragma to enable simple signal handling</P>
  41. <P>
  42. <HR>
  43. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  44. <UL>
  45. <LI>Linux</LI>
  46. <LI>Solaris</LI>
  47. <LI>Windows</LI>
  48. </UL>
  49. <HR>
  50. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  51. <PRE>
  52.     use sigtrap;
  53.     use sigtrap qw(stack-trace old-interface-signals);  # equivalent
  54.     use sigtrap qw(BUS SEGV PIPE ABRT);
  55.     use sigtrap qw(die INT QUIT);
  56.     use sigtrap qw(die normal-signals);
  57.     use sigtrap qw(die untrapped normal-signals);
  58.     use sigtrap qw(die untrapped normal-signals
  59.                     stack-trace any error-signals);
  60.     use sigtrap 'handler' => \&my_handler, 'normal-signals';
  61.     use sigtrap qw(handler my_handler normal-signals
  62.                     stack-trace error-signals);</PRE>
  63. <P>
  64. <HR>
  65. <H1><A NAME="description">DESCRIPTION</A></H1>
  66. <P>The <STRONG>sigtrap</STRONG> pragma is a simple interface to installing signal
  67. handlers.  You can have it install one of two handlers supplied by
  68. <STRONG>sigtrap</STRONG> itself (one which provides a Perl stack trace and one which
  69. simply <A HREF="#item_die"><CODE>die()</CODE></A>s), or alternately you can supply your own handler for it
  70. to install.  It can be told only to install a handler for signals which
  71. are either untrapped or ignored.  It has a couple of lists of signals to
  72. trap, plus you can supply your own list of signals.</P>
  73. <P>The arguments passed to the <A HREF="../lib/Pod/perlfunc.html#item_use"><CODE>use</CODE></A> statement which invokes <STRONG>sigtrap</STRONG>
  74. are processed in order.  When a signal name or the name of one of
  75. <STRONG>sigtrap</STRONG>'s signal lists is encountered a handler is immediately
  76. installed, when an option is encountered it affects subsequently
  77. installed handlers.</P>
  78. <P>
  79. <HR>
  80. <H1><A NAME="options">OPTIONS</A></H1>
  81. <P>
  82. <H2><A NAME="signal handlers">SIGNAL HANDLERS</A></H2>
  83. <P>These options affect which handler will be used for subsequently
  84. installed signals.</P>
  85. <DL>
  86. <DT><STRONG><A NAME="item_stack%2Dtrace"><STRONG>stack-trace</STRONG></A></STRONG><BR>
  87. <DD>
  88. The handler used for subsequently installed signals outputs a Perl stack
  89. trace to STDERR and then tries to dump core.  This is the default signal
  90. handler.
  91. <P></P>
  92. <DT><STRONG><A NAME="item_die"><STRONG>die</STRONG></A></STRONG><BR>
  93. <DD>
  94. The handler used for subsequently installed signals calls <A HREF="#item_die"><CODE>die</CODE></A>
  95. (actually <CODE>croak</CODE>) with a message indicating which signal was caught.
  96. <P></P>
  97. <DT><STRONG><A NAME="item_handler_your%2Dhandler"><STRONG>handler</STRONG> <EM>your-handler</EM></A></STRONG><BR>
  98. <DD>
  99. <EM>your-handler</EM> will be used as the handler for subsequently installed
  100. signals.  <EM>your-handler</EM> can be any value which is valid as an
  101. assignment to an element of <CODE>%SIG</CODE>.
  102. <P></P></DL>
  103. <P>
  104. <H2><A NAME="signal lists">SIGNAL LISTS</A></H2>
  105. <P><STRONG>sigtrap</STRONG> has a few built-in lists of signals to trap.  They are:</P>
  106. <DL>
  107. <DT><STRONG><A NAME="item_normal%2Dsignals"><STRONG>normal-signals</STRONG></A></STRONG><BR>
  108. <DD>
  109. These are the signals which a program might normally expect to encounter
  110. and which by default cause it to terminate.  They are HUP, INT, PIPE and
  111. TERM.
  112. <P></P>
  113. <DT><STRONG><A NAME="item_error%2Dsignals"><STRONG>error-signals</STRONG></A></STRONG><BR>
  114. <DD>
  115. These signals usually indicate a serious problem with the Perl
  116. interpreter or with your script.  They are ABRT, BUS, EMT, FPE, ILL,
  117. QUIT, SEGV, SYS and TRAP.
  118. <P></P>
  119. <DT><STRONG><A NAME="item_old%2Dinterface%2Dsignals"><STRONG>old-interface-signals</STRONG></A></STRONG><BR>
  120. <DD>
  121. These are the signals which were trapped by default by the old
  122. <STRONG>sigtrap</STRONG> interface, they are ABRT, BUS, EMT, FPE, ILL, PIPE, QUIT,
  123. SEGV, SYS, TERM, and TRAP.  If no signals or signals lists are passed to
  124. <STRONG>sigtrap</STRONG>, this list is used.
  125. <P></P></DL>
  126. <P>For each of these three lists, the collection of signals set to be
  127. trapped is checked before trapping; if your architecture does not
  128. implement a particular signal, it will not be trapped but rather
  129. silently ignored.</P>
  130. <P>
  131. <H2><A NAME="other">OTHER</A></H2>
  132. <DL>
  133. <DT><STRONG><A NAME="item_untrapped"><STRONG>untrapped</STRONG></A></STRONG><BR>
  134. <DD>
  135. This token tells <STRONG>sigtrap</STRONG> to install handlers only for subsequently
  136. listed signals which aren't already trapped or ignored.
  137. <P></P>
  138. <DT><STRONG><A NAME="item_any"><STRONG>any</STRONG></A></STRONG><BR>
  139. <DD>
  140. This token tells <STRONG>sigtrap</STRONG> to install handlers for all subsequently
  141. listed signals.  This is the default behavior.
  142. <P></P>
  143. <DT><STRONG><A NAME="item_signal"><EM>signal</EM></A></STRONG><BR>
  144. <DD>
  145. Any argument which looks like a signal name (that is,
  146. <CODE>/^[A-Z][A-Z0-9]*$/</CODE>) indicates that <STRONG>sigtrap</STRONG> should install a
  147. handler for that name.
  148. <P></P>
  149. <DT><STRONG><A NAME="item_number"><EM>number</EM></A></STRONG><BR>
  150. <DD>
  151. Require that at least version <EM>number</EM> of <STRONG>sigtrap</STRONG> is being used.
  152. <P></P></DL>
  153. <P>
  154. <HR>
  155. <H1><A NAME="examples">EXAMPLES</A></H1>
  156. <P>Provide a stack trace for the old-interface-signals:</P>
  157. <PRE>
  158.     use sigtrap;</PRE>
  159. <P>Ditto:</P>
  160. <PRE>
  161.     use sigtrap qw(stack-trace old-interface-signals);</PRE>
  162. <P>Provide a stack trace on the 4 listed signals only:</P>
  163. <PRE>
  164.     use sigtrap qw(BUS SEGV PIPE ABRT);</PRE>
  165. <P>Die on INT or QUIT:</P>
  166. <PRE>
  167.     use sigtrap qw(die INT QUIT);</PRE>
  168. <P>Die on HUP, INT, PIPE or TERM:</P>
  169. <PRE>
  170.     use sigtrap qw(die normal-signals);</PRE>
  171. <P>Die on HUP, INT, PIPE or TERM, except don't change the behavior for
  172. signals which are already trapped or ignored:</P>
  173. <PRE>
  174.     use sigtrap qw(die untrapped normal-signals);</PRE>
  175. <P>Die on receipt one of an of the <STRONG>normal-signals</STRONG> which is currently
  176. <STRONG>untrapped</STRONG>, provide a stack trace on receipt of <STRONG>any</STRONG> of the
  177. <STRONG>error-signals</STRONG>:</P>
  178. <PRE>
  179.     use sigtrap qw(die untrapped normal-signals
  180.                     stack-trace any error-signals);</PRE>
  181. <P>Install <CODE>my_handler()</CODE> as the handler for the <STRONG>normal-signals</STRONG>:</P>
  182. <PRE>
  183.     use sigtrap 'handler', \&my_handler, 'normal-signals';</PRE>
  184. <P>Install <CODE>my_handler()</CODE> as the handler for the normal-signals, provide a
  185. Perl stack trace on receipt of one of the error-signals:</P>
  186. <PRE>
  187.     use sigtrap qw(handler my_handler normal-signals
  188.                     stack-trace error-signals);</PRE>
  189. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  190. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  191. <STRONG><P CLASS=block> sigtrap - Perl pragma to enable simple signal handling</P></STRONG>
  192. </TD></TR>
  193. </TABLE>
  194.  
  195. </BODY>
  196.  
  197. </HTML>
  198.