libapa...egistry(3pm)

💖 libapa...egistry(3pm) — ModPerl::Registry 💖

okay bestie, welcome to the User Contributed Perl Documentation corner of the internet, where we're talking about ModPerl::Registry — the thing that lets you run unaltered CGI scripts persistently under mod_perl. no cap. 🦋

---

✨ NAME ✨

ModPerl::Registry — Run unaltered CGI scripts persistently under mod_perl

---

🌸 SYNOPSIS 🌸

like, here's the whole vibe in httpd.conf form:

# httpd.conf
PerlModule ModPerl::Registry
Alias /perl/ /home/httpd/perl/
<Location /perl>
    SetHandler perl-script
    PerlResponseHandler ModPerl::Registry
    #PerlOptions +ParseHeaders
    #PerlOptions -GlobalRequest
    Options +ExecCGI
</Location>

slay. that's it. that's the whole setup. 👑

---

🎀 DESCRIPTION 🎀

so URIs shaped like "http://example.com/perl/test.pl" get compiled as the body of a Perl subroutine and then executed. every child process compiles that subroutine once and keeps it in memory, and it recompiles whenever the file (like test.pl in our lil example) gets updated on disk. think of it as an object oriented server where each script is basically implementing a class loaded at runtime. it's giving… yeah. that. ✨

the file looks a lot like a "normal" script, but plot twist: it's compiled into a subroutine.

for example:

my $r = Apache2::RequestUtil->request;
$r->content_type("text/html");
$r->print("mod_perl rules!");

XXX: STOPPED here. Below is the old Apache::Registry document which I haven't worked through yet.

META: document that for now we don't chdir() into the script's dir, because it affects the whole process under threads. ModPerl::RegistryPrefork should be used by those who run only under prefork MPM.

this module emulates the CGI environment, so programmers can write scripts that run under CGI or mod_perl without change. existing CGI scripts might still need some changes, simply because a CGI script has a very short lifetime of one HTTP request — which let you get away with "quick and dirty" scripting. using mod_perl and ModPerl::Registry requires you to be more careful, but it also gives new meaning to the word "quick"! 😭

be sure to read all mod_perl related documentation for more details, including instructions for setting up an environment that looks exactly like CGI:

 print "Content-type: text/html\n\n";
 print "Hi There!";

note that each httpd process or "child" must compile each script once, so the first request to one server may seem slow, but each request after that will be faster. if your scripts are large and/or make use of many Perl modules, this difference should be noticeable to the human eye. 🫶

---

📁 DirectoryIndex 📁

if you're trying to set up a DirectoryIndex under a Location covered by ModPerl::Registry* you might run into some trouble. 🙈

META: if this gets added to core, replace with real documentation. See http://marc.theaimsgroup.com/?l=apache-modperl&m=112805393100758&w=2

---

🔮 SPECIAL BLOCKS 🔮

BEGIN Blocks

BEGIN blocks defined in scripts running under the ModPerl::Registry handler behave similarly to the normal mod_perl handlers plus:

• Only once, if pulled in by the parent process via Apache2::RegistryLoader.
• An additional time, once per child process or Perl interpreter, each time the script file changes on disk.

BEGIN blocks defined in modules loaded from ModPerl::Registry scripts behave identically to the normal mod_perl handlers, regardless of whether they define a package or not. periodt. 💅

CHECK and INIT Blocks

Same as normal mod_perl handlers. that's it, that's the whole section, iconic and brief. ✨

END Blocks

END blocks encountered during compilation of a script are called after the script has completed its run, including subsequent invocations when the script is cached in memory. this is assuming that the script itself doesn't define a package on its own. if the script defines its own package, the END blocks in the scope of that package will be executed at the end of the interpretor's life. 💀

END blocks residing in modules loaded by a registry script will be executed only once, when the interpreter exits.

---

🛡️ SECURITY 🛡️

ModPerl::Registry::handler performs the same sanity checks as mod_cgi does, before running the script. no shortcuts, no shady business. 👑

---

🌈 ENVIRONMENT 🌈

the Apache function exit overrides the Perl core built-in function.

---

🧚 COMMANDLINE SWITCHES IN FIRST LINE 🧚

normally when a Perl script is run from the command line or under CGI, arguments on the #! line are passed to the perl interpreter for processing.

ModPerl::Registry currently only honors the -w switch and will enable the warnings pragma in such case.

another common switch used with CGI scripts is -T to turn on taint checking. this can only be enabled when the server starts with the configuration directive:

 PerlSwitches -T

however, if taint checking is not enabled, but the -T switch is seen, ModPerl::Registry will write a warning to the error_log file. bestie, check your error log. 👀

---

🐛 DEBUGGING 🐛

you may set the debug level with the $ModPerl::Registry::Debug bitmask:

 1 => log recompile in errorlog
 2 => ModPerl::Debug::dump in case of $@
 4 => trace pedantically

---

💀 CAVEATS 💀

ModPerl::Registry makes things look just like the CGI environment, however, you must understand that this is not CGI. each httpd child will compile your script into memory and keep it there, whereas CGI will run it once, cleaning out the entire process space. many times you have heard "always use -w, always use -w and 'use strict'". this is more important here than anywhere else! some other important caveats to keep in mind are discussed on the Perl Reference page. 🫶

---

👑 AUTHORS 👑

Andreas J. Koenig, Doug MacEachern and Stas Bekman.

---

🦋 SEE ALSO 🦋

ModPerl::RegistryCooker, ModPerl::RegistryBB and ModPerl::PerlRun.

---

okay that's the whole page, you're officially certified in ModPerl::Registry now, go forth and slay ✨

this was brought to you by perl v5.42.3, dated 2026-08-20, from your friendly neighborhood libapa...egistry(3pm) page. mwah 💖