view release on metacpan or  search on metacpan

lib/Dunce/Files.pm  view on Meta::CPAN

package Dunce::Files;

use strict;
use vars qw($VERSION @EXPORT);
$VERSION = '0.04';

use base qw(Exporter);

=pod

=head1 NAME

Dunce::Files - Protects against sloppy use of files.


=head1 SYNOPSIS

  use Dunce::Files;

  # open() warns you that you forgot to check if it worked.
  open(FILE, $filename);
  while( <FILE> ) {
      chop;     # chop() warns you to use chomp() instead
      print;
  }
  exit;

  # *FILE will warn you that you forgot to close it.


=head1 DESCRIPTION

One of the most common programming mistakes is failing to check if an
open() worked.  Same goes for other file and system operations.  The
world outside your program is a scary, unreliable place, and things
you try to do with it might not always work.

Dunce::Files makes trick versions of all file functions which do some
basic sanity checking.

If used in void context (ie. you didn't check to see if it worked),
they will throw a warning.  If the function returns a filehandle (like
open() and readdir()) that filehandle will complain if its never
closed, or if its never used.

This module is useful for automated code auditing.  Its also useful as
a dunce cap to place on junior programmers, make sure they're not
making silly mistakes.

The list of overridden functions is:

             chdir
             chmod
             chop
             chown
             chroot
             dbmopen
             flock
             link
             mkdir
             open
             opendir
             read
             rename
             rmdir
             seek
             seekdir
             symlink
             syscall
             sysseek
             system
             syswrite
             truncate
             unlink
             write

=cut

# Commonly abused file functions.
use vars qw(@File_Functions);
@File_Functions= qw(
                    chdir
                    chmod
                    chown
                    chroot
                    dbmopen
                    flock
                    link
                    mkdir
                    open
                    opendir
                    read
                    rename
                    rmdir
                    seek
                    seekdir
                    symlink
                    syscall
                    sysseek
                    syswrite
                    truncate
                    unlink
                    write
                   );
@EXPORT = (@File_Functions, 'chop');

use Function::Override;
use Carp;
foreach my $func (@File_Functions) {
    override($func, sub { 
                       my $wantarray = (caller(1))[5];
                       carp "You didn't check if $func() succeeded"
                         unless defined $wantarray;
                    }
            );
}


=pod

A few functions have some additional warnings:

=over 4

=item B<chmod>

Often, people will gratuitiously grant files more permissions than
they really need causing unnecessary security problems.  Making
non-program files executable is a common mistake.  Unnecessarily
giving world write permission is another.  Dunce::Files will throw a
warning if either is detected.

I<Note: It may be worthwhile to split this out into a seperate module>

=cut

override('chmod', 
         sub {
             my $mode = $_[0];
             carp "Don't make files executable without a good reason"
               if $mode & 0111;
             carp "Don't make files writable by others without a good reason"
               if $mode & 0003;