Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
File::Cmp(3)	      User Contributed Perl Documentation	  File::Cmp(3)

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/>

SEE ALSO
       cmp(1), perlfunc, perlport, perlvar

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

COPYRIGHT AND LICENSE
       Copyright (C) 2013-2015 by Jeremy Mates

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

perl v5.32.1			  2015-02-03			  File::Cmp(3)

NAME | SYNOPSIS | DESCRIPTION | BUGS | HISTORY | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::Cmp&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help