File(3) User Contributed Perl Documentation File(3)

NAME
       Apache::File - advanced functions for manipulating files at the server
       side

SYNOPSIS
          use Apache::File ();

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 meth-
       ods to the Apache class which provide support for handling files under
       the HTTP/1.1 protocol.

AAppaacchhee::::FFiillee mmeetthhooddss
       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 open() method automatically.

              use Apache::File ();
              my $fh = Apache::File->new;

              my $fh = Apache::File->new($filename) or die "Can't open $filename $!";

       open()
           Given an Apache::File object previously created with new(), this
           method opens a file and associates it with the object. The open()
           method accepts the same types of arguments as the standard Perl
           open() function, including support for file modes.

              $fh->open($filename);

              $fh->open(">$outfile");

              $fh->open("|$program");

       close()
           The close() method is equivalent to the Perl builtin close func-
           tion, returns true upon success, false upon failure.

              $fh->close or die "Can't close $filename $!";

       tmpfile()
           The tmpfile() method is responsible for opening up a unique tempo-
           rary file. It is similar to the tmpnam() function in the POSIX mod-
           ule, but doesn't come with all the memory overhead that loading
           POSIX 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 $TMPNAM
           package global. Once a unique name is found, it is opened for writ-
           ing, 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, tmpfile() calls the registercleanup() method
           behind the scenes to make sure the file is unlinked after the
           transaction is finished.

           Called in a list context, tmpfile() returns the temporary file name
           and a filehandle opened for reading and writing. In a scalar con-
           text only the filehandle is returned.

              my($tmpnam, $fh) = Apache::File->tmpfile;

              my $fh = Apache::File->tmpfile;

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 mem-
       ory using the features of the HTTP/1.1 protocol that provide increased
       performance through client-side document caching.

       $r->discardrequestbody()
           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->discardrequestbody) != OK) {
                 return $rc;
              }

       $r->meetsconditions()
           In the interest of HTTP/1.1 compliance, the meetsconditions()
           method is used to implement ``conditional GET'' rules. These rules
           include inspection of client headers, including If-Modified-Since,
           If-Unmodified-Since, If-Match and If-None-Match.

           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 OK, the module should return
           from the handler with that value. A common return value other than
           OK is HTTPNOTMODIFIED, 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->meetsconditions) != OK) {
                 return $rc;
              }
              #else ... go and send the response body ...

       $r->mtime()
           This method returns the last modified time of the requested file,
           expressed as seconds since the epoch. The last modified time may
           also be changed using this method, although updatemtime() method
           is better suited to this purpose.

              my $datestring = localtime $r->mtime;

       $r->setcontentlength()
           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 $r->file-
           name. This method is a bit faster and more concise than setting
           Content-length in the headersout table yourself.

              $r->setcontentlength;
              $r->setcontentlength(-s $r->finfo); #same as above
              $r->setcontentlength(-s $filename);

       $r->setetag()
           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 modi-
           fied. This string is tested by the meetsconditions() method if the
           client provide an If-Match or If-None-Match header.

              $r->setetag;

       $r->setlastmodified()
           This method is used to set the outgoing Last-Modified header from
           the value returned by $r->mtime. The method checks that the speci-
           fied time is not in the future. In addition, using setlastmodi-
           fied() is faster and more concise than setting Last-Modified in the
           headersout table yourself.

           You may provide an optional time argument, in which case the method
           will first call the updatemtime() to set the file's last modifica-
           tion date. It will then set the outgoing Last-Modified header as
           before.

              $r->updatemtime((stat $r->finfo)[9]);
              $r->setlastmodified;
              $r->setlastmodified((stat $r->finfo)[9]); #same as the two lines above

       $r->updatemtime()
           Rather than setting the request record mtime field directly, you
           can use the updatemtime() 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->filename.

              $r->updatemtime;
              $r->updatemtime((stat $r->finfo)[9]); #same as above
              $r->updatemtime(time);



perl v5.8.6                       2003-10-08                           File(3)