.\" 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 "mod_perl_traps 3"
.TH mod_perl_traps 3 "2007-03-30" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
mod_perl_traps \- common/known mod_perl traps
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
In the \s-1CGI\s0 environment, the server starts a single external process
(Perl interpreter) per \s-1HTTP\s0 request which runs single script in that
process space. When the request is over, the process goes away
everything is cleaned up and a fresh script is started for the next
request. mod_perl brings Perl inside of the \s-1HTTP\s0 server not only for
speedup of \s-1CGI\s0 scripts, but also for access to server functionality
that \s-1CGI\s0 scripts do not and/or cannot have. Now that we're inside the
server, each process will likely handle more than one Perl script and
keep it \*(L"compiled\*(R" in memory for longer than a single \s-1HTTP\s0 request.
This new location and longer lifetime of Perl execution brings with it
some common traps. This document is here to tell you what they are
and how to prevent them. The descriptions here are short, please
consult the mod_perl \s-1FAQ\s0 for more detail. If you trip over something
not documented here, please send a message to the mod_perl list.
.Sh "Migrating from \s-1CGI\s0"
.IX Subsection "Migrating from CGI"
.IP "\(bu" 4
Be sure to have read cgi_to_mod_perl
.IP "\(bu" 4
Scripts under Apache::Registry are not run in package \fBmain\fR, they
are run in a unique namespace based on the requested uri.
.IP "\(bu" 4
Apache::Registry scripts cannot contain _\|_END_\|_ or _\|_DATA_\|_ tokens
.IP "\(bu" 4
Output of \f(CW\*(C`system\*(C'\fR, \f(CW\*(C`exec\*(C'\fR and \f(CW\*(C`open PIPE, "|program"\*(C'\fR calls will
not be sent to the browser unless you Perl was configured with sfio.
.IP "\(bu" 4
Perl's \fIexit()\fR built-in function cannot be used in mod_perl scripts.
The \fIApache::exit()\fR function should be used instead. \fIApache::exit()\fR
automatically overrides the built-in \fIexit()\fR for Apache::Registry
and Apache::PerlRun scripts.
.IP "\(bu" 4
Your script *will not* run from the command line if your script makes
any direct calls to Apache\->methods. See Apache::FakeRequest.
.Sh "Apache::Registry"
.IX Subsection "Apache::Registry"
.IP "undefined subroutine &Apache::Registry::handler" 4
.IX Item "undefined subroutine &Apache::Registry::handler"
Interaction with certain modules causes the shortcut configuration to
break, if you see this message change your configuration from this:
.Sp
.Vb 4
\&
\& PerlHandler Apache::Registry
\& ...
\&
.Ve
.Sp
To this:
.Sp
.Vb 5
\& PerlModule Apache::Registry
\&
\& PerlHandler Apache::Registry::handler
\& ...
\&
.Ve
.Sh "Using \s-1CGI\s0.pm and CGI::*"
.IX Subsection "Using CGI.pm and CGI::*"
.IP "\(bu" 4
\&\s-1CGI\s0.pm users \fBmust\fR have version \fB2.39\fR of the package or higher,
earlier versions will not work under mod_perl.
.IP "\(bu" 4
If you use the \f(CW\*(C`SendHeaders()\*(C'\fR function, be sure to call
\&\f(CW$req_obj\fR\->cgi\->done when you are done with a request, just as you
would under \fICGI::MiniSrv\fR.
.Sh "Perl Modules and Extensions"
.IX Subsection "Perl Modules and Extensions"
.IP "\(bu" 4
Files pulled in via \f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR statements are not
automatically reloaded when changed on disk. See the Apache::StatINC
or the Apache::Reload module to add this functionality.
.IP "Undefined subroutines" 4
.IX Item "Undefined subroutines"
A common trap with required files may result in an error message
similar to this in the error_log:
.Sp
.Vb 3
\& [Thu Sep 11 11:03:06 1997] Undefined subroutine
\& &Apache::ROOT::perl::test_2epl::some_function called at
\& /opt/www/apache/perl/test.pl line 79.
.Ve
.Sp
As the above items explains, a file pulled in via \f(CW\*(C`require\*(C'\fR will only
happen once per-process (unless \f(CW%INC\fR is modified). If the file does
not contain a \f(CW\*(C`package\*(C'\fR declaration, the file's subroutines and
variables will be created in the current package. Under \s-1CGI\s0, this is
commonly package \f(CW\*(C`main\*(C'\fR. However, \fBApache::Registry\fR scripts are
compiled into a unique package name (base on the uri). So, if
multiple scripts in the same process try to require the same file,
which does not declare a package, only one script will actually be
able to see the subroutines. The solution is to read perlmodlib,
perlmod and related perl documentation and re-work your required
file into a module which exports functions or defines a method
interface.
Or something more simple, along these lines:
.Sp
.Vb 2
\& #required_file.pl
\& package Test;
.Ve
.Sp
.Vb 1
\& sub some_function {...}
.Ve
.Sp
.Vb 1
\& ...
.Ve
.Sp
.Vb 1
\& __END__
.Ve
.Sp
Now, have your scripts say:
.Sp
.Vb 1
\& require "required_file.pl";
.Ve
.Sp
.Vb 1
\& Test::some_function();
.Ve
.IP "Undefined subroutine &Foo::Bar::handler called at PerlHandler subroutine `Foo::Bar' line 1." 4
.IX Item "Undefined subroutine &Foo::Bar::handler called at PerlHandler subroutine `Foo::Bar' line 1."
You mistyped the module name in the 'package' line in your module.
.ie n .IP """Use of uninitialized value""" 4
.el .IP "``Use of uninitialized value''" 4
.IX Item "Use of uninitialized value"
Because of eval context, you may see warnings with useless
filename/line, example:
.Sp
.Vb 3
\& Use of uninitialized value at (eval 80) line 12.
\& Use of uninitialized value at (eval 80) line 43.
\& Use of uninitialized value at (eval 80) line 44.
.Ve
.Sp
To track down where this eval is really happening, try using a
\&\fB_\|_WARN_\|_\fR handler to give you a stack trace:
.Sp
.Vb 2
\& use Carp ();
\& local $SIG{__WARN__} = \e&Carp::cluck;
.Ve
.ie n .IP """Callback called exit""" 4
.el .IP "``Callback called exit''" 4
.IX Item "Callback called exit"
.PD 0
.ie n .IP """Out of memory!""" 4
.el .IP "``Out of memory!''" 4
.IX Item "Out of memory!"
.PD
If something goes really wrong with your code, Perl may die with an
\&\*(L"Out of memory!\*(R" message and or \*(L"Callback called exit\*(R". A common
cause of this are never-ending loops, deep recursion or calling an
undefined subroutine. Here's one way to catch the problem:
See Perl's \s-1INSTALL\s0 document for this item:
.IP "\-DPERL_EMERGENCY_SBRK" 4
.IX Item "-DPERL_EMERGENCY_SBRK"
If \s-1PERL_EMERGENCY_SBRK\s0 is defined, running out of memory need not be a
fatal error: a memory pool can allocated by assigning to the special
variable $^M. See \fIperlvar\fR\|(1) for more details.
.Sp
If you compile with that option and add 'use Apache::Debug level => 4;'
to your PerlScript, it will allocate the $^M emergency pool and the
\&\f(CW$SIG\fR{_\|_DIE_\|_} handler will call Carp::confess, giving you a stack
trace which should reveal where the problem is.
.Sp
See the \fBApache::Resource\fR module for prevention of spinning httpds.
.IP "\(bu" 4
If you wish to use a module that is normally linked static with your
Perl, it must be listed in static_ext in Perl's Config.pm to be linked
with httpd during the mod_perl build.
.IP "Can't load '$Config{sitearchexp}/auto/Foo/Foo.so' for module Foo..." 4
.IX Item "Can't load '$Config{sitearchexp}/auto/Foo/Foo.so' for module Foo..."
When starting httpd some people have reported seeing an error along
the lines of:
.Sp
.Vb 6
\& [Thu Jul 9 17:33:42 1998] [error] Can't load
\& '/usr/local/ap/lib/perl5/site_perl/sun4-solaris/auto/DBI/DBI.so' for
\& module DBI: ld.so.1: src/httpd: fatal: relocation error: file
\& /usr/local/ap/lib/perl5/site_perl/sun4-solaris/auto/DBI/DBI.so: symbol
\& Perl_sv_undef: referenced symbol not found at
\& /usr/local/ap/lib/perl5/sun4-solaris/5.00404/DynaLoader.pm line 166.
.Ve
.Sp
Or similar for the \s-1IO\s0 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 \*(L"additional \s-1LD\s0 flags\*(R":
.Sp
.Vb 1
\& -Xlinker --export-dynamic
.Ve
.Sp
or
.Sp
.Vb 1
\& -Xlinker -E
.Ve
.Sp
This problem is only known to be caused by installing gnu ld under Solaris.
.Sp
Other known causes of this problem:
.Sp
\&\s-1OS\s0 distributions that ship with a (broken) binary Perl installation.
.Sp
The `perl' program and `libperl.a' library are somehow built with
different binary compatiblity flags.
.Sp
The solution to these problems is to rebuild Perl and extension
modules from a fresh source tree. Tip for running Perl's Configure
script, use the `\f(CW\*(C`\-des\*(C'\fR' flags to accepts defaults and `\f(CW\*(C`\-D\*(C'\fR' flag to
override certain attributes:
.Sp
.Vb 1
\& % ./Configure -des -Dcc=gcc ... && make test && make install
.Ve
.Sp
Read Perl's \s-1INSTALL\s0 doc for more details.
.Sh "Clashes with other Apache C modules"
.IX Subsection "Clashes with other Apache C modules"
.IP "mod_auth_dbm" 4
.IX Item "mod_auth_dbm"
If you are a user of \fBmod_auth_dbm\fR or \fBmod_auth_db\fR, you may need
to edit Perl's \f(CW\*(C`Config\*(C'\fR module. When Perl is configured it attempts
to find libraries for ndbm, gdbm, db, etc., for the *DBM*_File
modules. By default, these libraries are linked with Perl and
remembered by the \fBConfig\fR module. When mod_perl is configured with
apache, the \fBExtUtils::Embed\fR module returns these libraries to be
linked with httpd so Perl extensions will work under mod_perl.
However, the order in which these libraries are stored in
\&\fBConfig.pm\fR, may confuse \f(CW\*(C`mod_auth_db*\*(C'\fR. If \f(CW\*(C`mod_auth_db*\*(C'\fR does
not work with mod_perl, take a look at this order with the following
command:
.Sp
.Vb 1
\& % perl -V:libs
.Ve
.Sp
If \f(CW\*(C`\-lgdbm\*(C'\fR or \f(CW\*(C`\-ldb\*(C'\fR is before \f(CW\*(C`\-lndbm\*(C'\fR, example:
.Sp
.Vb 1
\& libs='-lnet -lnsl_s -lgdbm -lndbm -ldb -ldld -lm -lc -lndir -lcrypt';
.Ve
.Sp
Edit \fBConfig.pm\fR and move \f(CW\*(C`\-lgdbm\*(C'\fR and \f(CW\*(C`\-ldb\*(C'\fR to the end of the
list. Here's how to find \fBConfig.pm\fR:
.Sp
.Vb 1
\& % perl -MConfig -e 'print "$Config{archlibexp}/Config.pm\en"'
.Ve
.Sp
Another solution for building Apache/mod_perl+mod_auth_dbm under Solaris
is to remove the \s-1DBM\s0 and \s-1NDBM\s0 \*(L"emulation\*(R" from libgdbm.a. Seems
Solaris already provides its own \s-1DBM\s0 and \s-1NDBM\s0, and there's no reason
to build \s-1GDBM\s0 with them (for us anyway).
.Sp
In our Makefile for \s-1GDBM\s0, we changed
.Sp
.Vb 1
\& OBJS = $(DBM_OF) $(NDBM_OF) $(GDBM_OF)
.Ve
.Sp
to
.Sp
.Vb 1
\& OBJS = $(GDBM_OF)
.Ve
.Sp
Rebuild libgdbm, then Apache/mod_perl.
.SH "REGULAR EXPRESSIONS"
.IX Header "REGULAR EXPRESSIONS"
.Sh "\s-1COMPILED\s0 \s-1REGULAR\s0 \s-1EXPRESSIONS\s0"
.IX Subsection "COMPILED REGULAR EXPRESSIONS"
When using a regular expression that contains an interpolated Perl variable,
if it is known that the variable (or variables) will not vary during the
execution of the program, a standard optimization technique consists of
adding the \f(CW\*(C`o\*(C'\fR modifier to the regexp pattern, to direct the compiler to
build the internal table once, for the entire lifetime of the script, rather
than every time the pattern is executed. Consider:
.PP
.Vb 4
\& my $pat = '^foo$'; # likely to be input from an HTML form field
\& foreach( @list ) {
\& print if /$pat/o;
\& }
.Ve
.PP
This is usually a big win in loops over lists, or when using \f(CW\*(C`grep\*(C'\fR or
\&\f(CW\*(C`map\*(C'\fR.
.PP
In long-lived \f(CW\*(C`mod_perl\*(C'\fR scripts, however, this can pose a problem if the
variable changes according to the invocation. The first invocation of a
fresh httpd child will compile the table and perform the search correctly,
however, all subsequent uses by the httpd child will continue to match the
original pattern, regardless of the current contents of the Perl variables
the pattern is dependent on. Your script will appear broken.
.PP
There are two solutions to this problem.
.PP
The first is to use \f(CW\*(C`eval q//\*(C'\fR, to force the code to be evaluated each
time. Just make sure that the \f(CW\*(C`eval\*(C'\fR block covers the entire loop of
processing, and not just the pattern match itself.
.PP
The above code fragment would be rewritten as:
.PP
.Vb 6
\& my $pat = '^foo$';
\& eval q{
\& foreach( @list ) {
\& print if /$pat/o;
\& }
\& }
.Ve
.PP
Just saying
.PP
.Vb 1
\& eval q{ print if /$pat/o; };
.Ve
.PP
is going to be a horribly expensive proposition.
.PP
You use this approach if you require more than one pattern match operator in
a given section of code. If the section contains only one operator (be it an
\&\f(CW\*(C`m//\*(C'\fR or \f(CW\*(C`s///\*(C'\fR), you can rely on the property of the null pattern, that
reuses the last pattern seen. This leads to the second solution, which also
eliminates the use of \f(CW\*(C`eval\*(C'\fR.
.PP
The above code fragment becomes:
.PP
.Vb 5
\& my $pat = '^foo$';
\& "something" =~ /$pat/; # dummy match (MUST NOT FAIL!)
\& foreach( @list ) {
\& print if //;
\& }
.Ve
.PP
The only gotcha is that the dummy match that boots the regular expression
engine must absolutely, positively succeed, otherwise the pattern will not
be cached, and the // will match everything. If you can't count on fixed
text to ensure the match succeeds, you have two possibilities.
.PP
If you can guaranteee that the pattern variable contains no meta-characters
(things like \f(CW\*(C`*\*(C'\fR, \f(CW\*(C`+\*(C'\fR, \f(CW\*(C`^\*(C'\fR, \f(CW\*(C`$\*(C'\fR...), you can use the dummy match:
.PP
.Vb 1
\& "$pat" =~ /\eQ$pat\eE/; # guaranteed if no meta-characters present
.Ve
.PP
If there is a possibility that the pattern can contain meta\-characters, you
should search for the pattern or the unsearchable \f(CW\*(C`\e377\*(C'\fR character as
follows:
.PP
.Vb 1
\& "\e377" =~ /$pat|^[\e377]$/; # guarenteed if meta-characters present
.Ve
.Sh "References"
.IX Subsection "References"
.Vb 1
\& The Camel Book, 2nd edition, p. 538 (p. 356 in the 1st edition).
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Doug MacEachern, with contributions from
Jens Heunemann ,
David Landgren ,
Mark Mills ,
Randal Schwartz and
Ask Bjoern Hansen