.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" 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 "libapache2-mod-perl2-2.0.11::docs::api::Apache2::Response 3pm"
.TH libapache2-mod-perl2-2.0.11::docs::api::Apache2::Response 3pm "2021-05-21" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Apache2::Response \- Perl API for Apache HTTP request response methods
.SH "Synopsis"
.IX Header "Synopsis"
.Vb 1
\&  use Apache2::Response ();
\&  
\&  $r\->custom_response(Apache2::Const::FORBIDDEN, "No Entry today");
\&  
\&  $etag = $r\->make_etag($force_weak);
\&  $r\->set_etag();
\&  $status = $r\->meets_conditions();
\&  
\&  $mtime_rat = $r\->rationalize_mtime($mtime);
\&  $r\->set_last_modified($mtime);
\&  $r\->update_mtime($mtime);
\&  
\&  $r\->send_cgi_header($buffer);
\&  
\&  $r\->set_content_length($length);
\&  
\&  $ret = $r\->set_keepalive();
.Ve
.SH "Description"
.IX Header "Description"
\&\f(CW\*(C`Apache2::Response\*(C'\fR provides the Apache request
object utilities \s-1API\s0 for dealing
with \s-1HTTP\s0 response generation process.
.SH "API"
.IX Header "API"
\&\f(CW\*(C`Apache2::Response\*(C'\fR provides the following functions and/or methods:
.ie n .SS """custom_response"""
.el .SS "\f(CWcustom_response\fP"
.IX Subsection "custom_response"
Install a custom response handler for a given status
.PP
.Vb 1
\&  $r\->custom_response($status, $string);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "arg1: $status ( ""Apache2::Const constant"" )" 4
.el .IP "arg1: \f(CW$status\fR ( \f(CWApache2::Const constant\fR )" 4
.IX Item "arg1: $status ( Apache2::Const constant )"
The status for which the custom response should be used
(e.g. \f(CW\*(C`Apache2::Const::AUTH_REQUIRED\*(C'\fR)
.ie n .IP "arg2: $string (string)" 4
.el .IP "arg2: \f(CW$string\fR (string)" 4
.IX Item "arg2: $string (string)"
The custom response to use.  This can be a static string, or a \s-1URL,\s0
full or just the uri path (\fI/foo/bar.txt\fR).
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
\&\f(CW\*(C`custom_response()\*(C'\fR doesn't alter the response code, but is used to
replace the standard response body. For example, here is how to change
the response body for the access handler failure:
.PP
.Vb 5
\&  package MyApache2::MyShop;
\&  use Apache2::Response ();
\&  use Apache2::Const \-compile => qw(FORBIDDEN OK);
\&  sub access {
\&      my $r = shift;
\&   
\&      if (MyApache2::MyShop::tired_squirrels()) {
\&          $r\->custom_response(Apache2::Const::FORBIDDEN,
\&              "It\*(Aqs siesta time, please try later");
\&          return Apache2::Const::FORBIDDEN;
\&      }
\&  
\&      return Apache2::Const::OK;
\&  }
\&  ...
\&
\&  # httpd.conf
\&  PerlModule MyApache2::MyShop
\&  <Location /TestAPI_\|_custom_response>
\&      AuthName dummy
\&      AuthType none
\&      PerlAccessHandler   MyApache2::MyShop::access
\&      PerlResponseHandler MyApache2::MyShop::response
\&  </Location>
.Ve
.PP
When squirrels can't run any more, the handler will return 403, with
the custom message:
.PP
.Vb 1
\&  It\*(Aqs siesta time, please try later
.Ve
.ie n .SS """make_etag"""
.el .SS "\f(CWmake_etag\fP"
.IX Subsection "make_etag"
Construct an entity tag from the resource information.  If it's a real
file, build in some of the file characteristics.
.PP
.Vb 1
\&  $etag = $r\->make_etag($force_weak);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "arg1: $force_weak (number)" 4
.el .IP "arg1: \f(CW$force_weak\fR (number)" 4
.IX Item "arg1: $force_weak (number)"
Force the entity tag to be weak \- it could be modified
again in as short an interval.
.ie n .IP "ret: $etag (string)" 4
.el .IP "ret: \f(CW$etag\fR (string)" 4
.IX Item "ret: $etag (string)"
The entity tag
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """meets_conditions"""
.el .SS "\f(CWmeets_conditions\fP"
.IX Subsection "meets_conditions"
Implements condition \f(CW\*(C`GET\*(C'\fR rules for \s-1HTTP/1.1\s0 specification.  This
function inspects the client headers and determines if the response
fulfills the specified requirements.
.PP
.Vb 1
\&  $status = $r\->meets_conditions();
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "ret: $status ( ""Apache2::Const status constant"" )" 4
.el .IP "ret: \f(CW$status\fR ( \f(CWApache2::Const status constant\fR )" 4
.IX Item "ret: $status ( Apache2::Const status constant )"
\&\f(CW\*(C`Apache2::Const::OK\*(C'\fR if the response fulfills the condition \s-1GET\s0
rules. Otherwise some other status code (which should be returned to
Apache).
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
Refer to the Generating Correct \s-1HTTP\s0
Headers document
for an indepth discussion of this method.
.ie n .SS """rationalize_mtime"""
.el .SS "\f(CWrationalize_mtime\fP"
.IX Subsection "rationalize_mtime"
Return the latest rational time from a request/mtime pair.
.PP
.Vb 1
\&  $mtime_rat = $r\->rationalize_mtime($mtime);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "arg1: $mtime ( time in seconds )" 4
.el .IP "arg1: \f(CW$mtime\fR ( time in seconds )" 4
.IX Item "arg1: $mtime ( time in seconds )"
The last modified time
.ie n .IP "ret: $mtime_rat ( time in seconds )" 4
.el .IP "ret: \f(CW$mtime_rat\fR ( time in seconds )" 4
.IX Item "ret: $mtime_rat ( time in seconds )"
the latest rational time from a request/mtime pair.  Mtime is
returned unless it's in the future, in which case we return the
current time.
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.ie n .SS """send_cgi_header"""
.el .SS "\f(CWsend_cgi_header\fP"
.IX Subsection "send_cgi_header"
Parse the header
.PP
.Vb 1
\&  $r\->send_cgi_header($buffer);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
.PD 0
.ie n .IP "arg1: $buffer (string)" 4
.el .IP "arg1: \f(CW$buffer\fR (string)" 4
.IX Item "arg1: $buffer (string)"
.PD
headers and optionally a response body
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
This method is really for back-compatibility with mod_perl 1.0. It's
very inefficient to send headers this way, because of the parsing
overhead.
.PP
If there is a response body following the headers it'll be handled too
(as if it was sent via
\&\f(CW\*(C`print()\*(C'\fR).
.PP
Notice that if only \s-1HTTP\s0 headers are included they won't be sent until
some body is sent (again the \*(L"send\*(R" part is retained from the mod_perl
1.0 method).
.ie n .SS """set_content_length"""
.el .SS "\f(CWset_content_length\fP"
.IX Subsection "set_content_length"
Set the content length for this request.
.PP
.Vb 1
\&  $r\->set_content_length($length);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "arg1: $length (integer)" 4
.el .IP "arg1: \f(CW$length\fR (integer)" 4
.IX Item "arg1: $length (integer)"
The new content length
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """set_etag"""
.el .SS "\f(CWset_etag\fP"
.IX Subsection "set_etag"
Set the E\-tag outgoing header
.PP
.Vb 1
\&  $r\->set_etag();
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
.PD 0
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """set_keepalive"""
.el .SS "\f(CWset_keepalive\fP"
.IX Subsection "set_keepalive"
Set the keepalive status for this request
.PP
.Vb 1
\&  $ret = $r\->set_keepalive();
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "ret: $ret ( boolean )" 4
.el .IP "ret: \f(CW$ret\fR ( boolean )" 4
.IX Item "ret: $ret ( boolean )"
true if keepalive can be set, false otherwise
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
It's called by \f(CW\*(C`ap_http_header_filter()\*(C'\fR. For the complete
complicated logic implemented by this method see
\&\fIhttpd\-2.0/server/http_protocol.c\fR.
.ie n .SS """set_last_modified"""
.el .SS "\f(CWset_last_modified\fP"
.IX Subsection "set_last_modified"
sets the \f(CW\*(C`Last\-Modified\*(C'\fR response header field to the value of the
mtime field in the request structure \*(-- rationalized to keep it from
being in the future.
.PP
.Vb 1
\&  $r\->set_last_modified($mtime);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
.PD 0
.ie n .IP "opt arg1: $mtime ( time in seconds )" 4
.el .IP "opt arg1: \f(CW$mtime\fR ( time in seconds )" 4
.IX Item "opt arg1: $mtime ( time in seconds )"
.PD
if the \f(CW$mtime\fR argument is passed,
\&\f(CW$r\fR\->update_mtime will be first run with that
argument.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.ie n .SS """update_mtime"""
.el .SS "\f(CWupdate_mtime\fP"
.IX Subsection "update_mtime"
Set the
\&\f(CW\*(C`$r\->mtime\*(C'\fR field
to the specified value if it's later than what's already there.
.PP
.Vb 1
\&  $r\->update_mtime($mtime);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "arg1: $mtime ( time in seconds )" 4
.el .IP "arg1: \f(CW$mtime\fR ( time in seconds )" 4
.IX Item "arg1: $mtime ( time in seconds )"
.PD 0
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
See also: \f(CW$r\fR\->set_last_modified.
.SH "Unsupported API"
.IX Header "Unsupported API"
\&\f(CW\*(C`Apache2::Response\*(C'\fR also provides auto-generated Perl interface for a
few other methods which aren't tested at the moment and therefore
their \s-1API\s0 is a subject to change. These methods will be finalized
later as a need arises. If you want to rely on any of the following
methods please contact the the mod_perl development mailing
list so we can help each other take the steps necessary
to shift the method to an officially supported \s-1API.\s0
.ie n .SS """send_error_response"""
.el .SS "\f(CWsend_error_response\fP"
.IX Subsection "send_error_response"
Send an \*(L"error\*(R" response back to client. It is used for any response
that can be generated by the server from the request record.  This
includes all 204 (no content), 3xx (redirect), 4xx (client error), and
5xx (server error) messages that have not been redirected to another
handler via the ErrorDocument feature.
.PP
.Vb 1
\&  $r\->send_error_response($recursive_error);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "arg1: $recursive_error ( boolean )" 4
.el .IP "arg1: \f(CW$recursive_error\fR ( boolean )" 4
.IX Item "arg1: $recursive_error ( boolean )"
the error status in case we get an error in the process of trying to
deal with an \f(CW\*(C`ErrorDocument\*(C'\fR to handle some other error.  In that
case, we print the default report for the first thing that went wrong,
and more briefly report on the problem with the \f(CW\*(C`ErrorDocument\*(C'\fR.
.IP "ret: no return value" 4
.IX Item "ret: no return value"
.PD 0
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PD
.PP
\&\s-1META:\s0 it's really an internal Apache method, I'm not quite sure how
can it be used externally.
.ie n .SS """send_mmap"""
.el .SS "\f(CWsend_mmap\fP"
.IX Subsection "send_mmap"
\&\s-1META:\s0 Autogenerated \- needs to be reviewed/completed
.PP
Send an \s-1MMAP\s0'ed file to the client
.PP
.Vb 1
\&  $ret = $r\->send_mmap($mm, $offset, $length);
.Ve
.ie n .IP "obj: $r ( ""Apache2::RequestRec object"" )" 4
.el .IP "obj: \f(CW$r\fR ( \f(CWApache2::RequestRec object\fR )" 4
.IX Item "obj: $r ( Apache2::RequestRec object )"
The current request
.ie n .IP "arg1: $mm (""APR::Mmap"")" 4
.el .IP "arg1: \f(CW$mm\fR (\f(CWAPR::Mmap\fR)" 4
.IX Item "arg1: $mm (APR::Mmap)"
The \s-1MMAP\s0'ed file to send
.ie n .IP "arg2: $offset (number)" 4
.el .IP "arg2: \f(CW$offset\fR (number)" 4
.IX Item "arg2: $offset (number)"
The offset into the \s-1MMAP\s0 to start sending
.ie n .IP "arg3: $length (integer)" 4
.el .IP "arg3: \f(CW$length\fR (integer)" 4
.IX Item "arg3: $length (integer)"
The amount of data to send
.ie n .IP "ret: $ret (integer)" 4
.el .IP "ret: \f(CW$ret\fR (integer)" 4
.IX Item "ret: $ret (integer)"
The number of bytes sent
.IP "since: 2.0.00" 4
.IX Item "since: 2.0.00"
.PP
\&\s-1META:\s0 requires a working APR::Mmap, which is not supported at the
moment.
.SH "See Also"
.IX Header "See Also"
mod_perl 2.0 documentation.
.SH "Copyright"
.IX Header "Copyright"
mod_perl 2.0 and its core modules are copyrighted under
The Apache Software License, Version 2.0.
.SH "Authors"
.IX Header "Authors"
The mod_perl development team and numerous
contributors.