NAME

File::Find::Rule::Permissions - rule to match on file permissions and user access

SYNOPSIS

use File::Find::Rule::Permissions;

# Which files can the 'nobody' user read in the current directory?
@readable = File::Find::Rule::Permissions->file()
    ->permissions(isReadable => 1, user => 'nobody')
    ->in('.');
                
# Which files can UID 42 *not* read in the current directory?
@notreadable = File::Find::Rule::Permissions->file()
    ->permissions(isReadable => 0, user => 42)
    ->in('.');
                
# Find big insecurity badness!
@eek = File::Find::Rule::Permissions->permissions(
    isWriteable => 1,
    isExecutable => 1,
    user => 'nobody'
)->in('/web');

DESCRIPTION

An extension for File::Find::Rule to work with file permission bits and determine whether a given user can read, write or execute files.

METHODS

permissions

Takes at least one parameter and up to four. The mandatory parameter must be one of isReadable, isWriteable or isExecutable, which take values of 1 or 0 (actually true or false). Any of those three that are missing are ignored - ie, we match regardless of their truth or falsehood. A value of 1 means that we must only match files where the user can read/write/execute (as appropriate) the file, and a value of 0 means we must only match if the user can NOT read/write/execute the file. To supply none of these three is clearly an error, as it is equivalent to not caring what the permissions are, which is equivalent to seeing if the file exists, which File::Find::Rule already does quite nicely thankyouverymuch.

The 'user' parameter is optional. By default, we check access for the current effective userid, which is normally the user running the program. This can be changed using this parameter, which takes a numeric uid or a username. Note, however, that if the user running the program can't get at parts of the filesystem that the desired user can, the results will be incomplete.

The astute reader will have noticed that File::Find::Rule already handles some of these rules (checking permissions for the effective uid), but not for an arbitrary user. That this module can also check for the effective uid is more of a lucky accident that just falls out of the code when checking for any arbitrary user :-)

BUGS

I assume a Unix-a-like system, both when looking at file permissions, and when divining users' membership of groups. Patches for other systems are welcome.

We divine which groups a user belongs to when the module is loaded. If group membership changes underneath the program, incorrect results may be returned. I consider this to be Just Fine, given that most shells also have the same limitation.

FEEDBACK

I welcome constructive criticism. If you need to report a bug, it would be most helpful - and it'll get fixed quicker - if you include sufficient information for me to be able to replicate it consistently. Especially useful are test scripts which fail with the current implementation but should pass.

Please report bugs either by email or using http://rt.cpan.org/.

CVS

http://drhyde.cvs.sourceforge.net/viewvc/drhyde/perlmodules/File-Find-Rule-Permissions/

SEE ALSO

File::Find::Rule

AUTHOR, COPYRIGHT and LICENCE

Copyright 2003-2009 David Cantrell <david@cantrell.org.uk>

Based on code by Kate Pugh (File::Find::Rule::MP3Info) and Richard Clamp.

This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

CONSPIRACY

This module is also free-as-in-mason software.