.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Server::SIG 3"
.TH Net::Server::SIG 3 "2007-02-02" "perl v5.8.8" "User Contributed Perl Documentation"
.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);
.Ve
.PP
.Vb 1
\&  my $select = IO::Select->new();
.Ve
.PP
.Vb 6
\&  register_sig(PIPE => 'IGNORE',
\&               HUP  => 'DEFAULT',
\&               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); },
\&               );
.Ve
.PP
.Vb 2
\&  ### add some handles to the select
\&  $select->add(\e*STDIN);
.Ve
.PP
.Vb 2
\&  ### loop forever trying to stay alive
\&  while ( 1 ){
.Ve
.PP
.Vb 3
\&    ### do a timeout to see if any signals got passed us
\&    ### while we were processing another signal
\&    my @fh = $select->can_read(10);
.Ve
.PP
.Vb 2
\&    my $key;
\&    my $val;
.Ve
.PP
.Vb 5
\&    ### this is the handler for safe (fine under unsafe also)
\&    if( &check_sigs() ){
\&      # or my @sigs = &check_sigs();
\&      next unless @fh;
\&    }
.Ve
.PP
.Vb 1
\&    my $handle = $fh[@fh];
.Ve
.PP
.Vb 1
\&    ### do something with the handle
.Ve
.PP
.Vb 1
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Signals in Perl 5 are unsafe.  Some future releases may be
able to fix some of this (ie Perl 5.8 or 6.0), but it would
be nice to have some safe, portable signal handling now.
Clarification \- much of the time, signals are safe enough.
However, if the program employs forking or becomes a daemon
which can receive many simultaneous signals, then the 
signal handling of Perl is normally not sufficient for the
task.
.PP
Using a property of the \fIselect()\fR function, Net::Server::SIG
attempts to fix the unsafe problem.  If a process is blocking on
\&\fIselect()\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 the select
call via the \*(L"check_sigs\*(R" 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 '\s-1DEFAULT\s0' or
\&'\s-1IGNORE\s0'.  The function register_sig must be used in
conjuction with check_sigs, and with a blocking \fIselect()\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 '\s-1DEFAULT\s0' as arguments (same as
register_sig(\s-1SIG\s0,'\s-1DEFAULT\s0')
.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 occured.  If so, it
will play the registered code ref for that signal.  Return value
is array containing any \s-1SIGNAL\s0 names that had occured.
.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
.Ve
.PP
.Vb 1
\&  All rights reserved.
.Ve