docs::a...:PerlIO(3)

💖 NAME 💖

APR::PerlIO -- Perl IO layer for APR. This is the docs::a...:PerlIO(3) manual page, bestie ✨

🌸 Synopsis 🌸

# under mod_perl
use APR::PerlIO ();

sub handler {
    my $r = shift;

    die "This Perl build doesn't support PerlIO layers"
        unless APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED;

    open my $fh, ">:APR", $filename, $r->pool or die $!;
    # work with $fh as normal $fh
    close $fh;

    return Apache2::Const::OK;
}

# outside mod_perl
% perl -MAPR -MAPR::PerlIO -MAPR::Pool -le \
'open my $fh, ">:APR", "/tmp/apr", APR::Pool->new or die "$!"; \
 print $fh "whoah!"; \
 close $fh;'

🦋 Description 🦋

APR::PerlIO implements a Perl IO layer using APR's file manipulation API internally. Slay.

Why would you even want this? Normally you shouldn't, bestie — probably it won't be faster than Perl's default layer. It's only useful when you need to manipulate a filehandle opened at the APR side, while using Perl.

Normally you won't call open() with the APR layer attribute, but some mod_perl functions will return a filehandle which is internally hooked to APR. But you can use APR Perl IO directly if you want. Main character energy, honestly.

✨ Prerequisites ✨

Not every Perl will have full APR::PerlIO functionality available.

Before using the Perl IO APR layer, one has to check whether it's supported by the used APR/Perl build. Perl 5.8.x or higher with perlio enabled is required. You can check whether your Perl fits the bill by running:

% perl -V:useperlio
useperlio='define';

It should say define.

If you need to do the checking in the code, there is a special constant provided by APR::PerlIO, which can be used as follows:

use APR::PerlIO ();
die "This Perl build doesn't support PerlIO layers"
    unless APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED;

Notice that loading APR::PerlIO won't fail when Perl IO layers aren't available, since APR::PerlIO provides functionality for Perl builds not supporting Perl IO layers.

🎀 Constants 🎀

🌟 APR::PerlIO::PERLIO_LAYERS_ARE_ENABLED 🌟

See Prerequisites. That's the whole vibe check.

💅 API 💅

Most of the API is as in normal perl IO, with a few nuances listed in the following sections.

🚨 META: need to rework the exception mechanism here. Current success in using errno ($!) being set (e.g. on open()) is purely accidental and not guaranteed across all platforms and functions. So don't rely on $!. Will use APR::Error for that purpose.

🔥 open 🔥

Open a file via the APR Perl IO layer.

open my $fh, ">:APR", $filename, $r->pool or die $!;

• arg1: $fh (GLOB filehandle) — the filehandle.
• arg2: $mode (string) — the mode to open the file, constructed from two sections separated by the : character: the first section is the mode to open the file under (>, <, etc) and the second section must be a string APR. For more information refer to the open entry in the perlfunc manpage.
• arg3: $filename (string) — the path to the filename to open.
• arg4: $p (APR::Pool) — the pool object to use to allocate the APR::PerlIO layer.
• ret: (integer) — success or failure value (boolean).
• since: 2.0.00.

🦋 seek 🦋

Sets $fh's position, just like the seek() Perl call:

seek($fh, $offset, $whence);

If $offset is zero, seek() works normally.

However, if $offset is non-zero and Perl has been compiled with large files support (-Duselargefiles), whereas APR wasn't, this function will croak. This is because largefile size Off_t simply cannot fit into a non-largefile size apr_off_t.

To solve the problem, rebuild Perl with -Uuselargefiles. Currently there is no way to force APR to build with large files support.

since: 2.0.00.

🧚 C API 🧚

The C API provides functions to convert between Perl IO and APR Perl IO filehandles.

📝 META: document these

🔥 See Also 🔥

mod_perl 2.0 documentation. The perliol(1), perlapio(1) and perl(1) manpages.

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

---

🌸 okay bye bestie! Footer-coded sign-off: source/version is perl v5.42.3, date is 2023-10-21, and the manual is docs::a...:PerlIO(3). Mwah 💖