=head1 NAME

Apache::SIG - Override apache signal handlers with Perl's

=head1 Synopsis

  PerlFixupHandler Apache::SIG

=head1 Description

When a client drops a connection and apache is in the middle of a
write, a timeout will occur and httpd sends a C<SIGPIPE>.  When
apache's C<SIGPIPE> handler is used, Perl may be left in the middle of
it's eval context, causing bizarre errors during subsequent requests
are handled by that child.  When C<Apache::SIG> is used, it installs a
different C<SIGPIPE> handler which rewinds the context to make sure
Perl is back to normal state, preventing these bizarre errors.

If you would like to log when a request was cancelled by a C<SIGPIPE>
in your Apache I<access_log>, you can declare C<Apache::SIG> as a
handler (any C<Perl*Handler> will do, as long as it is run before
C<PerlHandler>, e.g. C<PerlFixupHandler>), and you must also define a
custom C<LogFormat> in your httpd.conf, like so:

  PerlFixupHandler Apache::SIG
  LogFormat "%h %l %u %t \"%r\" %s %b %{SIGPIPE}e"

If the server has noticed that the request was cancelled via a
C<SIGPIPE>, then the log line will end with C<1>, otherwise it will
just be a dash.

=head1 Caveats

The signal handler in this package uses the subprocess_env table of
the main request object to supply the C<SIGPIPE> "environment
variable" to the log handler. If you already use the key C<SIGPIPE> in
your C<subprocess_env> table, then you can redefine the key like this:

  $Apache::SIG::PipeKey = 'my_SIGPIPE';

and log it like this:

  LogFormat "%h %l %u %t \"%r\" %s %b %{my_SIGPIPE}e"

=head1 Maintainers

Maintainer is the person(s) you should contact with updates,
corrections and patches.

=over

=item * The L<documentation mailing list|maillist::docs-dev>

=back

=head1 Authors

=over

=item * Doug MacEachern

=item * Doug Bagley

=back

Only the major authors are listed above. For contributors see the
Changes file.

=head1 See Also

perlvar(1)

=cut