PerlIO::Util(3)

NAME
PerlIO::Util - A selection of general PerlIO utilities

VERSION
This document describes PerlIO::Util version 0.72.

SYNOPSIS
        use PerlIO::Util;

    # utility layers

        # open and flock(IN, LOCK_EX)
        $io = PerlIO::Util->open('+< :flock', $file);

        # open with O_CREAT | O_EXCL
        $io = PerlIO::Util->open('+<:creat :excl', $file);

    my $out = PerlIO::Util->open('>:tee', 'file.txt', \$scalar, \*STDERR);
    print $out 'foo'; # print to 'file.txt', $scalar and *STDERR

    # utility routines

    *STDOUT->push_layer(scalar => \$scalar); # it dies on fail
    print 'foo'; # to $scalar

    print *STDOUT->pop_layer(); # => scalar
    print $scalar; # to *STDOUT

DESCRIPTION
"PerlIO::Util" provides general PerlIO utilities: utility layers and utility methods.

Utility layers are a part of "PerlIO::Util", but you don't need to say "use PerlIO::Util" for loading them. They will be automatically loaded.

UTILITY LAYERS

  :flock
Easy interface to flock().

See PerlIO::flock.

  :creat
Use of O_CREAT without "Fcntl".

See PerlIO::creat.

  :excl
Use of O_EXCL without "Fcntl".

See PerlIO::excl.

  :tee
Multiplex output stream.

See PerlIO::tee.

  :dir
PerlIO interface to directory functions.

See PerlIO::dir.

  :reverse
Reverse input stream.

See PerlIO::reverse.

  :fse
Mediation of filesystem encoding.

This layer was split into an independent distribution, "PerlIO::fse".

See PerlIO::fse.

UTILITY METHODS

  PerlIO::Util->open(mode, args)
Calls built-in open(), and returns an "IO::Handle" instance named args. It dies on fail.

Unlike Perl's open() (nor "IO::File"'s), mode is always required.

  PerlIO::Util->known_layers( )
Returns the known layer names.

  FILEHANDLE->get_layers( )
Returns the names of the PerlIO layers on FILEHANDLE.

See "Querying the layers of filehandles" in PerlIO.

  FILEHANDLE->push_layer(layer [ => arg])
Almost equivalent to "binmode(FILEHANDLE, ':layer(arg)')", but accepts any type of arg, e.g. a scalar reference to the ":scalar" layer.

This method dies on fail. Otherwise, it returns FILEHANDLE.

  FILEHANDLE->pop_layer( )
Equivalent to "binmode(FILEHANDLE, ':pop')". It removes a top level layer from FILEHANDLE, but note that you cannot remove dummy layers such as ":utf8" or ":flock".

This method returns the name of the popped layer.

DEPENDENCIES
Perl 5.8.1 or later, and a C compiler.

BUGS
No bugs have been reported.

Please report any bugs or feature requests to <gfuji(at)cpan.org>, or through the web interface at <http://rt.cpan.org/>.

SEE ALSO
PerlIO::flock, PerlIO::creat, PerlIO::excl, PerlIO::tee, PerlIO::dir, PerlIO::reverse, PerlIO::fse.

PerlIO for push_layer() and pop_layer().

perliol for implementation details.

"open" in perlfunc.

perlopentut.

AUTHOR
Goro Fuji (藤 吾郎) <gfuji(at)cpan.org>.

LICENSE AND COPYRIGHT
Copyright (c) 2008-2010, Goro Fuji <gfuji(at)cpan.org>. Some rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.