.\" 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 "cgi_to_mod_perl 3"
.TH cgi_to_mod_perl 3 "2007-03-30" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
cgi_to_mod_perl \- First steps needed to use mod_perl as a CGI replacement
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
As the \s-1README\s0 and other mod_perl documents explain, mod_perl as
a \s-1CGI\s0 replacement is only a small piece of what the package offers.
However, it is the most popular use of mod_perl, this document is here
so you can cut to the chase.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
Read the \s-1INSTALL\s0 document, in most cases, nothing more is required
than:
.PP
.Vb 1
\& perl Makefile.PL && make && make install
.Ve
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
For using mod_perl as a \s-1CGI\s0 replacement, the recommended configuration
is as follows:
.PP
.Vb 1
\& Alias /perl/  /real/path/to/perl-scripts/
.Ve
.PP
.Vb 5
\& <Location /perl>
\& SetHandler  perl-script
\& PerlHandler Apache::Registry
\& Options +ExecCGI
\& </Location>
.Ve
.PP
`Location' refers to the uri, not a directory, think of the above as 
.PP
.Vb 1
\& <Location http://www.yourname.com/perl>
.Ve
.PP
Any files under that location (which live on your filesystem under
/real/path/to/perl\-scripts/), will be handled by the Apache::Registry
module, which emulates the \s-1CGI\s0 environment.  The file must exist and
be executable, in addition,  'Options ExecCGI' must be turned on.
.PP
If you wish to have mod_perl execute scripts in any location based on
file extension, use a configuration like so:
.PP
.Vb 5
\& <Files ~ "\e.pl$">
\& SetHandler perl-script
\& PerlHandler Apache::Registry
\& Options ExecCGI
\& </Files>
.Ve
.PP
Note that `ScriptAlias' does _not_ work for mod_perl.
.SH "PORTING CGI SCRIPTS"
.IX Header "PORTING CGI SCRIPTS"
.IP "I/O" 4
.IX Item "I/O"
If you are using Perl 5.004 most \s-1CGI\s0 scripts can run under mod_perl
untouched.  If you're using 5.003, Perl's built-in \f(CW\*(C`read()\*(C'\fR and
\&\f(CW\*(C`print()\*(C'\fR functions do not work as they do under \s-1CGI\s0.  If you're
using \s-1CGI\s0.pm, use \f(CW\*(C`$query\->print\*(C'\fR instead of plain 'ol \f(CW\*(C`print()\*(C'\fR.
.IP "\s-1HEADERS\s0" 4
.IX Item "HEADERS"
By default, mod_perl does not send any headers by itself, however, you
may wish to change this:
.Sp
.Vb 1
\&    PerlSendHeader On
.Ve
.Sp
Now the response line and common headers will be sent as they are by
mod_cgi.  And, just as with mod_cgi, PerlSendHeader will not send a
terminating newline, your script must send that itself, e.g.:
.Sp
.Vb 1
\& print "Content-type: text/html\en\en";
.Ve
.Sp
If you're using \s-1CGI\s0.pm and 'print \f(CW$q\fR\->header' you do
_not_ need \f(CW\*(C`PerlSendHeader On\*(C'\fR.    
.IP "\s-1NPH\s0 \s-1SCRIPTS\s0" 4
.IX Item "NPH SCRIPTS"
To run a \s-1CGI\s0 `nph' script under mod_perl, simply add to your code:
.Sp
.Vb 1
\& local $| = 1;
.Ve
.Sp
If you normally set \fBPerlSendHeader On\fR, add this to your httpd.conf:
.Sp
.Vb 3
\& <Files */nph-*>
\& PerlSendHeader Off
\& </Files>
.Ve
.IP "\s-1PROGRAMMING\s0 \s-1PRACTICE\s0" 4
.IX Item "PROGRAMMING PRACTICE"
\&\s-1CGI\s0 lets you get away with sloppy programming, mod_perl does not.
Why?  \s-1CGI\s0 scripts have the lifetime of a single \s-1HTTP\s0 request as a
separate process.  When the request is over, the process goes away and
everything is cleaned up for you, e.g. globals variables, open files,
etc.  Scripts running under mod_perl have a longer lifetime, over
several request, different scripts may be in the same process.  This
means you must clean up after yourself.  You've heard:
.Sp
.Vb 1
\& always 'use strict' and C<-w>!!!
.Ve
.Sp
It's more important under mod_perl Perl than anywhere else, while it's
not required, it \fBstrongly\fR recommended, it will save you more time
in the long run.  And, of course, clean scripts will still run under
\&\s-1CGI\s0! 
.IP "\s-1TRAPS\s0" 4
.IX Item "TRAPS"
See mod_perl_traps.
.SH "REPORTING PROBLEMS"
.IX Header "REPORTING PROBLEMS"
Read the \s-1SUPPORT\s0 file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIApache::PerlRun\fR\|(3)