.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Sys::SigAction 3pm" .TH Sys::SigAction 3pm "2022-06-17" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Sys::SigAction \- Perl extension for Consistent Signal Handling .SH "SYNOPSYS" .IX Header "SYNOPSYS" .Vb 6 \& #do something non\-interrupt able \& use Sys::SigAction qw( set_sig_handler ); \& { \& my $h = set_sig_handler( \*(AqINT\*(Aq ,\*(Aqmysubname\*(Aq ,{ flags => SA_RESTART } ); \& ... do stuff non\-interrupt able \& } #signal handler is reset when $h goes out of scope .Ve .PP or .PP .Vb 10 \& #timeout a system call: \& use Sys::SigAction qw( set_sig_handler ); \& eval { \& my $h = set_sig_handler( \*(AqALRM\*(Aq ,\e&mysubname ,{ mask=>[ \*(AqALRM\*(Aq ] ,safe=>1 } ); \& eval { \& alarm(2) \& ... do something you want to timeout \& alarm(0); \& }; \& alarm(0); \& die $@ if $@; \& }; #signal handler is reset when $h goes out of scope \& if ( $@ ) ... .Ve .PP or .PP .Vb 10 \& use Sys::SigAction; \& my $alarm = 0; \& eval { \& my $h = Sys::SigAction::set_sig_handler( \*(AqALRM\*(Aq ,sub { $alarm = 1; } ); \& eval { \& alarm(2) \& ... do something you want to timeout \& alarm(0); \& }; \& alarm(0); \& die $@ if $@; \& }; #signal handler is reset when $h goes out of scope \& if ( $@ or $alarm ) ... .Ve .PP or .PP .Vb 4 \& use Sys::SigAction; \& my $alarm = 0; \& Sys::SigAction::set_sig_handler( \*(AqTERM\*(Aq ,sub { "DUMMY" } ); \& #code from here on uses new handler.... (old handler is forgotten) .Ve .PP or .PP .Vb 5 \& use Sys::SigAction qw( timeout_call ); \& if ( timeout_call( 5 ,sub { $retval = DoSomething( @args ); } ) \& { \& print "DoSomething() timed out\en" ; \& } .Ve .PP or .PP .Vb 6 \& #use a floating point (fractional seconds) in timeout_call \& use Sys::SigAction qw( timeout_call ); \& if ( timeout_call( 0.1 ,sub { $retval = DoSomething( @args ); } ) \& { \& print "DoSomething() timed out\en" ; \& } .Ve .SH "ABSTRACT" .IX Header "ABSTRACT" This module implements \f(CW\*(C`set_sig_handler()\*(C'\fR, which sets up a signal handler and (optionally) returns an object which causes the signal handler to be reset to the previous value, when it goes out of scope. .PP Also implemented is \f(CW\*(C`timeout_call()\*(C'\fR which takes a timeout value, a code reference and optional arguments, and executes the code reference wrapped with an alarm timeout. timeout_call accepts seconds in floating point format, so you can time out call with a resolution of 0.000001 seconds. If \f(CW\*(C`Time::HiRes\*(C'\fR is not loadable or \f(CW\*(C`Time::HiRes::ualarm()\*(C'\fR does not work, then the factional part of the time value passed to \f(CW\*(C`timeout_call()\*(C'\fR will be raise to the next higher integer with \fBPOSIX::ceil()\fR. This means that the shortest a timeout can be in 1 second. .PP Finally, two convenience routines are defined which allow one to get the signal name from the number \*(-- \f(CW\*(C`sig_name()\*(C'\fR, and get the signal number from the name \*(-- \f(CW\*(C`sig_number()\*(C'\fR. .SH "DESCRIPTION" .IX Header "DESCRIPTION" Prior to version 5.8.0 perl implemented 'unsafe' signal handling. The reason it is consider unsafe, is that there is a risk that a signal will arrive, and be handled while perl is changing internal data structures. This can result in all kinds of subtle and not so subtle problems. For this reason it has always been recommended that one do as little as possible in a signal handler, and only variables that already exist be manipulated. .PP Perl 5.8.0 and later versions implements 'safe' signal handling on platforms which support the \s-1POSIX\s0 \fBsigaction()\fR function. This is accomplished by having perl note that a signal has arrived, but deferring the execution of the signal handler until such time as it is safe to do so. Unfortunately these changes can break some existing scripts, if they depended on a system routine being interrupted by the signal's arrival. The perl 5.8.0 implementation was modified further in version 5.8.2. .PP From the perl 5.8.2 \fBperlvar\fR man page: .PP .Vb 3 \& The default delivery policy of signals changed in Perl 5.8.0 \& from immediate (also known as "unsafe") to deferred, also \& known as "safe signals". .Ve .PP The implementation of this changed the \f(CW\*(C`sa_flags\*(C'\fR with which the signal handler is installed by perl, and it causes some system routines (like \fBconnect()\fR) to return \s-1EINTR,\s0 instead of another error when the signal arrives. The problem comes when the code that made the system call sees the \s-1EINTR\s0 code and decides it's going to call it again before returning. Perl doesn't do this but some libraries do, including for instance, the Oracle \s-1OCI\s0 library. .PP Thus the 'deferred signal' approach (as implemented by default in perl 5.8 and later) results in some system calls being retried prior to the signal handler being called by perl. This breaks timeout logic for DBD-Oracle which works with earlier versions of perl. This can be particularly vexing, when, for instance, the host on which a database resides is not available: \f(CW\*(C`DBI\->connect()\*(C'\fR hangs for minutes before returning an error (and cannot even be interrupted with control-C, even when the intended timeout is only seconds). This is because \s-1SIGINT\s0 appears to be deferred as well. The result is that it is impossible to implement open timeouts with code that looks like this in perl 5.8.0 and later: .PP .Vb 10 \& eval { \& eval { \& local $SIG{ALRM} = sub { die "timeout" }; \& alarm 2; \& $sth = DBI\->connect(...); \& alarm 0; \& }; \& alarm 0; \& die if $@; \& }; .Ve .PP Or as the author of bug #50628 pointed out, might probably better be written as: .PP .Vb 10 \& eval { \& local $SIG{ALRM} = sub { die "timeout" }; \& eval { \& alarm 2; \& $sth = DBI\->connect(...); \& alarm 0; \& }; \& alarm 0; \& die if $@; \& }; .Ve .PP The solution, if your system has the \s-1POSIX\s0 \fBsigaction()\fR function, is to use perl's \f(CW\*(C`POSIX::sigaction()\*(C'\fR to install the signal handler. With \f(CW\*(C`sigaction()\*(C'\fR, one gets control over both the signal mask, and the \&\f(CW\*(C`sa_flags\*(C'\fR that are used to install the handler. Further, with perl 5.8.2 and later, a 'safe' switch is provided which can be used to ask for safe(r) signal handling. .PP Using \fBsigaction()\fR ensures that the system call won't be resumed after it's interrupted, so long as die is called within the signal handler. This is no longer the case when one uses \f(CW$SIG{name}\fR to set signal handlers in perls >= 5.8.0. .PP The usage of \fBsigaction()\fR is not well documented however, and in perl versions less than 5.8.0, it does not work at all. (But that's \s-1OK,\s0 because just setting \f(CW$SIG\fR does work in that case.) Using \fBsigaction()\fR requires approximately 4 or 5 lines of code where previously one only had to set a code reference into the \f(CW%SIG\fR hash. .PP Unfortunately, at least with perl 5.8.0, the result is that doing this effectively reverts to the 'unsafe' signals behavior. It is not clear whether this would be the case in perl 5.8.2, since the safe flag can be used to ask for safe signal handling. I suspect this separates the logic which uses the \f(CW\*(C`sa_flags\*(C'\fR to install the handler, and whether deferred signal handling is used. .PP The reader should also note, that the behavior of the 'safe' attribute is not consistent with what this author expected. Specifically, it appears to disable signal masking. This can be examined further in the t/safe.t and the t/mask.t regression tests. Never-the-less, Sys::SigAction provides an easy mechanism for the user to recover the pre\-5.8.0 behavior for signal handling, and the mask attribute clearly works. (see t/mask.t) If one is looking for specific safe signal handling behavior that is considered broken, and the breakage can be demonstrated, then a patch to t/safe.t would be most welcome. .PP This module wraps up the \s-1POSIX::\s0 routines and objects necessary to call \&\fBsigaction()\fR in a way that is as efficient from a coding perspective as just setting a localized \f(CW$SIG{SIGNAL}\fR with a code reference. Further, the user has control over the \f(CW\*(C`sa_flags\*(C'\fR passed to \fBsigaction()\fR. By default, if no additional args are passed to \fBsigaction()\fR, then the signal handler will be called when a signal (such as \s-1SIGALRM\s0) is delivered. .PP Since \fBsigaction()\fR is not fully functional in perl versions less than 5.8, this module implements equivalent behavior using the standard \&\f(CW%SIG\fR array. The version checking and implementation of the 'right' code is handled by this module, so the user does not have to write perl version dependent code. The attrs hashref argument to \fBset_sig_handler()\fR is silently ignored, in perl versions less than 5.8. When this module was developed it was tested on perl 5.005 on solaris. That was in 2004. Now only perl versions >= 5.6 are supported. If you want this to work on perl 5.5 you will have comment out \*(L"use warnings\*(R" everywhere. .PP It is hoped that with the use of this module, your signal handling behavior can be coded in a way that does not change from one perl version to the next, and that \fBsigaction()\fR will be easier for you to use. .ie n .SH "Note on ""Double evals""" .el .SH "Note on ``Double evals''" .IX Header "Note on Double evals" \&\s-1CPAN\s0 bug #50628 which was filed against Sys::SigAction\-0.11 noting that the sample code was \*(L"buggy\*(R" because the evals that wrapped the code we wanted to timeout might die for an unanticipated reason, before the alarm could be cleared. In that case, as the bug writer noted, if the alarm expires before the final \fBalarm\fR\|(0) can be called, either the code will completely die because there is no \s-1SIGALRM\s0 handler in place to catch the signal, or the wrong handler (not the local handler) will be called. .PP All the code samples in this module have been modified to account for this. Additionally we have made the same change in \fBtimeout_call()\fR which could have exhibited this behavior, though the \s-1AUTHOR\s0 never knowing experienced it. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "\fBset_sig_handler()\fP" .IX Subsection "set_sig_handler()" .Vb 1 \& $sig ,$handler ,$attrs .Ve .PP Install a new signal handler and (if not called in a void context) returning a Sys::SigAction object containing the old signal handler, which will be restored on object destruction. .PP .Vb 1 \& $sig is a signal name (without the \*(AqSIG\*(Aq) or number. \& \& $handler is either the name (string) of a signal handler \& function or a subroutine CODE reference. \& \& $attrs if defined is a hash reference containing the \& following keys: \& \& flags => the flags the passed sigaction \& \& ex: SA_RESTART (defined in your signal.h) \& \& mask => the array reference: signals you \& do not want delivered while the signal \& handler is executing \& \& ex: [ SIGINT SIGUSR1 ] or \& ex: [ qw( INT USR1 ] \& \& safe => A boolean value requesting \*(Aqsafe\*(Aq signal \& handling (only in 5.8.2 and greater) \& earlier versions will issue a warning if \& you use this \& \& NOTE: This breaks the signal masking .Ve .SS "\fBtimeout_call()\fP" .IX Subsection "timeout_call()" .Vb 1 \& $timeout, $coderef, @args .Ve .PP Given a code reference, and a timeout value (in seconds), \fBtimeout_call()\fR will (in an eval) setup a signal handler for \s-1SIGALRM\s0 (which will die), set an alarm clock, and execute the code reference with optional arguments \f(CW@args\fR. \f(CW$timeout\fR (seconds) may be expressed as a floating point number. .PP If Time::HiRes is present and useable, \fBtimeout_call()\fR can be used with a timer resolution of 0.000001 seconds. If HiRes is not loadable, Sys::SigAction will \*(L"do the right thing\*(R" and convert the factional seconds to the next higher integer value using the posix \fBceil()\fR function. .PP If the alarm goes off the code will be interrupted. The alarm is canceled if the code returns before the alarm is fired. The routine returns true if the code being executed timed out. (was interrupted). Exceptions thrown by the code executed are propagated out. .PP The original signal handler is restored, prior to returning to the caller. .SS "\fBsig_alarm()\fP" .IX Subsection "sig_alarm()" ex: .PP .Vb 1 \& sig_alarm( 1.2 ); .Ve .PP \&\fBsig_alarm()\fR is a drop in replacement for the standard \fBalarm()\fR function. The argument may be expressed as a floating point number. .PP If Time::HiRes is present and useable, the alarm timers will be set to the floating point value with a resolution of 0.000001 seconds. If Time::HiRes is not available then the a fractional value in the argument will be raised to the next higher integer value. .SS "\fBsig_name()\fP" .IX Subsection "sig_name()" Return the signal name (string) from a signal number. .PP ex: .PP .Vb 1 \& sig_name( SIGINT ) returns \*(AqINT\*(Aq .Ve .SS "\fBsig_number()\fP" .IX Subsection "sig_number()" Return the signal number (integer) from a signal name (minus the \s-1SIG\s0 part). .PP ex: .PP .Vb 1 \& sig_number( \*(AqINT\*(Aq ) returns the integer value of SIGINT; .Ve .SH "MULTITHREADED PERL" .IX Header "MULTITHREADED PERL" Sys::SigAction works just fine on perls built with multithread support in single threaded perl applications. However, please note that using Signals in a multi-thread perl application is unsupported. .PP Read the following from perldoc perlthrtut: .PP .Vb 6 \& ... mixing signals and threads may be problematic. \& Implementations are platform\-dependent, and even the POSIX semantics \& may not be what you expect (and Perl doesn\*(Aqt even give you the full \& POSIX API). For example, there is no way to guarantee that a signal \& sent to a multi\-threaded Perl application will get intercepted by \& any particular thread. .Ve .PP That said, perl documentation for perl threading discusses a a way of emulating signals in multi-threaded applications, when safe signals is in effect. See perldoc threads and search for \s-1THREAD SIGNALLING. I\s0 have no test of multithreading and this module. If you think they could be used compatibly and would provide value, patches are welcome. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 1 \& Lincoln A. Baxter .Ve .SH "COPYRIGHT" .IX Header "COPYRIGHT" .Vb 2 \& Copyright (c) 2004\-2016 Lincoln A. Baxter \& All rights reserved. \& \& You may distribute under the terms of either the GNU General Public \& License or the Artistic License, as specified in the Perl README file, .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 2 \& perldoc perlvar \& perldoc POSIX .Ve