/ 
File-Locate-Iterator-9
River stage zero No dependents
/ File::Locate::Iterator

NAME

File::Locate::Iterator -- read "locate" database with an iterator

SYNOPSIS

use File::Locate::Iterator;
my $it = File::Locate::Iterator->new;
while (defined (my $entry = $it->next)) {
  print $entry,"\n";
}

DESCRIPTION

File::Locate::Iterator reads a "locate" database file in iterator style. Each next() call on the iterator returns the next entry from the database.

Locate databases normally hold filenames as a way of finding files faster than churning through directories on the filesystem. Optional glob, suffix and regexp options on the iterator let you restrict the entries returned.

Only "LOCATE02" format files are supported, per current versions of GNU locate, not the previous "slocate" format.

Iterators from this module are stand-alone, they don't need any of the various iterator frameworks. See Iterator::Locate and Iterator::Simple::Locate to inter-operate with those frameworks. The frameworks have the advantage of convenient ways to grep, map or manipulate iterated sequences.

FUNCTIONS

Constructor

$it = File::Locate::Iterator->new (key=>value,...)

Create and return a new locate database iterator object. The following optional key/value pairs are available.

database_file (string, default the system locate database)
database_fh (handle ref)

The file to read, either as filename or file handle. The default is the default_database_file below.

$it = File::Locate::Iterator->new
        (database_file => '/foo/bar.db');

A filehandle is read with the usual PerlIO, so it can come from various sources but should generally be in binary mode.

suffix (string)
suffixes (arrayref of strings)
glob (string)
globs (arrayref of strings)
regexp (string or regexp object)
regexps (arrayref of strings or regexp objects)

Restrict the entries returned to those with given suffix(es) or matching the given glob(s) or regexp(s). For example,

# C code files on the system, .c and .h
$it = File::Locate::Iterator->new
        (suffixes => ['.c','.h']);

If multiple patterns or suffixes are given then matches of any are returned.

Globs are in the style of the locate program, which means fnmatch with no options (see File::FnMatch) and the pattern must match the full entry, except a fixed string (none of "*", "?" or "[") can match anywhere.

use_mmap (string, default "if_sensible")

Whether to use mmap to access the database. This is fast and efficient when it's possible. To use mmap you must have the File::Map module, the file must fit in available address space, and for a database_fh handle there mustn't be any transforming PerlIO layers.

Setting default, undef or omitted means if_sensible. if_sensible uses mmap if available, if the size is reasonable, and for database_fh if it doesn't already have an :mmap layer. if_possible lifts those restrictions and uses mmap whenever it can be done. Setting 1 means use mmap or croak, and setting 0 means don't use mmap at all.

$it = File::Locate::Iterator->new
        (use_mmap => 'if_possible');

When multiple iterators access the same file they share the mmap. Only ordinary files are mapped by if_possible and if_sensible because generally the file size on char specials is not reliable. The size check in if_sensible counts space in all File::Locate::Iterator mappings and won't go beyond 1/5 of available data space (which is assumed to be (2^wordsize)/4 bytes). On a 32-bit system this means 200Mb.

Operations

$entry = $it->next

Return the next entry from the database, or no values at end of file. Recall that an empty return means undef in scalar context or no values in array context so you can loop with either

while (defined (my $filename = $it->next)) ...

or

while (my ($filename) = $it->next) ...

The return is a byte string since it's normally a filename and as of Perl 5.10 filenames are handled as byte strings.

$filename = File::Locate::Iterator->default_database_file

Return the default database file used for new above. This is meant to be the same as the locate program uses and currently means $ENV{'LOCATE_PATH'} if set, otherwise /var/cache/locate/locatedb. In the future it might be possible to check how findutils has been installed.

OTHER NOTES

On some systems mmap may be a bit too "efficient", giving a process more of the CPU than other processes making periodic system calls. This is an OS scheduling matter, but you might have to turn down the nice or ionice if doing a lot of mmapped work.

ENVIRONMENT VARIABLES

LOCATE_PATH

Default locate database.

FILES

/var/cache/locate/locatedb

Default locate database, if LOCATE_PATH environment variable not set.

OTHER WAYS TO DO IT

File::Locate reads a locate database with callbacks. Whether you prefer callbacks or an iterator is a matter of style. Iterators let you write your own loop and have multiple searches in progress simultaneously.

Iterators are good for cooperative coroutining like POE or Gtk where you must hold state in some sort of variable to be progressed by callbacks from the main loop. (next() waits while reading from the database, so the database generally should be a plain file rather than a socket or something, so as not to hold up a main loop.)

When File::Locate::Iterator is built with its XSUB code (requires Perl 5.10.0 or higher currently) the speed of an iterator is about the same as callbacks.

If you have the recommended mmap (File::Map module) then iterators share a map of the database file. If not then currently each holds a separate open handle to the database, which means a file descriptor and PerlIO buffering per iterator. Sharing a handle and making each seek to its desired position would be possible, but a seek drops buffered data and so would go slower. Some PerlIO trickery might transparently share an fd and have some multi-buffering.

SEE ALSO

File::Locate, Iterator::Locate, Iterator::Simple::Locate, locate(1) and the GNU Findutils manual, File::FnMatch, File::Map

HOME PAGE

http://user42.tuxfamily.org/file-locate-iterator/index.html

COPYRIGHT

Copyright 2009, 2010 Kevin Ryde

File-Locate-Iterator is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

File-Locate-Iterator is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with File-Locate-Iterator. If not, see http://www.gnu.org/licenses/