+=head2 Handling the SIGHUP Signal in Daemons
+
+A process that usually starts when the system boots and shuts down
+when the system is shut down is called a daemon (Disk And Execution
+MONitor). If a daemon process has a configuration file which is
+modified after the process has been started, there should be a way to
+tell that process to reread its configuration file without stopping
+the process. Many daemons provide this mechanism using a C<SIGHUP>
+signal handler. When you want to tell the daemon to reread the file,
+simply send it the C<SIGHUP> signal.
+
+The following example implements a simple daemon, which restarts
+itself every time the C<SIGHUP> signal is received. The actual code is
+located in the subroutine C<code()>, which just prints some debugging
+info to show that it works; it should be replaced with the real code.
+
+ #!/usr/bin/perl -w
+
+ use POSIX ();
+ use FindBin ();
+ use File::Basename ();
+ use File::Spec::Functions;
+
+ $| = 1;
+
+ # make the daemon cross-platform, so exec always calls the script
+ # itself with the right path, no matter how the script was invoked.
+ my $script = File::Basename::basename($0);
+ my $SELF = catfile($FindBin::Bin, $script);
+
+ # POSIX unmasks the sigprocmask properly
+ $SIG{HUP} = sub {
+ print "got SIGHUP\n";
+ exec($SELF, @ARGV) || die "$0: couldn't restart: $!";
+ };
+
+ code();
+
+ sub code {
+ print "PID: $$\n";
+ print "ARGV: @ARGV\n";
+ my $count = 0;
+ while (++$count) {
+ sleep 2;
+ print "$count\n";
+ }
+ }
+
+
+=head2 Deferred Signals (Safe Signals)
+
+Before Perl 5.8.0, installing Perl code to deal with signals exposed you to
+danger from two things. First, few system library functions are
+re-entrant. If the signal interrupts while Perl is executing one function
+(like malloc(3) or printf(3)), and your signal handler then calls the same
+function again, you could get unpredictable behavior--often, a core dump.
+Second, Perl isn't itself re-entrant at the lowest levels. If the signal
+interrupts Perl while Perl is changing its own internal data structures,
+similarly unpredictable behavior may result.
+
+There were two things you could do, knowing this: be paranoid or be
+pragmatic. The paranoid approach was to do as little as possible in your
+signal handler. Set an existing integer variable that already has a
+value, and return. This doesn't help you if you're in a slow system call,
+which will just restart. That means you have to C<die> to longjmp(3) out
+of the handler. Even this is a little cavalier for the true paranoiac,
+who avoids C<die> in a handler because the system I<is> out to get you.
+The pragmatic approach was to say "I know the risks, but prefer the
+convenience", and to do anything you wanted in your signal handler,
+and be prepared to clean up core dumps now and again.
+
+Perl 5.8.0 and later avoid these problems by "deferring" signals. That is,
+when the signal is delivered to the process by the system (to the C code
+that implements Perl) a flag is set, and the handler returns immediately.
+Then at strategic "safe" points in the Perl interpreter (e.g. when it is
+about to execute a new opcode) the flags are checked and the Perl level
+handler from %SIG is executed. The "deferred" scheme allows much more
+flexibility in the coding of signal handlers as we know the Perl
+interpreter is in a safe state, and that we are not in a system library
+function when the handler is called. However the implementation does
+differ from previous Perls in the following ways:
+
+=over 4
+
+=item Long-running opcodes
+
+As the Perl interpreter looks at signal flags only when it is about
+to execute a new opcode, a signal that arrives during a long-running
+opcode (e.g. a regular expression operation on a very large string) will
+not be seen until the current opcode completes.
+
+If a signal of any given type fires multiple times during an opcode
+(such as from a fine-grained timer), the handler for that signal will
+be called only once, after the opcode completes; all other
+instances will be discarded. Furthermore, if your system's signal queue
+gets flooded to the point that there are signals that have been raised
+but not yet caught (and thus not deferred) at the time an opcode
+completes, those signals may well be caught and deferred during
+subsequent opcodes, with sometimes surprising results. For example, you
+may see alarms delivered even after calling C<alarm(0)> as the latter
+stops the raising of alarms but does not cancel the delivery of alarms
+raised but not yet caught. Do not depend on the behaviors described in
+this paragraph as they are side effects of the current implementation and
+may change in future versions of Perl.
+
+=item Interrupting IO
+
+When a signal is delivered (e.g., SIGINT from a control-C) the operating
+system breaks into IO operations like I<read>(2), which is used to
+implement Perl's readline() function, the C<< <> >> operator. On older
+Perls the handler was called immediately (and as C<read> is not "unsafe",
+this worked well). With the "deferred" scheme the handler is I<not> called
+immediately, and if Perl is using the system's C<stdio> library that
+library may restart the C<read> without returning to Perl to give it a
+chance to call the %SIG handler. If this happens on your system the
+solution is to use the C<:perlio> layer to do IO--at least on those handles
+that you want to be able to break into with signals. (The C<:perlio> layer
+checks the signal flags and calls %SIG handlers before resuming IO
+operation.)
+
+The default in Perl 5.8.0 and later is to automatically use
+the C<:perlio> layer.
+
+Note that it is not advisable to access a file handle within a signal
+handler where that signal has interrupted an I/O operation on that same
+handle. While perl will at least try hard not to crash, there are no
+guarantees of data integrity; for example, some data might get dropped or
+written twice.
+
+Some networking library functions like gethostbyname() are known to have
+their own implementations of timeouts which may conflict with your
+timeouts. If you have problems with such functions, try using the POSIX
+sigaction() function, which bypasses Perl safe signals. Be warned that
+this does subject you to possible memory corruption, as described above.
+
+Instead of setting C<$SIG{ALRM}>:
+
+ local $SIG{ALRM} = sub { die "alarm" };
+
+try something like the following:
+
+ use POSIX qw(SIGALRM);
+ POSIX::sigaction(SIGALRM, POSIX::SigAction->new(sub { die "alarm" }))
+ || die "Error setting SIGALRM handler: $!\n";
+
+Another way to disable the safe signal behavior locally is to use
+the C<Perl::Unsafe::Signals> module from CPAN, which affects
+all signals.
+
+=item Restartable system calls
+
+On systems that supported it, older versions of Perl used the
+SA_RESTART flag when installing %SIG handlers. This meant that
+restartable system calls would continue rather than returning when
+a signal arrived. In order to deliver deferred signals promptly,
+Perl 5.8.0 and later do I<not> use SA_RESTART. Consequently,
+restartable system calls can fail (with $! set to C<EINTR>) in places
+where they previously would have succeeded.
+
+The default C<:perlio> layer retries C<read>, C<write>
+and C<close> as described above; interrupted C<wait> and
+C<waitpid> calls will always be retried.
+
+=item Signals as "faults"
+
+Certain signals like SEGV, ILL, and BUS are generated by virtual memory
+addressing errors and similar "faults". These are normally fatal: there is
+little a Perl-level handler can do with them. So Perl delivers them
+immediately rather than attempting to defer them.
+
+=item Signals triggered by operating system state
+
+On some operating systems certain signal handlers are supposed to "do
+something" before returning. One example can be CHLD or CLD, which
+indicates a child process has completed. On some operating systems the
+signal handler is expected to C<wait> for the completed child
+process. On such systems the deferred signal scheme will not work for
+those signals: it does not do the C<wait>. Again the failure will
+look like a loop as the operating system will reissue the signal because
+there are completed child processes that have not yet been C<wait>ed for.
+
+=back
+
+If you want the old signal behavior back despite possible
+memory corruption, set the environment variable C<PERL_SIGNALS> to
+C<"unsafe">. This feature first appeared in Perl 5.8.1.
+