NAME
PerlIO::Util - A selection of general PerlIO utilities
VERSION
This document describes PerlIO::Util version 0.21
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, @others;
print OUT "foo"; # print to $file and @others
# utility routines
STDOUT->push_layer(scalar => \my $s);
print "foo";
print STDOUT->pop_layer(); # => scalar
print $s; # => fooDESCRIPTION
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 are automatically loaded.
UTILITY LAYERS
:flock
The :flock layer provides an interface to flock().
It tries to lock the filehandle in open() (or binmode()) with flock() according to the open mode. That is, if a file is opened for writing, :flock attempts exclusive lock (using LOCK_EX). Otherwise, it attempts shared lock (using LOCK_SH).
It waits until the lock is granted. If an argument non-blocking (or LOCK_NB) is suplied, the call of open() fails when the lock cannot be granted.
For example:
# tries shared lock, or waits until the lock is granted
open IN, "<:flock", $file;
open IN, "<:flock(blocking)", $file; # ditto.
# tries shared lock, or returns undef
open IN, "<:flock(non-blocking)", $file;
open IN, "<:flock(LOCK_NB)", $file; # ditto.See "flock" in perlfunc.
:creat
:excl
They append O_CREAT or O_EXCL to the open flags.
When you'd like to create a file but not to truncate it, then you can use the :creat layer with the open mode '<' or '+<'.
open(IO, '+< :creat', $file);When you'd like to create a file only if it doesn't exist before, then you can use the :excl layer with the :creat layer and '<' or '+<'.
open(IO, '+< :excl :creat', $file);That is, it is used to emulate a part of sysopen() without Fcntl.
:tee
The :tee layer provides a multiplex output stream like tee(1) command. It is used to make a filehandle write to one or more files (or scalars via the :scalar layer) at the same time.
You can use push_layer() (defined in PerlIO::Util) to add a source to a filehandle. The source may be a file name, a scalar reference, or a filehandle. For example:
$fh->push_layer(tee => $file); # meaning "> $file"
$fh->push_layer(tee => ">>$file");# append mode
$fh->push_layer(tee => \$scalar); # via :scalar
$fh->push_layer(tee => \*OUT); # shallow copy, not duplicationYou can also use open() with multiple arguments. However, it is just a syntax sugar to call push_layer(): One :tee layer has a single extra filehandle, so arguments $x, $y, $z of open(), for example, prepares a filehandle with one basic layer and two :tee layers with a internal filehandle.
open my $tee, '>:tee', $x, $y, $z;
# the code above means:
# open my $tee, '>', $x;
# $tee->push_layer(tee => $y);
# $tee->push_layer(tee => $z);
$tee->get_layers(); # => "perlio", "tee($y)", "tee($z)"
$tee->pop_layer(); # "tee($z)" is popped
$tee->pop_layer(); # "tee($y)" is popped
# now $tee is a filehandle only to $x:dir
The :dir layer provides an interface to directories.
There is an important difference from Perl's readdir(). This layer appends a newline code, \n, to the end of the name, because readline() requires input separators. Call chomp() if necesary.
open my $dir, '<:dir', '.';
my @dirs = <$dir>; # readdir() but added "\n" at the end of the name
chomp @dirs; # if necessaryYou can call tell() and seek(), although there are some limits. seek() refuses SEEK_CUR and SEEK_END with a non-zero potition value. And tell() returns an integer that refuses any arithmetic operations.
my $pos = tell($dir); # telldir()
seek $dir, $pos, 0; # seekdir()
seek $dir, 0, 0; # rewinddir()
close $dir; # closedir()UTILITY METHODS
PerlIO::Util->open($mode, @args)
Calls built-in open(), and returns an anonymus 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])
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 poped 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
"flock" in perlfunc for :flock.
"sysopen" in perlfunc for :creat and :excl.
PerlIO for push_layer() and pop_layer().
perliol for implementation details.
AUTHOR
Goro Fuji (藤 吾郎) <gfuji (at) cpan.org>
LICENCE 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.