.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "Net::Server::SIG 3"
.TH Net::Server::SIG 3 2023-07-25 "perl v5.38.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
Net::Server::SIG \- adpf \- Safer signal handling
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 3
\&    use Net::Server::SIG qw(register_sig check_sigs);
\&    use IO::Select ();
\&    use POSIX qw(WNOHANG);
\&
\&    my $select = IO::Select\->new();
\&
\&    register_sig(PIPE => \*(AqIGNORE\*(Aq,
\&                 HUP  => \*(AqDEFAULT\*(Aq,
\&                 USR1 => sub { print "I got a SIG $_[0]\en"; },
\&                 USR2 => sub { print "I got a SIG $_[0]\en"; },
\&                 CHLD => sub { 1 while waitpid(\-1, WNOHANG) > 0; },
\&                 );
\&
\&    # add some handles to the select
\&    $select\->add(\e*STDIN);
\&
\&    # loop forever trying to stay alive
\&    while (1) {
\&
\&        # do a timeout to see if any signals got passed us
\&        # while we were processing another signal
\&        my @fh = $select\->can_read(10);
\&
\&        my $key;
\&        my $val;
\&
\&        # this is the handler for safe (fine under unsafe also)
\&        if (check_sigs()) {
\&          # or my @sigs = check_sigs();
\&          next unless @fh;
\&        }
\&
\&        my $handle = $fh[@fh];
\&
\&        # do something with the handle
\&
\&    }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Signals prior in Perl prior to 5.7 were unsafe.  Since then signals
have been implemented in a more safe algorithm.  Net::Server::SIG
provides backwards compatibility, while still working reliably with
newer releases.
.PP
Using a property of the \fBselect()\fR function, Net::Server::SIG attempts
to fix the unsafe problem.  If a process is blocking on \fBselect()\fR any
signal will short circuit the select.  Using this concept,
Net::Server::SIG does the least work possible (changing one bit from 0
to 1).  And depends upon the actual processing of the signals to take
place immediately after the select call via the "check_sigs"
function.  See the example shown above and also see the sigtest.pl
script located in the examples directory of this distribution.
.SH FUNCTIONS
.IX Header "FUNCTIONS"
.ie n .IP """register_sig($SIG => \e&code_ref)""" 4
.el .IP "\f(CWregister_sig($SIG => \e&code_ref)\fR" 4
.IX Item "register_sig($SIG => &code_ref)"
Takes key/value pairs where the key is the signal name, and the
argument is either a code ref, or the words 'DEFAULT' or 'IGNORE'.
The function register_sig must be used in conjunction with check_sigs,
and with a blocking \fBselect()\fR function call \-\- otherwise, you will
observe the registered signal mysteriously vanish.
.ie n .IP unregister_sig($SIG) 4
.el .IP \f(CWunregister_sig($SIG)\fR 4
.IX Item "unregister_sig($SIG)"
Takes the name of a signal as an argument.  Calls register_sig with a
this signal name and 'DEFAULT' as arguments (same as
register_sig(SIG,'DEFAULT')
.ie n .IP check_sigs() 4
.el .IP \f(CWcheck_sigs()\fR 4
.IX Item "check_sigs()"
Checks to see if any registered signals have occurred.  If so, it will
play the registered code ref for that signal.  Return value is array
containing any SIGNAL names that had occurred.
.ie n .IP sig_is_registered($SIG) 4
.el .IP \f(CWsig_is_registered($SIG)\fR 4
.IX Item "sig_is_registered($SIG)"
Takes a signal name and returns any registered code_ref for that signal.
.SH AUTHORS
.IX Header "AUTHORS"
Paul Seamons (paul@seamons.com)
.PP
Rob B Brown (rob@roobik.com) \- Provided a sounding board and feedback
in creating Net::Server::SIG and sigtest.pl.
.SH LICENSE
.IX Header "LICENSE"
.Vb 4
\&  This package may be distributed under the terms of either the
\&  GNU General Public License
\&    or the
\&  Perl Artistic License
\&
\&  All rights reserved.
.Ve