perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/user/porting compat.pod
Date Fri, 02 Jul 2004 23:17:53 GMT
stas        2004/07/02 16:17:53

  Modified:    src/docs/2.0/api/Apache RequestIO.pod
               src/docs/2.0/user/porting compat.pod
  Log:
  complete Apache::RequestIO
  
  Revision  Changes    Path
  1.5       +294 -141  modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod
  
  Index: RequestIO.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestIO.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -u -r1.4 -r1.5
  --- RequestIO.pod	22 May 2004 02:03:27 -0000	1.4
  +++ RequestIO.pod	2 Jul 2004 23:17:53 -0000	1.5
  @@ -8,8 +8,20 @@
   =head1 Synopsis
   
     use Apache::RequestIO ();
  -
  -META: to be completed
  +  
  +  $rc = $r->discard_request_body();
  +  
  +  $r->print("foo", "bar");
  +  $r->puts("foo", "bar"); # same as print, but no flushing
  +  $r->printf("%s $d", "foo", 5);
  +  
  +  $r->read($buffer, $len);
  +  
  +  $r->rflush();
  +  
  +  $r->sendfile($filename);
  +  
  +  $r->write("foobartarcar", 3, 5);
   
   
   
  @@ -31,112 +43,142 @@
   
   =head2 C<discard_request_body>
   
  -META: Autogenerated - needs to be reviewed/completed
  -
   In HTTP/1.1, any method can have a body.  However, most GET handlers
   wouldn't know what to do with a request body if they received one.
  -This helper routine tests for and reads any message body in the request,
  -simply discarding whatever it receives.  We need to do this because
  -failing to read the request body would cause it to be interpreted
  -as the next request on a persistent connection.
  +This helper routine tests for and reads any message body in the
  +request, simply discarding whatever it receives.  We need to do this
  +because failing to read the request body would cause it to be
  +interpreted as the next request on a persistent connection.
   
  -  $ret = $r->discard_request_body();
  +  $rc = $r->discard_request_body();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$rc> ( integer )
   
  -error status if request is malformed, Apache::OK otherwise
  +C<L<APR::Const status constant|docs::2.0::api::APR::Const>> if request
  +is malformed, C<Apache::OK> otherwise.
  +
  +=item since: 1.99_10
   
   =back
   
  +Since we return an error status if the request is malformed, this
  +routine should be called at the beginning of a no-body handler, e.g.,
   
  +   use Apache::Const -compile => qw(OK);
  +   $rc = $r->discard_request_body;
  +   return $rc if $rc != Apache::OK;
   
   
   
  -=head2 C<setup_client_block>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -META: I think this method is deprecated along with other client_block
  -methods, use plain $r-E<lt>read() instead.
  +=head2 C<print>
   
  -Setup the client to allow Apache to read the request body.
  +Send data to the client.
   
  -  $ret = $r->setup_client_block($read_policy);
  +  $cnt = $r->print(@msg);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
   
  -The current request
  +=item arg1: C<@msg> ( ARRAY )
   
  -=item arg1: C<$read_policy> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +Data to send
   
  -How the server should interpret a chunked transfer-encoding. One of:
  +=item ret: C<$cnt> ( number )
   
  -    REQUEST_NO_BODY          Send 413 error if message has any body
  -    REQUEST_CHUNKED_ERROR    Send 411 error if body without Content-Length
  -    REQUEST_CHUNKED_DECHUNK  If chunked, remove the chunks for me.
  +How many bytes were sent (or buffered)
   
  -=item ret: C<$ret> (integer)
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
   
  -either OK or an error code
  +=item since: 1.99_10
   
   =back
   
  +The data is flushed only if STDOUT stream's C<$|> is true. Otherwise
  +it's buffered up to the size of the buffer, flushing only excessive
  +data.
   
   
   
   
  -=head2 C<should_client_block>
  +=head2 C<printf>
   
  -META: Autogenerated - needs to be reviewed/completed
  +Format and send data to the client (same as C<printf>).
   
  -META: I think this method is deprecated along with other client_block
  -methods, use plain $r-E<lt>read() instead.
  +  $cnt = $r->printf($format, @args);
   
  -Determine if the client has sent any data.  This also sends a
  -100 Continue response to HTTP/1.1 clients, so modules should not be called
  -until the module is ready to read content.
  +=over 4
   
  -  $ret = $r->should_client_block();
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
   
  -=over 4
  +=item arg1: C<$format> ( string )
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +Format string, as in the Perl core C<printf> function.
   
  -The current request
  +=item arg2: C<@args> ( ARRAY )
  +
  +Arguments to be formatted, as in the Perl core C<printf> function.
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$cnt> ( number )
   
  -0 if there is no message to read, 1 otherwise
  +How many bytes were sent (or buffered)
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_10
   
   =back
   
  +The data is flushed only if STDOUT stream's C<$|> is true. Otherwise
  +it's buffered up to the size of the buffer, flushing only excessive
  +data.
   
   
   
  -=head2 C<print>
   
  -Send data to the client.
  +=head2 C<puts>
  +
  +Send data to the client
   
  -  $ret = $r->print(@msg);
  +  $cnt = $r->puts(@msg);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item arg1: C<@msg> ( ARRAY )
  +
  +Data to send
   
  -=item arg1: C<@msg> (ARRAY)
  +=item ret: C<$cnt> ( number )
   
  -=item ret: C<$ret> (number)
  +How many bytes were sent (or buffered)
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_10
   
   =back
   
  +C<puts()> is similar to C<L<print()|/C_print_>>, but it won't attempt
  +to flush data, no matter what the value of STDOUT stream's C<$|>
  +is. Therefore assuming that STDOUT stream's C<$|> is true, this method
  +should be a tiny bit faster than C<L<print()|/C_print_>>, especially
  +if small strings are printed.
  +
  +
   
   
   
  @@ -144,26 +186,43 @@
   
   Read data from the client.
   
  -  $read_count = $r->read($buffer, $len, $offset);
  -
  -META: same as CORE::read, minus the filehandle argument
  +  $cnt = $r->read($buffer, $len);
  +  $cnt = $r->read($buffer, $len, $offset);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item arg1: C<$buffer> ( SCALAR )
  +
  +The buffer to populate with the read data
  +
  +=item arg2: C<$len> ( number )
   
  -=item arg1: C<$buffer> (scalar)
  +How many bytes to attempt to read
   
  -=item arg2: C<$len> (scalar)
  +=item opt arg3: C<$offset> ( number )
   
  -=item arg3: C<$offset> (number)
  +If a non-zero C<$offset> is specified, the read data will be placed at
  +that offset in the C<$buffer>.
   
  -=item ret: C<$read_count> (number)
  +META: negative offset and \0 padding are not supported at the moment
  +
  +=item ret: C<$cnt> ( number )
   
   How many characters were actually read
   
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_10
  +
   =back
   
  +This method shares a lot of similarities with the Perl core C<read()>
  +function. The main difference in the error handling, which is done via
  +C<L<APR::Error exceptions|docs::2.0::api::APR::Error>>
  +
   
   
   
  @@ -171,39 +230,74 @@
   
   Flush any buffered data to the client.
   
  -  $ret = $r->rflush();
  +  $r->rflush();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item ret: no return value
   
  -=item ret: C<$ret> (integer)
  +=item since: 1.99_15
   
   =back
   
  -Unless C<$|> E<gt> 0, data sent via C<L<$r-E<gt>print()|/C_print_>>
is
  -buffered. This method flushes that data to the client.
  +Unless STDOUT stream's C<$|> is false, data sent via
  +C<L<$r-E<gt>print()|/C_print_>> is buffered. This method flushes that
  +data to the client.
  +
   
   
   
   
   =head2 C<sendfile>
   
  -META: Autogenerated - needs to be reviewed/completed
  +Send a file or a part of it
   
  -  $ret = $r->sendfile($filename, $offset, $len);
  +  $rc = $r->sendfile($filename);
  +  $rc = $r->sendfile($filename, $offset);
  +  $rc = $r->sendfile($filename, $offset, $len);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item arg1: C<$filename> ( string )
  +
  +The full path to the file (using C</> on all systems)
  +
  +=item opt arg2: C<$offset> ( integer )
  +
  +Offset into the file to start sending.
  +
  +No offset is used if C<$offset> is not specified.
   
  -=item arg1: C<$filename> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item opt arg3: C<$len> ( integer )
   
  -=item arg2: C<$offset> (integer)
  +How many bytes to send.
   
  -=item arg3: C<$len> (integer)
  +If not specified the whole file is sent (or a part of it, if
  +C<$offset> if specified)
   
  -=item ret: C<$ret> (integer)
  +=item ret: C<$rc> ( C<L<APR::Const status
  +constant|docs::2.0::api::APR::Const>> )
  +
  +On success,
  +C<L<APR::SUCCESS|docs::2.0::api::APR::Const/C_APR__SUCCESS_>> is
  +returned.
  +
  +In case of a failure -- a failure code is returned, in which case
  +normally it should be returned to the caller.
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +Exceptions are thrown only when this function is called in the VOID
  +context. So if you don't want to handle the errors, just don't ask for
  +a return value and the function will handle all the errors on its own.
  +
  +=item since: 1.99_15
   
   =back
   
  @@ -213,218 +307,277 @@
   
   =head2 C<write>
   
  -META: Autogenerated - needs to be reviewed/completed
  -
  -Write data to the client
  +Send partial string to the client
   
  -  $ret = $r->write($buffer, $bufsiz, $offset);
  +  $cnt = $r->write($buffer);
  +  $cnt = $r->write($buffer, $len);
  +  $cnt = $r->write($buffer, $len, $offset);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>> )
  +
  +=item arg1: C<$buffer> ( SCALAR )
   
  -=item arg1: C<$buffer> (scalar)
  +The string with data
   
  -=item arg2: C<$bufsiz> (scalar)
  +=item opt arg2: C<$len> ( SCALAR )
   
  -=item arg3: C<$offset> (number)
  +How many bytes to send. If not specified, or -1 is specified, all the
  +data in C<$buffer> (or starting from C<$offset>) will be sent.
   
  -=item ret: C<$ret> (number)
  +=item opt arg3: C<$offset> ( number )
  +
  +Offset into the C<$buffer> string.
  +
  +=item ret: C<$cnt> ( number )
  +
  +How many bytes were sent (or buffered)
  +
  +=item excpt: C<L<APR::Error|docs::2.0::api::APR::Error>>
  +
  +=item since: 1.99_10
   
   =back
   
  +Examples:
   
  +Assuming that we have a string:
   
  +  $string = "123456789";
   
  -=head1 TIE Interface
  +Then:
   
  -=head2 C<OPEN>
  +  $r->write($string);
   
  -META: Autogenerated - needs to be reviewed/completed
  +sends:
   
  -  $ret = OPEN($self, $arg1, $arg2);
  +  123456789
   
  -=over 4
  +Whereas:
   
  -=item obj: C<$self> (scalar)
  +  $r->write($string, 3);
   
  -=item arg1: C<$arg1> (scalar)
  +sends:
   
  -=item arg2: C<$arg2> (scalar)
  +  123
   
  -=item ret: C<$ret> (integer)
  +And:
   
  -=back
  +  $r->write($string, 3, 5);
   
  +sends:
   
  -=head2 C<UNTIE>
  +  678
   
  -META: Autogenerated - needs to be reviewed/completed
  +Finally:
   
  +  $r->write($string, -1, 5);
   
  +sends:
   
  -  $ret = $r->UNTIE($refcnt);
  +  6789
   
  -=over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
   
  -=item arg1: C<$refcnt> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
   
  -=item ret: C<$ret> (scalar)
   
  -=back
   
   
   
  +=head1 TIE Interface
   
  +The TIE interface implementation. This interface is used for HTTP
  +request handlers, when running under C<L<SetHandler
  +perl-script|docs::2.0::user::config::config/C_perl_script_>> and
  +Perl doesn't have perlio enabled.
   
  -=head2 C<PRINTF>
  +See the I<perltie> manpage for more information.
   
  -META: Autogenerated - needs to be reviewed/completed
   
   
   
  -  $ret = PRINTF(...);
  +=head2 C<BINMODE>
   
   =over 4
   
  -=item obj: C<...> (scalar)
  -
  -=item ret: C<$ret> (number)
  +=item since: 1.99_10
   
   =back
   
  +NoOP
   
  +See the I<binmode> Perl entry in the I<perlfunc> manpage
   
   
   
   =head2 C<CLOSE>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=over 4
   
  -  $ret = $r->CLOSE();
  +=item since: 1.99_10
   
  -=over 4
  +=back
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +NoOP
   
  -=item ret: C<$ret> (scalar)
  +See the I<close> Perl entry in the I<perlfunc> manpage
   
  -=back
   
   
  +=head2 C<FILENO>
   
  +=over 4
   
  +=item since: 1.99_10
   
  -=head2 C<PRINT>
  +=back
   
  -META: Autogenerated - needs to be reviewed/completed
  +See the I<fileno> Perl entry in the I<perlfunc> manpage
   
   
   
  -  $ret = PRINT(...);
   
  -=over 4
  +=head2 C<GETC>
   
  -=item obj: C<...> (scalar)
  +=over 4
   
  -=item ret: C<$ret> (number)
  +=item since: 1.99_10
   
   =back
   
  +See the I<getc> Perl entry in the I<perlfunc> manpage
   
   
   
   
  -=head2 C<BINMODE>
  +=head2 C<OPEN>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=over 4
   
  +=item since: 1.99_10
   
  +=back
   
  -  $ret = $r->BINMODE();
  +See the I<open> Perl entry in the I<perlfunc> manpage
   
  -=over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
   
  -=item ret: C<$ret> (scalar)
   
  -=back
   
  +=head2 C<PRINT>
  +
  +=over 4
   
  +=item since: 1.99_10
   
  +=back
   
  +See the I<print> Perl entry in the I<perlfunc> manpage
   
  -=head2 C<WRITE>
   
  -META: Autogenerated - needs to be reviewed/completed
   
   
  -  $ret = $r->WRITE($buffer, $bufsiz, $offset);
  +=head2 C<PRINTF>
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item since: 1.99_10
   
  -=item arg1: C<$buffer> (scalar)
  +=back
   
  -=item arg2: C<$bufsiz> (scalar)
  +See the I<printf> Perl entry in the I<perlfunc> manpage
   
  -=item arg3: C<$offset> (integer)
   
  -=item ret: C<$ret> (integer)
  +
  +
  +=head2 C<READ>
  +
  +=over 4
  +
  +=item since: 1.99_10
   
   =back
   
  +See the I<read> Perl entry in the I<perlfunc> manpage
  +
   
   
   
   
   =head2 C<TIEHANDLE>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=over 4
  +
  +=item since: 1.99_10
  +
  +=back
   
  +See the I<tie> Perl entry in the I<perlfunc> manpage
   
   
  -  $ret = TIEHANDLE($stashsv, $sv);
  +
  +
  +=head2 C<UNTIE>
   
   =over 4
   
  -=item obj: C<$stashsv> (scalar)
  +=item since: 1.99_10
   
  -=item arg1: C<$sv> (scalar)
  +=back
   
  -=item ret: C<$ret> (scalar)
  +NoOP
  +
  +See the I<untie> Perl entry in the I<perlfunc> manpage
  +
  +
  +
  +
  +
  +=head2 C<WRITE>
  +
  +=over 4
  +
  +=item since: 1.99_10
   
   =back
   
  +See the I<write> Perl entry in the I<perlfunc> manpage
   
   
   
   
  -=head2 C<READ>
  +=head1 Deprecated API
   
  -META: Autogenerated - needs to be reviewed/completed
  +The following methods are deprecated, Apache plans to remove those in
  +the future, therefore avoid using them.
   
   
   
  -  $ret = $r->READ($buffer, $len, $offset);
  +=head2 C<get_client_block>
   
  -=over 4
  +This method is deprecated since the C implementation is buggy and we
  +don't want you to use it at all. Instead use the plain
  +C<L<$r-E<gt>read()|/C_read_>>.
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
   
  -=item arg1: C<$buffer> (scalar)
   
  -=item arg2: C<$len> (scalar)
   
  -=item arg3: C<$offset> (integer)
  +=head2 C<setup_client_block>
  +
  +This method is deprecated since
  +C<L<$r-E<gt>get_client_block|/C__get_client_block_>> is deprecated.
  +
  +
  +
  +
  +=head2 C<should_client_block>
  +
  +This method is deprecated since
  +C<L<$r-E<gt>get_client_block|/C__get_client_block_>> is deprecated.
   
  -=item ret: C<$ret> (scalar)
   
  -=back
   
   
   
  
  
  
  1.51      +11 -14    modperl-docs/src/docs/2.0/user/porting/compat.pod
  
  Index: compat.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/porting/compat.pod,v
  retrieving revision 1.50
  retrieving revision 1.51
  diff -u -u -r1.50 -r1.51
  --- compat.pod	22 May 2004 21:55:52 -0000	1.50
  +++ compat.pod	2 Jul 2004 23:17:53 -0000	1.51
  @@ -858,8 +858,7 @@
   =item *
   
   if one wishes to simply read POST data, there is the more modern
  -C<{setup,should,get}_client_block> API, and even more modern filter
  -API, along with continued support for C<read(STDIN, ...)> and
  +filter API, along with continued support for C<read(STDIN, ...)> and
   C<$r-E<gt>read($buf, $r-E<gt>headers_in-E<gt>{'content-length'}>)
   
   =back
  @@ -1019,8 +1018,9 @@
   
   =head2 C<$r-E<gt>send_fd>
   
  -Apache 2.0 provides a new method C<sendfile()> instead of C<send_fd>,
  -so if your code used to do:
  +mod_perl 2.0 provides a new method
  +C<L<sendfile()|docs::2.0::api::Apache::RequestIO/C_sendfile_>> instead
  +of C<send_fd>, so if your code used to do:
   
     open my $fh, "<$file" or die "$!";
     $r->send_fd($fh);
  @@ -1028,19 +1028,16 @@
   
   now all you need is:
   
  -  $r->sendfile($fh);
  +  $r->sendfile($file);
   
  -There is also a compatibility implementation in pure perl in
  -C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  +There is also a compatibility implementation of send_fd in pure perl
  +in C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
   
  +XXX: later we may provide a direct access to the real send_fd. That
  +will be possible if we figure out how to portably convert PerlIO/FILE
  +into apr_file_t (with help of apr_os_file_put, which expects a native
  +filehandle, so I'm not sure whether this will work on win32).
   
  -=head2 C<$r-E<gt>send_fd_length>
  -
  -currently available only in the 1.0 compatibility layer. The problem
  -is that Apache has changed the API and its functionality. See the
  -implementation in C<L<Apache::compat|docs::2.0::api::Apache::compat>>.
  -
  -XXX: needs a better resolution
   
   =head2 C<$r-E<gt>send_http_header>
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message