NAME

File::Cmp - compare two files character by character

SYNOPSIS

  use File::Cmp qw/fcmp/;

  print "identical" if fcmp("/tmp/foo", "/tmp/bar");

  fcmp(
    $fh1, $fh2,
    binmode   => ':raw',  # a good default
    fscheck   => 1,       # ... but beware network fs/portability
    RS        => \"4096"  # handy for binary
  );

Among other optional parameters.

DESCRIPTION

This module offers a fcmp function that checks whether the contents of two files are identical, in the spirit of the Unix cmp(1) utility. A single subroutine, fcmp, is offered for optional export. It expects at minimum two files or file handles, along with various optional parameters following those filenames. Any errors encountered will cause an exception to be thrown; consider "eval" or Try::Tiny to catch these. Otherwise, the return value will be true if the files are identical, false if not.

Note that if passed a file handle, the code will read to the end of the handle, and will not rewind. This will require "tell" and "seek" function calls before and after fcmp to return to the same position, if necessary. Likewise, if entire file contents are to be compared, file handles may need "SEEK_SET" performed on them to move to the beginning prior to the fcmp call. None of this is a concern if file names are passed instead of file handles.

"readline" calls are used on the filehandle. This means the usual "do not mix sys* and non-sys* calls on the same filehandle" advice applies for any passed filehandles. (See the "sysread" function perldocs for details in perlfunc.)

Available parameters include:

binmode

If set, applied as the "LAYER" specification of a "binmode" call performed on the files or file handles. ":raw" may very well likely be prudent for most cases, to avoid wasting time on linefeeds and encodings.

If the files need different "binmode" settings, for example if comparing irrespective of the linefeeds involved, do not set this option, and instead pass in the file handles with "binmode" already set as appropriate on those file handles.

fscheck

If set and true, perform "stat" tests on the input to check whether the device and inode numbers are identical. If so, this will avoid the need to check the file contents. This test may run afoul network filesystems or other edge cases possibly mentioned in perlport.

reason

A scalar reference that will be populated with a reason the files differ. Grep the source for what reasons are possible.

  my $msg = '';
  fcmp($f1, $f1, reason => \$msg);

reason will only be changed if the files differ, so may contain a stale value if the same scalar reference is used in multiple calls to fcmp.

RS

Input Record Separator value for $/, see the docs for such in perlvar. Binary file comparisons will likely benefit from the use of a fixed record size, as who knows how long the "lines" could be in such files.

sizecheck

If set and false, disables the default "-s" file size test on the input files. This will force the file contents to be checked, even if the files are of differing size (and thus stand a good chance of not being identical). (Sparse files (untested) or unknown unknowns prompt the inclusion of this knob.)

tells

An array reference that will be populated with the "tell" offsets of where the files differ. Enabling this parameter disables the sizecheck option, thus forcing inspection of the file contents.

  my @where;
  fcmp($f1, $f1, tells => \@where);

Will only be set if the files differ or EOF is encountered (perhaps check reason) and nothing else goes awry.

BUGS

No attempt at portability is made; in particular, this module assumes Unix file system semantics for the "fscheck" parameter.

Newer versions of this module may be available from CPAN. If the bug is in the latest version, check:

<http://github.com/thrig/File-Cmp>

HISTORY

As a historical note, there was an old File::Cmp module from 1996-10-21 that exported "cmp_file". That old interface is not replicated in this implementation, though would not be difficult to add, if necessary.

<http://backpan.perl.org/authors/id/J/JN/JNH/>

AUTHOR

thrig - Jeremy Mates (cpan:JMATES) "<jmates at cpan.org>"

COPYRIGHT AND LICENSE

This module is free software; you can redistribute it and/or modify it under the Artistic License (2.0).