.\" 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 "File 3"
.TH File 3 "2007-03-30" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Apache::File \- advanced functions for manipulating files at the server side
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Apache::File ();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Apache::File does two things: it provides an object-oriented interface
to filehandles similar to Perl's standard IO::File class. While the
Apache::File module does not provide all the functionality of
IO::File, its methods are approximately twice as fast as the
equivalent IO::File methods. Secondly, when you use Apache::File, it
adds several new methods to the Apache class which provide support for
handling files under the \s-1HTTP/1\s0.1 protocol.
.SH "Apache::File methods"
.IX Header "Apache::File methods"
.IP "\fInew()\fR" 4
.IX Item "new()"
This method creates a new filehandle, returning the filehandle object
on success, undef on failure. If an additional argument is given, it
will be passed to the \fIopen()\fR method automatically.
.Sp
.Vb 2
\&   use Apache::File ();
\&   my $fh = Apache::File->new;
.Ve
.Sp
.Vb 1
\&   my $fh = Apache::File->new($filename) or die "Can't open $filename $!";
.Ve
.IP "\fIopen()\fR" 4
.IX Item "open()"
Given an Apache::File object previously created with \fInew()\fR, this
method opens a file and associates it with the object. The \fIopen()\fR
method accepts the same types of arguments as the standard Perl \fIopen()\fR
function, including support for file modes.
.Sp
.Vb 1
\&   $fh->open($filename);
.Ve
.Sp
.Vb 1
\&   $fh->open(">$out_file");
.Ve
.Sp
.Vb 1
\&   $fh->open("|$program");
.Ve
.IP "\fIclose()\fR" 4
.IX Item "close()"
The \fIclose()\fR method is equivalent to the Perl builtin close function,
returns true upon success, false upon failure.
.Sp
.Vb 1
\&   $fh->close or die "Can't close $filename $!";
.Ve
.IP "\fItmpfile()\fR" 4
.IX Item "tmpfile()"
The \fItmpfile()\fR method is responsible for opening up a unique temporary
file. It is similar to the \fItmpnam()\fR function in the \s-1POSIX\s0 module, but
doesn't come with all the memory overhead that loading \s-1POSIX\s0 does. It
will choose a suitable temporary directory (which must be writable by
the Web server process). It then generates a series of filenames using
the current process \s-1ID\s0 and the \f(CW$TMPNAM\fR package global. Once a unique
name is found, it is opened for writing, using flags that will cause
the file to be created only if it does not already exist. This
prevents race conditions in which the function finds what seems to be
an unused name, but someone else claims the same name before it can be
created.
.Sp
As an added bonus, \fItmpfile()\fR calls the \fIregister_cleanup()\fR method
behind the scenes to make sure the file is unlinked after the
transaction is finished.
.Sp
Called in a list context, \fItmpfile()\fR returns the temporary file name
and a filehandle opened for reading and writing. In a scalar context
only the filehandle is returned.
.Sp
.Vb 1
\&   my($tmpnam, $fh) = Apache::File->tmpfile;
.Ve
.Sp
.Vb 1
\&   my $fh = Apache::File->tmpfile;
.Ve
.SH "Apache Methods added by Apache::File"
.IX Header "Apache Methods added by Apache::File"
When a handler pulls in Apache::File, the module adds a number of new
methods to the Apache request object. These methods are generally of
interest to handlers that wish to serve static files from disk or
memory using the features of the \s-1HTTP/1\s0.1 protocol that provide
increased performance through client-side document caching.
.IP "$r\->\fIdiscard_request_body()\fR" 4
.IX Item "$r->discard_request_body()"
This method tests for the existence of a request body and if present,
simply throws away the data. This discarding is especially important
when persistent connections are being used, so that the request body
will not be attached to the next request. If the request is malformed,
an error code will be returned, which the module handler should
propagate back to Apache.
.Sp
.Vb 3
\&   if ((my $rc = $r->discard_request_body) != OK) {
\&      return $rc;
\&   }
.Ve
.IP "$r\->\fImeets_conditions()\fR" 4
.IX Item "$r->meets_conditions()"
In the interest of \s-1HTTP/1\s0.1 compliance, the \fImeets_conditions()\fR method
is used to implement ``conditional \s-1GET\s0'' rules. These rules include
inspection of client headers, including If\-Modified\-Since,
If\-Unmodified\-Since, If-Match and If\-None\-Match.
.Sp
As far as Apache modules are concerned, they need only check the
return value of this method before sending a request body. If the
return value is anything other than \s-1OK\s0, the module should return from
the handler with that value. A common return value other than \s-1OK\s0 is
\&\s-1HTTP_NOT_MODIFIED\s0, which is sent when the document is already cached
on the client side, and has not changed since it was cached.
.Sp
.Vb 4
\&   if((my $rc = $r->meets_conditions) != OK) {
\&      return $rc;
\&   }
\&   #else ... go and send the response body ...
.Ve
.IP "$r\->\fImtime()\fR" 4
.IX Item "$r->mtime()"
This method returns the last modified time of the requested file,
expressed as seconds since the epoch.
.Sp
.Vb 1
\&   my $date_string = localtime $r->mtime;
.Ve
.Sp
To change the last modified time use the \f(CW\*(C`update_mtime()\*(C'\fR method.
.IP "$r\->\fIset_content_length()\fR" 4
.IX Item "$r->set_content_length()"
This method sets the outgoing Content-length header based on its
argument, which should be expressed in byte units. If no argument is
specified, the method will use the size returned by \f(CW$r\fR\->filename. This
method is a bit faster and more concise than setting Content-length in
the headers_out table yourself.
.Sp
.Vb 3
\&   $r->set_content_length;
\&   $r->set_content_length(-s $r->finfo); #same as above
\&   $r->set_content_length(-s $filename);
.Ve
.IP "$r\->\fIset_etag()\fR" 4
.IX Item "$r->set_etag()"
This method is used to set the outgoing ETag header corresponding to
the requested file. ETag is an opaque string that identifies the
currrent version of the file and changes whenever the file is
modified. This string is tested by the \fImeets_conditions()\fR method if
the client provide an If-Match or If-None-Match header.
.Sp
.Vb 1
\&   $r->set_etag;
.Ve
.IP "$r\->\fIset_last_modified()\fR" 4
.IX Item "$r->set_last_modified()"
This method is used to set the outgoing Last-Modified header from the
value returned by \f(CW$r\fR\->mtime. The method checks that the specified time
is not in the future. In addition, using \fIset_last_modified()\fR is faster
and more concise than setting Last-Modified in the headers_out table
yourself.
.Sp
You may provide an optional time argument, in which case the method
will first call the \fIupdate_mtime()\fR to set the file's last modification
date. It will then set the outgoing Last-Modified header as before.
.Sp
.Vb 3
\&   $r->update_mtime((stat $r->finfo)[9]);
\&   $r->set_last_modified;
\&   $r->set_last_modified((stat $r->finfo)[9]); #same as the two lines above
.Ve
.IP "$r\->\fIupdate_mtime()\fR" 4
.IX Item "$r->update_mtime()"
Rather than setting the request record mtime field directly, you can
use the \fIupdate_mtime()\fR method to change the value of this field. It
will only be updated if the new time is more recent than the current
mtime. If no time argument is present, the default is the last
modified time of \f(CW$r\fR\->filename.
.Sp
.Vb 3
\&   $r->update_mtime;
\&   $r->update_mtime((stat $r->finfo)[9]); #same as above
\&   $r->update_mtime(time);
.Ve