=head1 NAME

Warnings and Errors Troubleshooting Index

=head1 Description

If you encounter an error or warning you don't understand, check this
chapter for solutions to common warnings and errors that the mod_perl
community has encountered in the last few years.

=head1 General Advice

Perl's warnings mode is immensely helpful in detecting possible
problems.  Make sure you always turn on warnings while you are
developing code.  See L<The Importance of
Warnings|guide::debug/The_Importance_of_Warnings>.

Enabling C<use diagnostics;> generally helps you to determine the
source of the problem and how to solve it.  See L<diagnostics
pragma|guide::debug/diagnostics_pragma> for more information.





=head1 Building and Installation




=head2 Bareword "gensym" not allowed while "strict subs"

When building mod_perl one may get the following failure:

  make[1]: Entering directory `.../mod_perl-1.29/Symbol'
  Running Mkbootstrap for Apache::Symbol ()
  ...
  Bareword "gensym" not allowed while "strict subs" in use at 
  /usr/lib/perl5/5.8.3/Pod/Parser.pm line 1158.
  ...
  make: *** [subdirs] Error 2

That happens when you you've modify C<@INC> to push C<"."> before all
other directories, whereas it should be last. When C<"."> is first in
C<@INC> it picks F<mod_perl-1.29/Symbol/Symbol.pm> when it's inside
the directory F<mod_perl-1.29/Symbol>. This shouldn't happen if your
system paths are coming first. To check your C<@INC>, run:

  % perl -V

and it'll appear at the end of the output. Usually C<"."> is pushed
first by setting a C<PERL5LIB> or a similar environment
variable. Unset it and repeat the build process to solve the problem.





=head2 C<No rule to make target ... CORE/config.h>

If while running C<'make'> you get a message:

  make: *** No rule to make target
  `/usr/lib/perl5/5.8.3/i386-linux/CORE/config.h',
  needed by `Makefile'.  Stop.

That means that your Perl installation is incomplete. Usually this is
the case on package based distros, where perl is split across multiple
packages.  Usually you need to install the Perl-devel package to be
able to build any other Perl modules that include XS extensions.






=head1 make test Issues

See L<make Troubleshooting|guide::install/make_Troubleshooting> and
L<make test Troubleshooting|guide::install/make_test_Troubleshooting>





=head1 Configuration and Startup

This section talks about errors reported when you attempt to start the
server.


=head2 'relocation errors' or 'undefined symbol'

Although the httpd executable was successfully built, you can still
have make failures. The output could include the following errors:

  relocation error:
  undefined symbol: PL_dowarn

This class of errors is often due to multiple installations of
Perl. Having F<libperl.so> in I</usr/lib/> is a great reason for lots
of obscure problems, when you have one more perl installed
elsewhere. That's why perl puts its F<libperl.so> under its private
tree (e.g., I</usr/lib/perl5/5.8.3/i686/CORE/>). But some
distributions decide to put it along with the rest of system
libraries, not expecting that users will have extra perl
installations.

To resolve the problem you need to check what perl library the
application finds. This is easy to check with the help of C<ldd(1)>.

If your mod_perl is statically linked with httpd, you need to check
the httpd executable whether it's linked against F<libperl.so>:

  % ldd /path/to/apache/bin/httpd

If the output includes F<libperl.so> check that the path is to the
version of Perl you've built mod_perl with. If your httpd executable
is reported to link against the wrong F<libperl.so> file, you've found
the cause of the problem. You should either ask your distributor to
not put the perl library into the global system libs directory, or use
some other solution to force the loading of the right library, which
is usually very platform specific. For example on Linux one can
preload a specific library path using the C<LD_PRELOAD> environment
variable. So if the wanted library is located at
I</usr/lib/perl5/5.8.3/i686/CORE/libperl.so> you can make httpd use it
with:

  % LD_PRELOAD=/usr/lib/perl5/5.8.3/i686/CORE/libperl.so httpd

for more information on Linux loader referer to the C<ld.so(8)>
C<ldconfig(8)> manpages.

If mod_perl is built as DSO, you will need to check the mod_perl
module (and not C<httpd>) with C<ldd>. Confusingly, mod_perl 1.0
module name is the same as of Perl: F<libperl.so>. If for example the
mod_perl module is located in I</path/to/apache/libexec/>, the command
would be:

  % ldd /path/to/apache/libexec/libperl.so

There could be another variation of the problem where a Perl used to
build mod_perl is statically linked and again, during the build time a
wrong static archive (e.g., F</usr/lib/libperl.a>) is picked by the
linker. If Perl is statically linked, running:

  % perl -V:useshrplib

will say:

    useshrplib='false'

Again, the solution may vary from system to system, but moving
F</usr/lib/libperl.a> away while building mod_perl is probably the
simplest.



=head2 SegFaults During Startup

Possible reasons and solutions:

=over

=item *

You have to build mod_perl with the same compiler as Perl was built
with. Otherwise you may see segmentation faults and other weird things
happen.

=item *

This could be the XSLoader vs. DynaLoader problem, where the list of
dl_handles created by XSLoader is wiped out by DynaLoader.  Try
adding:

  use DynaLoader (); 

to your I<startup.pl> before any other module is loaded.

This has been resolved in perl 5.8.0. For earlier versions of Perl you
need to comment out:

  #@dl_librefs         = ();       # things we have loaded
  #@dl_modules         = ();       # Modules we have loaded

in I<DynaLoader.pm>.

=back

However if none of this cases applies and you still experience
segmentation faults, please report the problem using the L<following
guidelines|guide::help/How_to_Report_Problems>.

=head2 libexec/libperl.so: open failed: No such file or directory

If when you run the server you get the following error:

  libexec/libperl.so: open failed: No such file or directory

it probably means that Perl was compiled with a shared
library.  mod_perl does detect this and links the Apache executable to
the Perl shared library (I<libperl.so>).

First of all make sure you have Perl installed on the machine, and
that you have I<libperl.so> in
I<E<lt>perlrootE<gt>/E<lt>versionE<gt>/E<lt>architectureE<gt>/CORE>. For
example in I</usr/local/lib/perl5/5.00503/sun4-solaris/CORE>.

Then make sure that directory is included in the environment
variable C<LD_LIBRARY_PRELOAD>.  Under normal circumstances, Apache
should have the path configured at compile time, but this way you can
override the library path.

=head2 install_driver(Oracle) failed: Can't load '.../DBD/Oracle/Oracle.so' for module DBD::Oracle

  install_driver(Oracle) failed: Can't load
  '/usr/lib/perl5/site_perl/5.005/i386-linux/auto/DBD/Oracle/Oracle.so' 
  for module DBD::Oracle:
  libclntsh.so.8.0: cannot open shared object file: 
  No such file or directory at
  /usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169. 
  at (eval 27) line 3
  Perhaps a required shared
  library or dll isn't installed where expected at 
  /usr/local/apache/perl/tmp.pl line 11

On BSD style filesystems C<LD_LIBRARY_PATH> is not searched for setuid
programs (a.k.a., Apache). This isn't a problem for CGI script since
they don't do a setuid (and are forked off), but Apache does, and
mod_perl is in Apache. Therefore the first solution is to explicitly
load the library from the system wide I<ldconfig> configuration file:

  # echo $ORACLE_HOME/lib >> /etc/ld.so.conf
  # ldconfig

Another solution to this problem is to modify the resulting
I<Makefile> ( after running C<perl Makefile.PL>) as follows:

1. search for the line C<LD_RUN_PATH=>

2. replace it with C<LD_RUN_PATH=(my_oracle_home)/lib>

(my_oracle_home) is, of course, the home path to your oracle
installation.  In particular, the file libclntsh.so.8.0 should exist
in that directory.  (If you use CPAN, the build directory for
DBD::Oracle should be in ~/.cpan/build/DBD-Oracle-1.06/ if you're
logged in as root.)

Then, just type C<make install>, and all should go well.

FYI, setting C<LD_RUN_PATH> has the effect of hard-coding the path to
I<(my_oracle_home)/lib> in the resulting C<Oracle.so> file generated
by the C<DBD::Oracle> so that at run-time, it doesn't have to go
searching through C<LD_LIBRARY_PATH> or the default directories used
by C<ld>.

For more information see the I<ld> manpage and an essay on
C<LD_LIBRARY_PATH>: http://www.visi.com/~barr/ldpath.html

=head2 Invalid command 'PerlHandler'...

  Syntax error on line 393 of /etc/httpd/conf/httpd.conf: Invalid
  command 'PerlHandler', perhaps mis-spelled or defined by a module
  not included in the server configuration [FAILED]

This can happen when you have a mod_perl enabled Apache compiled with 
DSO (generally it's an installed RPM or other binary package) but the
mod_perl module isn't loaded.  In this case you have to tell Apache 
to load mod_perl by adding:

  AddModule mod_perl.c

in your I<httpd.conf>.

This can also happen when you try to run a non-mod_perl Apache server 
using the configuration from a mod_perl server.

=head2 symbol __floatdisf: referenced symbol not found

This problem is experienced by users on certain Solaris versions. When
the server is built with modules that use the C<__floatdisf> symbol it
can't be started. e.g.:

  Cannot load /usr/local/apache/libexec/libproxy.so into server:
  ld.so.1: ../bin/httpd: fatal: relocation error: file
  /usr/local/apache/libexec/libproxy.so: symbol __floatdisf: referenced
  symbol not found

The missing symbol is in I<libgcc.a>.  Use

  % gcc -print-libgcc-file-name

to see where that file is. Once found you have to relink the module
with that file. You can also look for it in the gcc tree, e.g. under
I<gcc-3.2.1/gcc>.

First, configure and install Apache. Next, relink I<mod_proxy.so> or
I<mod_negotiation.so>, or whatever the module that reports the problem
with I<libgcc.a>.

  % cd apache_1.3.27/src/modules
  % ld -G -o mod_proxy.so mod_proxy.lo /pathto/libgcc.a

(adjust the I</pathto/> to point to the right file from the gcc output
stage.)

You can now verify with C<nm> that I<mod_proxy.so> includes that
symbol.




=head2 RegistryLoader: Translation of uri [...] to filename failed

  RegistryLoader: Translation of uri [/home/httpd/perl/test.pl] to filename 
          failed [tried: /home/httpd/docs/home/httpd/perl/test.pl]

This error shows up when C<Apache::RegistryLoader> fails to translate
the URI into the corresponding filesystem path. Most failures happen
when one passes a file path instead of URI. (A reminder:
I</home/httpd/perl/test.pl> is a file path, while I</perl/test.pl> is
a URI). In most cases all you have to do is to pass something that
C<Apache::RegistryLoader> expects to get - the URI, but there are more
complex cases. C<Apache::RegistryLoader>'s man page shows how to
handle these cases as well (look for the trans() sub).

=head2 "Apache.pm failed to load!"

If your server startup fails with:

  Apache.pm failed to load!

try adding this to I<httpd.conf>:

  PerlModule Apache










=head1 Code Parsing and Compilation

=head2 Value of $x will not stay shared at - line 5

L<my () Scoped Variable in Nested 
Subroutines|general::perl_reference::perl_reference/my___Scoped_Variable_in_Nested_Subroutines>.

=head2 Value of $x may be unavailable at - line 5.

L<my () Scoped Variable in Nested 
Subroutines|general::perl_reference::perl_reference/my___Scoped_Variable_in_Nested_Subroutines>.

=head2 Can't locate loadable object for module XXX

There is no object built for this module. e.g. when you see:

  Can't locate loadable object for module Apache::Util in @INC...

make sure to give mod_perl's C<Makefile.PL> C<PERL_UTIL_API=1>,
C<EVERYTHING=1> or C<DYNAMIC=1> parameters to enable and build all the
components of C<Apache::Util>.

=head2 Can't locate object method "get_handlers"...

  Can't locate object method "get_handlers" via package "Apache"

You need to rebuild your mod_perl with stacked handlers, i.e.
C<PERL_STACKED_HANDLERS=1> or more simply C<EVERYTHING=1>.

=head2 Missing right bracket at line ...

Most often you will find that you really do have a syntax error.
However the other reason might be that a script running under
C<Apache::Registry> is using C<__DATA__> or C<__END__> tokens. L<Learn
why|guide::porting/__END___and___DATA___tokens>.

=head2  Can't load '.../auto/DBI/DBI.so' for module DBI

Check that all your modules are compiled with the same Perl that is
compiled into mod_perl.  Perl 5.005 and 5.004 are not binary
compatible by default.

Other known causes of this problem:

OS distributions that ship with a broken binary Perl installation.

The `perl' program and `libperl.a' library are somehow built with
different binary compatibility flags.

The solution to these problems is to rebuild Perl and any extension
modules from a fresh source tree.  Tip for running Perl's Configure
script: use the `-des' flags to accepts defaults and `-D' flag to
override certain attributes:

  % ./Configure -des -Dcc=gcc ... && make test && make install

Read Perl's INSTALL document for more details.

Solaris OS specific:

"C<Can't load DBI>" or similar error for the IO module or whatever
dynamic module mod_perl tries to pull in first.  The solution is to
re-configure, re-build and re-install Perl and dynamic modules with
the following flags when Configure asks for "C<additional LD flags>":

  -Xlinker --export-dynamic

or

  -Xlinker -E

This problem is only known to be caused by installing gnu ld under Solaris.











=head1 Runtime





=head2 print() doesn't send anything on Mac OS X

On certain Mac OS X builds mod_perl doesn't seem to able to print()
anything to the client. That's because C<STDOUT> is not tied to the
C<Apache> module. Most likely some core module on Mac OS X
untie's/re-tie's C<STDOUT> after mod_perl had it tied. The workaround
is to add:

  PerlHeaderParserHandler "sub { tie *STDOUT, 'Apache' unless tied *STDOUT; }"

Another solution is not to use un unqualified C<print()>, but
C<$r-E<gt>print()>, for example replace:

  print "Hello";

with:

  $r->print("Hello");

If you don't have C<$r>, you can obtain it with:

  my $r = Apache->request;









=head2 "exit signal Segmentation fault (11)" with mysql

If you build mod_perl and mod_php in the same binary, you might get
Segmentation fault followed by this error:

  exit signal Segmentation fault (11)

The solution is to not rely on PHP's built-in MySQL support, and
instead build mod_php with your local MySQL support files by adding
C<--with-mysql=/path/to/mysql> during C<./configure>.

=head2 foo ... at /dev/null line 0

Under mod_perl you may receive a warning or an error in the
I<error_log> which specifies I</dev/null> as the source file, and line
0 as an line number where the printing of the message was triggered.
This is absolutely normal if the code is executed from within a
handler, because there is no actual file associated with the handler.
Therefore C<$0> is set to I</dev/null> and that's what you see.

=head2 Preventing mod_perl Processes From Going Wild

See the sections "L<Non-Scheduled Emergency Log
Rotation|general::control::control/Non_Scheduled_Emergency_Log_Rotation>" and "L<All RAM
Consumed|general::control::control/All_RAM_Consumed>"

=head2 Segfaults when using XML::Parser

If you have some of the processes segfault when using C<XML::Parser>
you should use

  --disable-rule=EXPAT

during the Apache configuration step.

Starting from mod_perl version 1.23 this option is disabled by default.

=head2 My CGI/Perl Code Gets Returned as Plain Text Instead of Being Executed by the Webserver

See L<My CGI/Perl Code Gets Returned as Plain Text Instead of Being
Executed by the Webserver|guide::config/My_CGI_Perl_Code_Gets_Returned_as_Plain_Text_Instead_of_Being_Executed_by_the_Webserver>.

=head2 Incorrect line number reporting in error/warn log messages

See L<Use of uninitialized value at (eval 80) line
12.|guide::troubleshooting/Use_of_uninitialized_value_at__eval_80__line_12_>

=head2 rwrite returned -1

This message happens when the client breaks the connection while your
script is trying to write to the client.  With Apache 1.3.x, you should
only see the rwrite messages if C<LogLevel> is set to C<debug>.

There was a bug that reported this debug message regardless of the
value of the C<LogLevel> directive.  It was fixed in mod_perl 1.19_01.

Generally C<LogLevel> is either C<debug> or C<info>.  C<debug> logs
everything, C<info> is the next level, which doesn't include debug
messages.  You shouldn't use "debug" mode on your production server.
At the moment there is no way to prevent users from aborting
connections.

=head2 Can't upgrade that kind of scalar ...

Fixed in mod_perl 1.23.

=head2 caught SIGPIPE in process

  [modperl] caught SIGPIPE in process 1234
  [modperl] process 1234 going to Apache::exit with status...

That's the C<$SIG{PIPE}> handler installed by mod_perl/C<Apache::SIG>,
which is called if a connection times out or if the client presses the
'Stop' button.  It gives you an opportunity to do cleanups if the
script was aborted in the middle of its execution.  See L<Handling the
'User pressed Stop button'
case|guide::debug/Handling_the__User_pressed_Stop_button__case> for more
info.

If your mod_perl version is earlier than 1.17 you might also get the 
message in the following section...

=head2 Client hit STOP or Netscape bit it!

  Client hit STOP or Netscape bit it!
  Process 2493 going to Apache::exit with status=-2

You may see this message in mod_perl versions less than 1.17.  See also
L<caught SIGPIPE in process|guide::troubleshooting/caught_SIGPIPE_in_process>.

=head2 Global symbol "$foo" requires explicit package name

The script below will print a warning like that above, moreover it will
print the whole script as a part of the warning message:

  #!/usr/bin/perl -w
  use strict;
  print "Content-type: text/html\n\n";
  print "Hello $undefined";

The warning:

  Global symbol "$undefined" requires 
  explicit package name at /usr/apps/foo/cgi/tmp.pl line 4.
          eval 'package Apache::ROOT::perl::tmp_2epl;
  use Apache qw(exit);sub handler {
  #line 1 /usr/apps/foo/cgi/tmp.pl
  BEGIN {$^W = 1;}#!/usr/bin/perl -w
  use strict;
  print "Content-type: text/html\\n\\n";
  print "Hello $undefined";
  
  
  }
  ;' called at 
  /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm 
  line 168
          Apache::Registry::compile('package
    Apache::ROOT::perl::tmp_2epl;use Apache qw(exit);sub han...') 
    called at 
        /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm 
        line 121
        Apache::Registry::handler('Apache=SCALAR(0x205026c0)') 
        called at /usr/apps/foo/cgi/tmp.pl line 4
          eval {...} called at /usr/apps/foo/cgi/tmp.pl line 4
  [Sun Nov 15 15:15:30 1998] [error] Undefined subroutine 
  &Apache::ROOT::perl::tmp_2epl::handler called at 
  /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm 
  line 135.
  
  [Sun Nov 15 15:15:30 1998] [error] Goto undefined subroutine 
  &Apache::Constants::SERVER_ERROR at 
  /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Constants.pm 
  line 23.

The error is simple to fix.  When you use the C<use strict;> pragma
(and you should...), Perl will insist that all variables are defined
before being used, so the error will not arise.

The bad thing is that sometimes the whole script (possibly, thousands
of lines) is printed to the I<error_log> file as code that the server
has tried to C<eval()>uate.

May be you have a C<$SIG{__DIE__}> handler installed
(C<Carp::confess()>?).  If so that's what's expected.

You might wish to try something more terse such as S<"local
$SIG{__WARN__} = \&Carp::cluck;"> The confess method is I<very>
verbose and will tell you more than you might wish to know including
full source.

=head2 Use of uninitialized value at (eval 80) line 12.

Your code includes some undefined variable that you have used as if it
was already defined and initialized.  For example:

  $param = $q->param('test');
  print $param;

vs.

  $param = $q->param('test') || '';
  print $param;

In the second case, C<$param> will always be I<defined>, either with
C<$q-E<gt>param('test')>'s return value or the default value (C<''>
empty string in our example).

Also read about L<Finding the Line Which Triggered the Error or
Warning|guide::debug/Finding_the_Line_Which_Triggered_the_Error_or_Warning>.

=head2 Undefined subroutine &Apache::ROOT::perl::test_2epl::some_function called at

See L<Names collisions with Modules and
libs|guide::porting/Name_collisions_with_Modules_and_libs>.

=head2 Callback called exit

I<Callback called exit> is just a generic message when some
unrecoverable error occurs inside Perl during C<perl_call_sv()> (which
mod_perl uses to invoke all handler subroutines.  Such problems seem
to occur far less with 5.005_03 than 5.004.

Sometimes you discover that your server is not responding and its
error_log has filled up the remaining space on the file system. When
you get to see the contents of the error_log -- it includes millions
of lines, like:

  Callback called exit at -e line 33, <HTML> chunk 1.

Why the looping?

Perl can get I<very> confused inside an infinite loop in your code.  
It doesn't necessarily mean that your code did call C<exit()>.  Perl's 
malloc went haywire and called C<croak()>, but no memory is left to 
properly report the error, so Perl is stuck in a loop writing that 
same message to stderr.

Perl 5.005+ plus is recommended for its improved malloc.c and other
features that improve mod_perl and are turned on by default.

See also L<Out of memory|/Out_of_memory_>





=head2 Out of memory!

If something goes really wrong with your code, Perl may die with an
"Out of memory!" message and/or "Callback called exit".  Common causes
of this are never-ending loops, deep recursion, or calling an
undefined subroutine.

If you are using perl 5.005 or later, and perl is compiled to use it's
own malloc rutines, you can trap out of memory errors by setting aside
an extra memory pool in the special variable C<$^M>.  By default perl
uses the operating system malloc for many popular systems, so unless
you build perl with 'usemymalloc=y' you probably wont be able to use
C<$^M>.  Run:

  % perl -V:usemymalloc

if your mod_perl was compiled against perl which uses internal
C<malloc()> the answer will be 'y'.

Here is an explanation of C<$^M> from the C<perlvar> manpage:

  By default, running out of memory is an untrap- pable, fatal
  error.  However, if suitably built, Perl can use the contents of
  $^M as an emergency memory pool after die()ing.  Suppose that
  your Perl were compiled with -DPERL_EMERGENCY_SBRK and used
  Perl's malloc.  Then

      $^M = 'a' x (1 << 16);

  would allocate a 64K buffer for use in an emer- gency.  See the
  INSTALL file in the Perl distribu- tion for information on how
  to enable this option.  To discourage casual use of this
  advanced feature, there is no English long name for this
  variable.

If your perl installation supports $^M and you add 'C<use
Apache::Debug level =E<gt> 4;>' to your Perl script, it will allocate
the C<$^M> emergency pool and the C<$SIG{__DIE__}> handler will call
C<Carp::confess>, giving you a stack trace which should reveal where
the problem is.  See the C<Apache::Resource> module for ways to
control httpd processes.

Note that Perl 5.005 and later have C<PERL_EMERGENCY_SBRK> turned on 
by default.

Another trick is to have a startup script initialize C<Carp::confess>,
like so:

  use Carp ();
  eval { Carp::confess("init") };

this way, when the real problem happens, C<Carp::confess> doesn't eat
memory in the emergency pool (C<$^M>).

Some other mod_perl users have reported that this works well for them:

  # Allocate 64K as an emergency memory pool for use in out of
  # memory situation
  $^M = 0x00 x 65536;

  # Little trick to initialize this routine here so that in the case
  # of OOM, compiling this routine doesn't eat memory from the
  # emergency memory pool $^M
  use CGI::Carp ();
  eval { CGI::Carp::confess('init') };

  # Importing CGI::Carp sets $main::SIG{__DIE__} = \&CGI::Carp::die;
  # Override that to additionally give a stack backtrace
  $main::SIG{__DIE__} = \&CGI::Carp::confess;

Discussion of C<$^M> has come up on PerlMonks, and there is
speculation that C<$^M> is a forgotten feature that's not well
supported.  See http://perlmonks.org/index.pl?node_id=287850 for more
information.





=head2 server reached MaxClients setting, consider raising the MaxClients setting

See L<Choosing MaxClients|guide::performance/Choosing_MaxClients>.

=head2 syntax error at /dev/null line 1, near "line arguments:"

  syntax error at /dev/null line 1, near "line arguments:"
  Execution of /dev/null aborted due to compilation errors.
  parse: Undefined error: 0

There is a chance that your C</dev/null> device is broken. Try:

  % echo > /dev/null

Alternatively you should try to remove this special file and recreate
it:

  # rm /dev/null
  # mknod /dev/null c 1 3
  # chmod a+rw /dev/null

=head2 Can't call method "register_cleanup" (CGI.pm)

  Can't call method "register_cleanup" on an
  undefined value at /usr/lib/perl5/5.00503/CGI.pm line 263.

caused by this code snippet in I<CGI.pm>:

  if ($MOD_PERL) {
    Apache->request->register_cleanup(\&CGI::_reset_globals);
    undef $NPH;
  }

One solution is to add to I<httpd.conf>:

  PerlPostReadRequestHandler 'sub { Apache->request(shift) }'

But even better, switch to C<Apache::Cookie>:

  use Apache;
  use Apache::Cookie;
  
  sub handler {
    my $r = shift;
    my $cookies = Apache::Cookie->new($r)->parse;
    my %bar = $cookies->{foo}->value;
  }

=head2 readdir() not working

If readdir() either fails with an exception, or in the list context it
returns the correct number of items but each item as an empty string,
you have a binary compatibility between mod_perl and Perl
problem. Most likely the two have been built against different
I<glibc> versions, which have incompatible C<struct dirent>.

To solve this problem rebuild mod_perl and Perl against the same
I<glibc> version or get new binary packages built against the same
I<glibc> version.














=head1 Shutdown and Restart

=head2 Evil things might happen when using PerlFreshRestart

C<PerlFreshRestart> affects the graceful restart process for non-DSO
mod_perl builds. If you have mod_perl enabled Apache built as DSO and
you restart it, the whole Perl interpreter is completely torn down
(perl_destruct())and restarted.  The value of C<PerlFreshRestart> is
irrelevant at this point.

Unfortunately, not all perl modules are robust enough to survive
reload.  For them this is an unusual situation.  C<PerlFreshRestart>
does not much more than:

  while (my ($k,$v) = each %INC) {
    delete $INC{$k};
    require $k;
  }

Besides that, it flushes the C<Apache::Registry> cache, and empties
any dynamic stacked handlers (e.g. C<PerlChildInitHandler>).

Some users, who had turned C<PerlFreshRestart> B<On>, reported having
segfaults, others have seen no problems starting the server, no errors
written to the logs, but no server running after a restart. Most of
the problems have gone away when it was turned C<Off>.

It doesn't mean that you shouldn't use it, if it works for you.  Just
beware of the dragons...


=head2 Constant subroutine XXX redefined

That's a mandatory warning inside Perl which happens only if you modify
your script and Apache::Registry reloads it.  Perl is warning you that
the subroutine(s) were redefined.  It is mostly harmless.  If you
don't like seeing these warnings, just C<kill -USR1> (graceful restart) 
Apache when you modify your scripts.

You aren't supposed to see these warnings if you don't modify the code
with perl 5.004_05 or 5.005+.and higher.  If you still experience a
problem with code within a CGI script, moving all the code into a
module (or a library) and require()ing it should solve the problem.

=head2 Can't undef active subroutine

  Can't undef active subroutine at
  /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm line 102.
  Called from package Apache::Registry, filename
  /usr/apps/lib/perl5/site_perl/5.005/aix/Apache/Registry.pm, line 102

This problem is caused when a client drops the connection while httpd
is in the middle of a write.  httpd times out, sending a SIGPIPE,
and Perl (in that child) is stuck in the middle of its eval context.
This is fixed by the Apache::SIG module which is called by
default.  This should not happen unless you have code that is messing
with B<$SIG{PIPE}>.  It's also triggered only when you've changed your
script on disk and mod_perl is trying to reload it.

=head2 [warn] child process 30388 did not exit, sending another SIGHUP

From mod_perl.pod: With Apache versions 1.3.0 and higher, mod_perl
will call the perl_destruct() Perl API function during the child exit
phase.  This will cause proper execution of C<END> blocks found during
server startup as well as invoking the C<DESTROY> method on global
objects which are still alive.  It is possible that this operation may
take a long time to finish, causing problems during a restart.  If
your code does not contain any C<END> blocks or C<DESTROY> methods
which need to be run during child server shutdown, this destruction
can be avoided by setting the C<PERL_DESTRUCT_LEVEL> environment
variable to C<-1>. Be aware that `your code' includes any modules you
use and I<they> may well have C<DESTROY> and C<END> blocks...

=head2 Processes Get Stuck on Graceful Restart

If you see a process stuck in "G" (Gracefully finishing) after a doing
a graceful restart (sending S<kill -SIGUSR1>) it means that the
process is hanging in perl_destruct() while trying to cleanup.  This
cleanup normally isn't a requirement, you can disable it by setting
the PERL_DESTRUCT_LEVEL environment variable to -1.  See the section
"L<Speeding up the Apache Termination and
Restart|general::control::control/Speeding_up_the_Apache_Termination_and_Restart>"
for more information.

=head2 httpd keeps on growing after each restart

See the I<HUP Signal> explanation at the section:
L<Server Stopping and Restarting|general::control::control/Server_Stopping_and_Restarting>

Also, be aware that C<E<lt>PerlE<gt>> sections can also cause leaks
during graceful restarts.  See the (sub)thread:
http://aspn.activestate.com/ASPN/Mail/Message/modperl/304620 (META: we
don't have code samples, so if you have such please let us know).












=head1 OS Specific Notes

=head2 RedHat Linux

=head3 RH 8 and 9 Locale Issues

RedHat 8 and 9 ship Perl with a locale setting that breaks perl. To
solve the problem either change the locale to en_US.ISO8859-1 or
simply remove the UTF8 part.

For more information refer to:
http://twiki.org/cgi-bin/view/Codev/UsingPerl58OnRedHat8
http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=87682


=head2 OpenBSD

=head3 Issues Caused by httpd being C<chroot>'ed

Since OpenBSD 3.2, the Apache C<httpd(8)> server has been
C<chroot(2)>ed by default.

A mod_perl enabled OpenBSD httpd will NOT work as is.  A proper
C<chroot(2)> environment must be setup for the default chrooted
behavior to work.  The C<-u> option to httpd disables the chroot
behavior, and returns the httpd to the expanded "unsecure" behavior.
See the OpenBSD C<httpd(8)> man page.

For more information see I<section 10.16 of the OpenBSD FAQ>.
I<http://www.openbsd.org/faq/faq10.html#httpdchroot>.

=head2 Win FU

=head3 Apache::DBI

C<Apache::DBI> causes the server to exit when it starts up, with:

  [Mon Oct 25 15:06:11 1999] file .\main\http_main.c, line 5890,
  assertion "start_mutex" failed

Solution: build mod_perl with C<PERL_STARTUP_DONE_CHECK> set
(e.g. insert

  #define PERL_STARTUP_DONE_CHECK 1

at the top of I<mod_perl.h> or add it to the defines in the MSVC++ and
similar applications' C<Options> dialog).

Apache loads all Apache modules twice, to make sure the server will
successfully restart when asked to.  This flag disables all
C<PerlRequire> and C<PerlModule> statements on the first load, so they
can succeed on the second load.  Without that flag, the second load
fails.

=head2 HP-UX

=head3 C<Apache::Status> Dumps Core Under HP-UX 10.20

HP-UX 10.20 may dump core when accessing I<perl-status?sig>.  This
issue is known to happen when perl's I<./Configure> doesn't detect
that C<SIGRTMAX> is defined, but not implemented on that platform.

One solution is to upgrade to a recent version of Perl (5.8.0?) that
properly detects the implementation of that signal.

Another solution is to modify I<Apache/Status.pm> to skip that broken
signal by replacing the line:

  sort keys %SIG),

with:

  sort grep { $_ ne 'RTMAX' } keys %SIG),











=head1 Problematic Perl Modules

Here is the list of Perl Modules that are known to have problems under
mod_perl 1.0 and possible workarounds, solutions.

=over 

=item C<IPC::Open*>

use C<IPC::Run> instead. It provides the same functionality as the
C<IPC::Open*> family and more... and it works fine with mod_perl.

=back






=head1 Maintainers

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

=over

=item *

Stas Bekman [http://stason.org/]

=back






=head1 Authors

=over

=item *

Stas Bekman [http://stason.org/]

=back

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


=cut