NAME

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

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.

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

A few functions have some additional warnings:

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.

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

chop

chop() works a little differently. Using it in void context is fine, but if it looks like you're using it to strip newlines it will throw a warning reminding you about chomp().

NOTE chop() was non-overridable before 5.7.0, so this feature will only work on that perl or newer.

dbmopen

dbmopen() will warn you if the hash argument you gave it already contains data.

open

NOT YET IMPLEMENTED

open() will warn you if you don't close its filehandle explicitly before the program ends. It will also warn if you give it an already open filehandle.

XXX I'd also like to have made sure $! is checked, but $! can't be usefully tied. :(

#'# # Waiting on postamble callbacks in Function::Override.

opendir

NOT YET IMPLEMENTED

Same as open().

CAVEATS

Because of the way perl compiles, the following code will produce a 'Name main::FILE used only once: possible typo' where it shouldn't.

use Dunce::Files;
open(FILE, $filename) or die $!;
print <FILE>;

Because open() is really Dunce::Files::open() and not the real open, Perl doesn't realize that FILE is the filehandle *FILE, so it thinks its only being used once.

Turns out this is a useful feature. If you close FILE the warning will go away, and you should have closed it in the first place.

TODO

Make a flag to have Dunce::Files die instead of just warning.

Complete Function::Override so I can finish open() and opendir().

AUTHOR

Michael G Schwern <schwern@pobox.com> with help from crysflame and Simon Cozens. Thanks to Jay A. Kreibich for the chop() idea.

SEE ALSO

Function::Override