mod_perl logo perl icon
previous page: Apache2::Process - Perl API for Apache process recordpage up: mod_perl 2.0 APInext page: Apache2::RequestRec - Perl API for Apache request record accessors

Apache2::RequestIO - Perl API for Apache request record IO






Practical mod_perl

Practical mod_perl

By Stas Bekman, Eric Cholet
The mod_perl Developer's Cookbook

The mod_perl Developer's Cookbook

By Geoffrey Young, Paul Lindner, Randy Kobes
mod_perl Pocket Reference

mod_perl Pocket Reference

By Andrew Ford
Writing Apache Modules with Perl and C

Writing Apache Modules with Perl and C

By Lincoln Stein, Doug MacEachern
Embedding Perl in HTML with Mason

Embedding Perl in HTML with Mason

By Dave Rolsky, Ken Williams
mod_perl2 User's Guide

mod_perl2 User's Guide

By Stas Bekman, Jim Brandt


Table of Contents

Synopsis

  use Apache2::RequestIO ();
  
  $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);


TOP

Description

Apache2::RequestIO provides the API to perform IO on the Apache request object.



TOP

API

Apache2::RequestIO provides the following functions and/or methods:



TOP

discard_request_body

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.

  $rc = $r->discard_request_body();

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 Apache2::Const -compile => qw(OK);
   $rc = $r->discard_request_body;
   return $rc if $rc != Apache2::Const::OK;


TOP

print

Send data to the client.

  $cnt = $r->print(@msg);

The data is flushed only if STDOUT stream's $| is true. Otherwise it's buffered up to the size of the buffer, flushing only excessive data.



TOP

printf

Format and send data to the client (same as printf).

  $cnt = $r->printf($format, @args);

The data is flushed only if STDOUT stream's $| is true. Otherwise it's buffered up to the size of the buffer, flushing only excessive data.



TOP

puts

Send data to the client

  $cnt = $r->puts(@msg);

puts() is similar to print(), but it won't attempt to flush data, no matter what the value of STDOUT stream's $| is. Therefore assuming that STDOUT stream's $| is true, this method should be a tiny bit faster than print(), especially if small strings are printed.



TOP

read

Read data from the client.

  $cnt = $r->read($buffer, $len);
  $cnt = $r->read($buffer, $len, $offset);

This method shares a lot of similarities with the Perl core read() function. The main difference in the error handling, which is done via APR::Error exceptions



TOP

rflush

Flush any buffered data to the client.

  $r->rflush();

Unless STDOUT stream's $| is false, data sent via $r->print() is buffered. This method flushes that data to the client.



TOP

sendfile

Send a file or a part of it

  $rc = $r->sendfile($filename);
  $rc = $r->sendfile($filename, $offset);
  $rc = $r->sendfile($filename, $offset, $len);


TOP

write

Send partial string to the client

  $cnt = $r->write($buffer);
  $cnt = $r->write($buffer, $len);
  $cnt = $r->write($buffer, $len, $offset);

Examples:

Assuming that we have a string:

  $string = "123456789";

Then:

  $r->write($string);

sends:

  123456789

Whereas:

  $r->write($string, 3);

sends:

  123

And:

  $r->write($string, 3, 5);

sends:

  678

Finally:

  $r->write($string, -1, 5);

sends:

  6789


TOP

TIE Interface

The TIE interface implementation. This interface is used for HTTP request handlers, when running under SetHandler perl-script and Perl doesn't have perlio enabled.

See the perltie manpage for more information.



TOP

BINMODE

NoOP

See the binmode Perl entry in the perlfunc manpage



TOP

CLOSE

NoOP

See the close Perl entry in the perlfunc manpage



TOP

FILENO

See the fileno Perl entry in the perlfunc manpage



TOP

GETC

See the getc Perl entry in the perlfunc manpage



TOP

OPEN

See the open Perl entry in the perlfunc manpage



TOP

PRINT

See the print Perl entry in the perlfunc manpage



TOP

PRINTF

See the printf Perl entry in the perlfunc manpage



TOP

READ

See the read Perl entry in the perlfunc manpage



TOP

TIEHANDLE

See the tie Perl entry in the perlfunc manpage



TOP

UNTIE

NoOP

See the untie Perl entry in the perlfunc manpage



TOP

WRITE

See the write Perl entry in the perlfunc manpage



TOP

Deprecated API

The following methods are deprecated, Apache plans to remove those in the future, therefore avoid using them.



TOP

get_client_block

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 $r->read().



TOP

setup_client_block

This method is deprecated since $r->get_client_block is deprecated.



TOP

should_client_block

This method is deprecated since $r->get_client_block is deprecated.



TOP

See Also

mod_perl 2.0 documentation.



TOP

Copyright

mod_perl 2.0 and its core modules are copyrighted under The Apache Software License, Version 2.0.



TOP

Authors

The mod_perl development team and numerous contributors.






TOP
previous page: Apache2::Process - Perl API for Apache process recordpage up: mod_perl 2.0 APInext page: Apache2::RequestRec - Perl API for Apache request record accessors