Writing Apache Modules with Perl and C

3.3. The Handler API

When Apache calls a handler, it passes information about the current transaction and the server configuration. It's the handler's responsibility to take whatever action is appropriate for this phase and to then return an integer status code to Apache indicating the success or failure of its operation.

3.3.1. Handler Subroutines

In the Perl API, the definition of a handler is short and sweet:

In the Perl API, the definition of a handler is short and sweet:

sub handler { 
   my $r = shift; 
   # do something 
   return SOME_STATUS_CODE; 
}

No matter which phase of the Apache life cycle the handler is responsible for, the subroutine structure is always the same. The handler is passed a single argument consisting of a reference to an Apache request object. The request object is an object-oriented version of a central C record structure called the request record , and it contains all the information that Apache has collected about the transaction. By convention, a typical handler will store this object in a lexically scoped variable named $r. The handler retrieves whatever information it needs from the request object, does some processing, and possibly modifies the object to suit its needs. The handler then returns a numeric status code as its function result, informing Apache of the outcome of its work. We discuss the list of status codes and their significance in the next section.

There is one special case, however. If the handler has a function prototype of ($$) indicating ...