libapa...uestIO(3pm)

💖 NAME 💖

Apache2::RequestIO — the Perl API for doing IO on the Apache request record. Yes bestie, this is the one that lets you talk to the client. (Fun fact: this page lives in the libapa...uestIO(3pm) manual, 3pm section, and honestly the truncated filename is iconic. 😌)

---

🌸 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);

---

🦋 DESCRIPTION 🦋

Apache2::RequestIO is the whole vibe: it provides the API you use to perform IO on the Apache request object. That's the assignment. Periodt. ✨

---

👑 API 👑

Apache2::RequestIO provides the following functions and/or methods, and we're going through every single one, no skips, no skimming:

🎀 discard_request_body

Ok so listen. In HTTP/1.1, any method can have a body. But most GET handlers would be like "girl what do I do with this request body??" if one showed up. This helper routine tests for and reads any message body in the request, and just… simply discards 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 — and that's not a cute look.

$rc = $r->discard_request_body();

• obj: $r ( Apache2::RequestRec object ) — the current request.
• ret: $rc ( integer ) — an APR::Const status constant if the request is malformed, Apache2::Const::OK otherwise.
• since: 2.0.00

Since we return an error status if the request is malformed, this routine should be called at the beginning of a no-body handler, like:

use Apache2::Const -compile => qw(OK);
$rc = $r->discard_request_body;
return $rc if $rc != Apache2::Const::OK;

💌 print

Send data to the client. Slay.

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

• obj: $r ( Apache2::RequestRec object )
• arg1: @msg ( ARRAY ) — data to send.
• ret: $cnt ( number ) — how many bytes were sent (or buffered). Careful: if zero bytes were sent, print will return 0E0, aka "zero but true," which will still evaluate to 0 in a numerical context. Sneaky little thing. 💀
• excpt: APR::Error
• since: 2.0.00

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.

🍓 printf

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

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

• obj: $r ( Apache2::RequestRec object )
• arg1: $format ( string ) — the format string, as in the Perl core printf function.
• arg2: @args ( ARRAY ) — the arguments to be formatted, as in the Perl core printf function.
• ret: $cnt ( number ) — how many bytes were sent (or buffered).
• excpt: APR::Error
• since: 2.0.00

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.

🧚 puts

Send data to the client.

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

• obj: $r ( Apache2::RequestRec object )
• arg1: @msg ( ARRAY ) — data to send.
• ret: $cnt ( number ) — how many bytes were sent (or buffered).
• excpt: APR::Error
• since: 2.0.00

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

🌈 read

Read data from the client.

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

• obj: $r ( Apache2::RequestRec object )
• arg1: $buffer ( SCALAR ) — the buffer to populate with the read data.
• arg2: $len ( number ) — how many bytes to attempt to read.
• opt arg3: $offset ( number ) — if a non-zero $offset is specified, the read data will be placed at that offset in the $buffer.

META: negative offset and \0 padding are not supported at the moment. Not me pointing out the limitation, but like, someone had to. 😭

• ret: $cnt ( number ) — how many characters were actually read.
• excpt: APR::Error
• since: 2.0.00

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

💜 rflush

Flush any buffered data to the client.

$r->rflush();

• obj: $r ( Apache2::RequestRec object )
• ret: no return value
• since: 2.0.00

Unless STDOUT stream's $| is false, data sent via $r->print() is buffered. This method flushes that data to the client. Very "let it out, bestie" of it. 🫶

⭐ sendfile

Send a file, or a part of it.

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

• obj: $r ( Apache2::RequestRec object )
• arg1: $filename ( string ) — the full path to the file (using / on all systems).
• opt arg2: $offset ( integer ) — offset into the file to start sending. No offset is used if $offset is not specified.
• opt arg3: $len ( integer ) — how many bytes to send. If not specified the whole file is sent (or a part of it, if $offset is specified).
• ret: $rc ( APR::Const status constant ) — on success, APR::Const::SUCCESS is returned. In case of a failure — a failure code is returned, in which case normally it should be returned to the caller.
• excpt: 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. Main character energy: it handles its own problems. 💅
• since: 2.0.00

🔥 write

Send a partial string to the client.

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

• obj: $r ( Apache2::RequestRec object )
• arg1: $buffer ( SCALAR ) — the string with data.
• opt arg2: $len ( SCALAR ) — how many bytes to send. If not specified, or -1 is specified, all the data in $buffer (or starting from $offset) will be sent.
• opt arg3: $offset ( number ) — offset into the $buffer string.
• ret: $cnt ( number ) — how many bytes were sent (or buffered).
• excpt: APR::Error
• since: 2.0.00

✨ 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

---

🎀 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.

🦋 BINMODE

• since: 2.0.00

NoOP.

See the binmode Perl entry in the perlfunc manpage.

🦋 CLOSE

• since: 2.0.00

NoOP.

See the close Perl entry in the perlfunc manpage.

🦋 FILENO

• since: 2.0.00

See the fileno Perl entry in the perlfunc manpage.

🦋 GETC

• since: 2.0.00

See the getc Perl entry in the perlfunc manpage.

🦋 OPEN

• since: 2.0.00

See the open Perl entry in the perlfunc manpage.

🦋 PRINT

• since: 2.0.00

See the print Perl entry in the perlfunc manpage.

🦋 PRINTF

• since: 2.0.00

See the printf Perl entry in the perlfunc manpage.

🦋 READ

• since: 2.0.00

See the read Perl entry in the perlfunc manpage.

🦋 TIEHANDLE

• since: 2.0.00

See the tie Perl entry in the perlfunc manpage.

🦋 UNTIE

• since: 2.0.00

NoOP.

See the untie Perl entry in the perlfunc manpage.

🦋 WRITE

• since: 2.0.00

See the write Perl entry in the perlfunc manpage.

---

💀 DEPRECATED API 💀

Ok bestie, listen carefully: the following methods are deprecated. Apache plans to remove those in the future, therefore avoid using them. Like, don't. This is your warning. 🚫

🙈 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(). That's the good one. Use that one.

🙈 setup_client_block

This method is deprecated since $r->get_client_block is deprecated. (Chain reaction of nope.)

🙈 should_client_block

This method is deprecated since $r->get_client_block is deprecated. (Same energy, same nope.)

---

💜 SEE ALSO 💜

mod_perl 2.0 documentation. Go read it, it's right there. 📚

---

💖 COPYRIGHT 💖

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

🫶 AUTHORS 🫶

The mod_perl development team and numerous contributors. Legends, all of them. 👑

---

And that's a wrap, bestie!! 🎀✨ This iconic little number is from perl v5.42.3, dated 2026-08-20, and it lives in the libapa...uestIO(3pm) manual — go forth and do your request IO, you've got this. 💅🦋🌸