NAME

PerlIO::Util - A selection of general PerlIO utilities

VERSION

This document describes PerlIO::Util version 0.60

SYNOPSIS

use PerlIO::Util;

# utility layers

open $in, '+<:flock', ...; # with flock(IN, LOCK_EX)

open $in, '+<:creat :excl', ...; # with O_CREAT | O_EXCL

open $out, '>:tee', 'file.txt', \$scalar, \*STDERR;
print $out 'foo'; # print to 'file.txt', $scalar and *STDERR

# utility routines

$fh = PerlIO::Util->open('<', $file); # it dies on fail

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

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

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.

See PerlIO::fse.

UTILITY METHODS

PerlIO::Util->open(mode, args)

Calls built-in open(), and returns an anonymous IO::Handle instance. 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, 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.