perl-modperl-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cho...@locus.apache.org
Subject cvs commit: modperl/File File.pm
Date Thu, 02 Mar 2000 01:57:46 GMT
cholet      00/03/01 17:57:46

  Modified:    .        Changes ToDo
               Apache   Apache.pm
               File     File.pm
  Log:
  Document Apache::File and $r->hostname
  Fixed a few typos along the way
  
  Revision  Changes    Path
  1.382     +12 -7     modperl/Changes
  
  Index: Changes
  ===================================================================
  RCS file: /home/cvs/modperl/Changes,v
  retrieving revision 1.381
  retrieving revision 1.382
  diff -u -r1.381 -r1.382
  --- Changes	2000/03/02 01:10:26	1.381
  +++ Changes	2000/03/02 01:57:44	1.382
  @@ -10,10 +10,15 @@
   
   =item 1.21_01-dev
   
  +$r->hostname now documented [Eric Cholet <cholet@logilune.com>]
  +
  +Apache::File methods are now documented 
  +[Eric Cholet <cholet@logilune.com>]
  +
   avoid quoting <Perl> config if args_how == RAW_ARGS
   thanks to Michael Schout for the spot
   
  -PerlPassEnv maintains it's value beyond the first request,
  +PerlPassEnv maintains its value beyond the first request,
   thanks to Chris Thorman for the spot
   
   prevent possible core dump in $r->pnotes if get_module_config returns
  @@ -656,7 +661,7 @@
   
   Apache::Log optimizations/enhancements:
     $r->log now invokes ap_log_rerror (w/ 1.3.2-dev+)
  -  ${r,s}->log->$method() will now accept a CODE ref as it's first
  +  ${r,s}->log->$method() will now accept a CODE ref as its first
     argument, which is only called when LogLevel >= $method
     caller() file/line info determined only if LogLevel >= debug
     avoid copy of message SV 
  @@ -849,7 +854,7 @@
   
   add some casts to avoid warnings from const char changes in 1.3.1-dev
   
  -write_client will break out of it's loop if rwrite returns a -1 error 
  +write_client will break out of its loop if rwrite returns a -1 error 
   condition, which could cause spinning httpds otherwise
   [Eric Eisenhart <eric@sonic.net>]
   
  @@ -898,7 +903,7 @@
   if $r->subprocess_env is called in a void context just call
   (void)perl_cgi_env_init(r)
   
  -$ENV{PATH}: don't let perl_clear_env() clear it's value
  +$ENV{PATH}: don't let perl_clear_env() clear its value
   
   prevent $r->dir_config SEGV if called during ChildInit, 
   spotted by Lincoln Stein
  @@ -1395,7 +1400,7 @@
   
   renamed eg/perlio.pl to eg/test.pl
   
  -moved SUPPORT section from INSTALL doc to it's own file
  +moved SUPPORT section from INSTALL doc to its own file
   
   fixed auto-set of $ServerRoot bug in Apache::httpd_conf
   
  @@ -1797,7 +1802,7 @@
   
   Apache::Status "Loaded Modules" item enhancements:
   -now shows file location
  --can click on module package for dump of it's symbol table
  +-can click on module package for dump of its symbol table
   -pretty table format
   
   don't add -I. to perl_startup() which may cause confusion spotted by
  @@ -2285,7 +2290,7 @@
   
   fix Apache::Status so it sends http headers!  spotted by Mike Stok
   
  -have cgi.t skip it's tests if CGI.pm is not installed, for Rob, the
  +have cgi.t skip its tests if CGI.pm is not installed, for Rob, the
   only person in the whole world who doesn't have CGI.pm installed ;-)
   
   s/make/$(MAKE)/ for 'make test_report' thanks to Tom Hughes 
  
  
  
  1.218     +0 -4      modperl/ToDo
  
  Index: ToDo
  ===================================================================
  RCS file: /home/cvs/modperl/ToDo,v
  retrieving revision 1.217
  retrieving revision 1.218
  diff -u -r1.217 -r1.218
  --- ToDo	2000/01/28 19:28:50	1.217
  +++ ToDo	2000/03/02 01:57:45	1.218
  @@ -28,8 +28,6 @@
   
   - fix t/httpd symlink logic ["Young, Geoffrey S." <younggs@acwilm.com>]
   
  -- document $r->hostname
  -
   - rename PerlSendHeader?
   
   - syswrite/WRITE
  @@ -37,8 +35,6 @@
   - sfio patch [Lupe Christoph <lupe@lupe-christoph.de>]
   
   - libapreq: Apache::Cookie format sync w/ CGI.pm
  -
  -- document Apache::File
   
   - think about making 'use Apache::Log ()' automatic
   
  
  
  
  1.41      +4 -0      modperl/Apache/Apache.pm
  
  Index: Apache.pm
  ===================================================================
  RCS file: /home/cvs/modperl/Apache/Apache.pm,v
  retrieving revision 1.40
  retrieving revision 1.41
  diff -u -r1.40 -r1.41
  --- Apache.pm	2000/02/20 14:59:50	1.40
  +++ Apache.pm	2000/03/02 01:57:45	1.41
  @@ -356,6 +356,10 @@
   that the client speaks.  Typical values will be "HTTP/1.0" or
   "HTTP/1.1".
   
  +=item $r->hostname
  +
  +Returns the server host name, as set by full URI or Host: header.
  +
   =item $r->request_time
   
   Returns the time that the request was made.  The time is the local unix
  
  
  
  1.6       +185 -0    modperl/File/File.pm
  
  Index: File.pm
  ===================================================================
  RCS file: /home/cvs/modperl/File/File.pm,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- File.pm	1999/06/08 06:30:53	1.5
  +++ File.pm	2000/03/02 01:57:46	1.6
  @@ -33,3 +33,188 @@
   
   1;
   __END__
  +
  +=head1 NAME
  +
  +Apache::File - advanced functions for manipulating files at the server side
  +
  +=head1 SYNOPSIS
  +
  +   use Apache::File ();
  +
  +=head1 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 HTTP/1.1 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 open() 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 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(">$out_file");
  +
  +   $fh->open("|$program");
  +
  +=item close() 
  +
  +The close() 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 tmpfile() method is responsible for opening up a unique temporary
  +file. It is similar to the tmpnam() function in the POSIX module, 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 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, tmpfile() calls the register_cleanup() 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 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 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 HTTP/1.1 protocol that provide
  +increased performance through client-side document caching.
  +
  +=over 4
  +
  +=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.
  +
  +   if ((my $rc = $r->discard_request_body) != OK) {
  +      return $rc;
  +   }
  +
  +=item $r->meets_conditions() 
  +
  +In the interest of HTTP/1.1 compliance, the meets_conditions() 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
  +HTTP_NOT_MODIFIED, 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->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 update_mtime() method is better
  +suited to this purpose.
  +
  +   my $date_string = localtime $r->mtime;
  +
  +=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 $r->filename. This
  +method is a bit faster and more concise than setting Content-length 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->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 meets_conditions() method if
  +the client provide an If-Match or If-None-Match header.
  +
  +   $r->set_etag;
  +
  +=item $r->set_last_modified() 
  +
  +This method is used to set the outgoing Last-Modified header from the
  +value returned by $r->mtime. The method checks that the specified time
  +is not in the future. In addition, using set_last_modified() is faster
  +and more concise than setting Last-Modified in the headers_out table
  +yourself.
  +
  +You may provide an optional time argument, in which case the method
  +will first call the update_mtime() to set the file's last modification
  +date. It will then set the outgoing Last-Modified 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->update_mtime() 
  +
  +Rather than setting the request record mtime field directly, you can
  +use the update_mtime() 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->update_mtime;
  +   $r->update_mtime((stat $r->finfo)[9]); #same as above
  +   $r->update_mtime(time);
  +
  +=cut
  
  
  

Mime
View raw message