Set up environment variables for each request, à la mod_cgi.

When this option is enabled, mod_perl fiddles with the environment to make it appear as if the code is called under the mod_cgi handler. For example, the $ENV{QUERY_STRING} environment variable is initialized with the contents of Apache::args( ), and the value returned by Apache::server_hostname( ) is put into $ENV{SERVER_NAME}.

Those who have moved to the mod_perl API no longer need this extra %ENV population and can gain by disabling it, since %ENV population is expensive. Code using the CGI.pm module requires PerlOptions +SetupEnv because that module relies on a properly populated CGI environment table.

This option is enabled by default for sections configured as:

<Location ...>
    SetHandler perl-script
    ...
</Location>

Since this option adds an overhead to each request, if you don't need this functionality you can turn it off for a certain section:

<Location ...>
    SetHandler perl-script
    PerlOptions -SetupEnv
    ...
</Location>

or globally affect the whole server:

PerlOptions -SetupEnv
<Location ...>
    ...
</Location>

It can still be enabled for sections that need this functionality.

When this option is disabled you can still read environment variables set by you. For example, when you use the following configuration:

PerlOptions -SetupEnv
<Location /perl>
  PerlSetEnv TEST hi
  SetHandler perl-script
  PerlHandler ModPerl::Registry
  Options +ExecCGI
</Location>

and you issue a request for setupenvoff.pl from Example 24-4.

Example 24-4. setupenvoff.pl

use Data::Dumper;
my $r = Apache->request( );
$r->send_http_header('text/plain');
print Dumper(\%ENV);

you should see something like this:

$VAR1 = {
          'GATEWAY_INTERFACE' => 'CGI-Perl/1.1',
          'MOD_PERL' => 'mod_perl/2.0.1',
          'PATH' => '/bin:/usr/bin',
          'TEST' => 'hi'
        };

Notice that we got the value of the environment variable TEST.