You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs-cvs@perl.apache.org by st...@apache.org on 2004/07/03 01:17:53 UTC
cvs commit: modperl-docs/src/docs/2.0/user/porting compat.pod
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