=head1 NAME Apache::File - advanced functions for manipulating files at the server side =head1 Synopsis use Apache::File (); my $fh = Apache::File->new($filename); print $fh 'Hello'; $fh->close; my ($name, $fh) = Apache::File->tmpfile; if ((my $rc = $r->discard_request_body) != OK) { return $rc; } if((my $rc = $r->meets_conditions) != OK) { return $rc; } my $date_string = localtime $r->mtime; $r->set_content_length; $r->set_etag; $r->update_mtime; $r->set_last_modified; =head1 Description C does two things: it provides an object-oriented interface to filehandles similar to Perl's standard C. While the C module does not provide all the functionality of C, its methods are approximately twice as fast as the equivalent C methods. Secondly, when you use C, it adds several new methods to the C class which provide support for handling files under the C protocol. =head1 Apache::File methods =over 4 =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 C method automatically. use Apache::File (); my $fh = Apache::File->new; my $fh = Apache::File->new($filename) or die "Can't open $filename $!"; =item open() Given an Apache::File object previously created with C, this method opens a file and associates it with the object. The C method accepts the same types of arguments as the standard Perl C function, including support for file modes. $fh->open($filename); $fh->open(">$out_file"); $fh->open("|$program"); =item close() The C method is equivalent to the Perl builtin close function, returns true upon success, false upon failure. $fh->close or die "Can't close $filename $!"; =item tmpfile() The C method is responsible for opening up a unique temporary file. It is similar to the C function in the C module, but doesn't come with all the memory overhead that loading C 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 ID and the C<$TMPNAM> 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. As an added bonus, C calls the C method behind the scenes to make sure the file is unlinked after the transaction is finished. Called in a list context, C returns the temporary file name and a filehandle opened for reading and writing. In a scalar context only the filehandle is returned. my ($tmpnam, $fh) = Apache::File->tmpfile; my $fh = Apache::File->tmpfile; =back =head1 Apache Methods added by Apache::File When a handler pulls in C, 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 C protocol that provide increased performance through client-side document caching. =over 4 =item $r-Ediscard_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. if ((my $rc = $r->discard_request_body) != OK) { return $rc; } =item $r-Emeets_conditions() In the interest of HTTP/1.1 compliance, the C method is used to implement ``conditional GET'' rules. These rules include inspection of client headers, including C, C, C and C. 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 C, the module should return from the handler with that value. A common return value other than C is C, which is sent when the document is already cached on the client side, and has not changed since it was cached. if((my $rc = $r->meets_conditions) != OK) { return $rc; } #else ... go and send the response body ... =item $r-Emtime() This method returns the last modified time of the requested file, expressed as seconds since the epoch. my $date_string = localtime $r->mtime; To change the last modified time use the C method. =item $r-Eset_content_length() This method sets the outgoing C 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 C<$r-Efilename>. This method is a bit faster and more concise than setting C in the headers_out table yourself. $r->set_content_length; $r->set_content_length(-s $r->finfo); #same as above $r->set_content_length(-s $filename); =item $r-Eset_etag() This method is used to set the outgoing C header corresponding to the requested file. C 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 C method if the client provide an C or C header. $r->set_etag; =item $r-Eset_last_modified() This method is used to set the outgoing C from the value returned by C<$r-Emtime>. The method checks that the specified time is not in the future. In addition, using C is faster and more concise than setting C in the C table yourself. You may provide an optional time argument, in which case the method will first call the C to set the file's last modification date. It will then set the outgoing C header as before. $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 =item $r-Eupdate_mtime() Rather than setting the request record mtime field directly, you can use the C 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 $r-Efilename. $r->update_mtime; $r->update_mtime((stat $r->finfo)[9]); #same as above $r->update_mtime(time); =back =head1 Maintainers Maintainer is the person(s) you should contact with updates, corrections and patches. =over =item * The L =back =head1 Authors =over =item * Doug MacEachern =back Only the major authors are listed above. For contributors see the Changes file. =cut