CMP — Compare Text or Binary Files
User Guide for Release 5.23

Summary: CMP compares text or binary files (or groups of files) and report any differences. Output is suitable for piping, or processing by other programs. A value returned in ERRORLEVEL lets batch files take action based on whether files are the same or different.

See also: CMP Revision History
These documents are sometimes revised between software releases. You may want to check for revisions at <http://oakroadsystems.com/sharware/cmp.htm>.

Why CMP?

CMP works your way, much more than the DOS utilities comp and fc.

• CMP can compare text or binary files, or compare output from some program to a reference file.

• CMP comes in both 16-bit and 32-bit versions. The 32-bit version runs in 64-bit windows as well.

• CMP can compare multiple files, even entire subdirectory trees.

• CMP lets you configure virtually every aspect of the comparison process, including the lookahead depth and resync threshold, whether to treat A-Z and a-z as the same or different, whether to treat all runs of spaces as the same, and whether to ignore blank lines.

• CMP lets you configure most aspects of the output such as UNIX diff style or traditional style (line number on each line), width and formatting of line numbers, separators between line numbers and lines, whether to show differing lines from both files or just one, and the quantity of warning and diagnostic messages.

• CMP returns status values that can be useful in batch files or makefiles.

• CMP lets you store often-used options in an environment variable instead of typing them on the command line every time.

Getting Started

System Requirements

Use CMP32 with all 32-bit and 64-bit Windows versions, from Windows 95 through Windows 10. For legacy systems running DOS 2.0 through 7.0, use CMP16. It lacks support for long filenames, and has limited capacity for lookahead, but otherwise functions the same as CMP32.

TIP: Rename your preferred version (almost certainly CMP32.EXE) as CMP.EXE.

CMP handles text in 256-character sets like the ISO-8859 group, ANSI, and Windows-1252. It is not compatible with multibyte Unicode characters.

Installation and Demo

There is no special installation procedure. Simply move cmp16.exe cmp32.exe, or both to any convenient directory in your path. Each executable is completely self-contained. If installing on Windows XP, don’t fiddle with any compatibility settings: CMP runs fine with the XP defaults.

You may wish to rename the executable you use more often, cmp32.exe or cmp16.exe, to the simpler cmp.exe. All the examples in this user guide assume you’ve done that. Otherwise, just substitute cmp16 or cmp32 wherever you see cmp in the examples.

If you’d like to see a demo of CMP, change to the subdirectory containing the demo files and execute the batch program:

        cd demo
        demo

You need to have 100 KB or so free on your hard drive for temporary files that will be created. The files are automatically deleted when the demo finishes.

Evaluation, License, and Warranty

CMP is shareware. If you use it past a 30-day evaluation period, you are morally and legally bound to register and pay for it. Please see the file license.txt for full details, including support and warranty information.

The registered version offers some rewards:

• the /Q option to suppress various levels of non-essential output
• full directory tree searches with the /S option (The evaluation version searches only two levels.)
• the ability to store often-used options in an environment variable
• and, of course, no reminder to register

User Instructions

The basic command form is

        cmp options file(s) otherfile_or_directory

See Comparing Single Files and Comparing Groups of Files, below, for the principal variations on this basic form.

CMP normally lists differences on the screen, but you can send them to a file with normal DOS redirection (>reportfile). If you don’t want to see the differences at all, but just want CMP to test whether the files are the same, >NUL does that, or you can use the /Q3 or /Q4 option to get a one-line “report”.

Options can actually be specified anywhere on the command line, not just before the first filespec, and they can be stored in an environment variable. All options apply to all files, no matter where they appear on the command line

Filespecs may contain wild cards; see Comparing Groups of Files below. There are two special rules for filespecs that contain certain characters:

• If a filespec begins with a hyphen (-), CMP interprets it as an option. To prevent this, specify a file like –sleep as .\-sleep or ./-sleep instead. The period (.) is the standard DOS character for “current directory”.

  Exception to the exception: CMP recognizes a bare hyphen as meaning standard input; see Example 5 below.

• If a filespec contains spaces, remember that DOS requires you to enclose it in quotes.

For a summary of operating instructions and options, type

        cmp /? | more

Comparing Single Files

To compare one file to another:

        cmp [options] filespec1 filespec2 [>reportfile]

Each filespec can contain a drive letter of path. Either one (not both) can be - (a hyphen), indicating standard input; see Example 5 below.

Single Compare and Missing Files

If you’re comparing one specified file to another specified file — no wild cards, no subdirectory search — then CMP considers it an error if either one can’t be found. In that case, CMP displays an error message and stops.

Examples

Example 1: Compare two files in the current directory.

        cmp /w100 mywords.txt herwords.txt

Example 2: Compare mywords.txt in directory d:\ordinal to ourwords.txt in the current directory.

        cmp /w100 d:\ordinal\mywords.txt ourwords.txt

Example 3: Compare ferns.txt in the ordinal directory of disk d: to a file of the same name in the backup directory of the current disk. As you can see, when the two files have the same name, you need only type the file name once.

        cmp /w100 d:\ordinal\ferns.txt \backup

or

        cmp /w100 d:\ordinal\ferns.txt \backup\ferns.txt

Example 4: Compare lizard.cpp in the ordinal directory of disk d: to a file of the same name in the current directory of the current disk. Remember that “.” means “current directory” in DOS commands.

        cmp /w100 d:\ordinal\lizard.cpp .

or

        cmp /w100 d:\ordinal\lizard.cpp .\lizard.cpp

Example 5: Compare output of some program to a benchmark or reference file, using the - (hyphen) to stand for standard input:

        someprogram | cmp \path\reference.log -

Example 6: Locate the lines that are in updated but not in original, using the /J2* option, and write them to file diffs:

        cmp /J2* updated original >diffs

Comparing Groups of Files

To compare groups of files, specify only a disk and/or directory as the last filespec:

        cmp [options] [path\]files path [>reportfile]

When you’re comparing multiple files, only the first and last filespecs can have disk or path specified. CMP applies the first path to the other files automatically; see Example 3 below.

CMP tells you at the end how many comparisons it tried, broken down to file pairs the same, file pairs different, and files missing.

Wild Card Expansion

Please be aware that CMP16 and CMP32 expand wild cards slightly differently because CMP32 supports long filenames. Thus CMP32 would expand abc* to include all files, with any extension or none, whose names start with abc; with CMP16 you need abc*.* to get the same result. This matches the way commands like dir operate in a 32-bit command prompt versus traditional DOS.

When expanding wild cards, CMP considers hidden and system files for possible matches.

Multiple Compare and Missing Files

If you’re comparing multiple files, CMP processes the filespecs in order, comparing each one against any matching files in the other directory. If you used the /S option to search subdirectories, CMP matches all filespecs from the command line against each directory before moving on to the next subdirectory.

The question then arises, what to do about missing files? Consider this example, which compares all .htm and .css files in directory d:\a to their counterparts in directory d:\b:

        cmp d:\a\*.htm *.css d:\b 

That example will illustrate the two possibilities for missing files:

Class 1

File doesn’t exist in the first directory. In the above example, this problem occurs if there are no .css files in directory d:\a. Since you specified *.css, you probably want to know if there are no .css files at all, and CMP will tell you.

If you specified the /S option for subdirectory search, any particular subdirectory might lack matching files. CMP won’t tell you about each directory that has no *.css files, but if there aren’t any *.css files anywhere in the directory tree CMP will tell you that.

Class 2

File exists in the first directory but not the second. In the above example, suppose CMP finds files p.htm,q.htm, and r.htm in directory d:\a but only r.htm in directory d:\b. Then p.htm and q.htm are considered missing files from directory d:\b.

CMP tells you about each .htm file that’s in a but not in b.

Which types of missing files does CMP warn you about? By default you get warnings for both types; if you don’t want that information, use the /C option to suppress either type of warning, or both. (This is a change effective with CMP release 5.2. In earlier releases, CMP didn’t tell you about missing files unless you set an option to get that information. This resulted in confusion and questions from users, and therefore I’ve changed the default as indicated above.)

Where are warnings about missing files written? That depends on the /Q option and some additional factors. The following scheme may seem complex, but it developed in response to user requests:

• If you specified the /Q3 or /Q4 option, CMP writes “not found” messages only to standard output, stdout. This makes sense because with those options the result of every comparison of file pairs is a one-line message.
• If you specified the /Q2 option, CMP writes “not found” messages only to the standard error stream, stderr. Usually this means your screen, but some command processors let you redirect stderr. For instance, in the Windows XP command processor and in 4NT you can redirect the standard error stream to a file with 2>filename.
• If you didn’t specify the /Q2 option or higher, and neither stderr nor stdout is being redirected, then CMP writes warning messages about missing files to your screen via stderr.
• If you didn’t specify the /Q2 option or higher, and either stderr or stdout or both are being redirected, then CMP writes duplicate warning messages about missing files to stderr and stderr.

For even more information about every possible file match and mismatch, use the /D option and look for the lines beginning “cmp CF:”.

Examples

Example 1: Compare all files in the current directory with extension .txt to files of the same names in directory d:\other.

        cmp *.txt d:\other

Example 2: Compare three named files in the current directory to files of the same names in directory d:\placate.

        cmp sheep.txt goat.txt eland.txt d:\placate

Example 3: Compare the three named files in directory f:\first to files of the same name in directory second, a subdirectory of the current directory.

        cmp f:\first\sheep.txt goat.txt eland.txt second

Example 4: Compare all the .doc files in the current directory of drive a:, plus xx.htm in the current directory of drive a:, to files of the same names in the current directory of drive b:.

        cmp a:*.doc xx.htm b:

Example 5: Compare every file in the January directory to the same-named file in the February directory.

        cmp January February

CMP tells you about any file in the January directory that had no counterpart in the February directory. You can alter this behavior with the /C option if you don’t want those warning messages.

Overview: How CMP Compares Files

You can customize almost every aspect of CMP’s operation, but so many choices can be bewildering. This section gives you an overview of how CMP operates, so that you can understand the various options in context. There’s a lot here, so by all means feel free to skip right to the options when you’re first getting started.

Try playing around with the sample files alice1, alice2, and alice3 that are included in the demo subdirectory. Try comparing files with various options, and then look at the differences in results. The included demo.bat program shows you the effects of some options.

Hint: When you are comparing the output of CMP with different options, you can redirect the two runs to two different files and then use CMP itself to compare them. For example, to compare two files with and without the /E option, and see what difference it makes, you could do this:

        cmp alice1 alice2    >without
        cmp alice1 alice2 /e >with
        cmp with without | more

CMP Output

A good way to get an idea of what CMP does is to look at a typical output. Next to each section you’ll have commentary on that, explaining what it means and which options can modify it.

The input command I ran is

cmp32 cmp_opti* ../5.15 /2 /L,5 /W84

to compare cmp_opti source files from release 5.2 to those in an archive or internal “release” 5.15. Here’s how I chose my options:

• I always use the /2 option to ensure that file 1 is the older file and file 2 is the newer file.
• Usually I use the /L,2 option to set resync to 2 (see). However, for these particular files I found I got a shorter difference report by setting resync to 5. See The Resync Value.
• I normally leave the /W option (line width) at its default setting, but I’ve lowered it for this run to illustrate the truncation messages.

Here’s the annotated output:

cmp32 5.2           Copyright 2005  Oak Road Systems  http://oakroadsystems.com

Please buy the registered version at http://oakroadsystems.com/sharware/

** comparing (1) .\CMP_OPTI.H and (2) ..\5.15\CMP_OPTI.H

** Time: 0.0 s    Lines in file 1: 86   file 2: 86
** The files are identical.

** comparing (1) ..\5.15\CMP_OPTI.C and (2) .\CMP_OPTI.C

2.20>2005-10-30/5.16 A bare - is now a filename (stdin), not an option. The /R, /S,
2.21>                and /2 options aren't allowed with input from stdin.
2.22>2005-10-31/5.2  Default is now /C3 instead of /C0.
2.23>2005-11-06/5.2  Allow /Q2 with /U (why was it disallowed?).
2.24>                /2 with stdin is now a level-1 warning.

87,90c110,113
<     /* If /Q2 or higher then /U is irrelevant. */
<
<     if (op.quiet >= 2  &&  op.unix) {
<         swWrn(2, nugatory, "Q2 or Q3 or Q4", "U (UNIX output)");
---
>     /* If /Q3 or higher then /U is irrelevant. */
>
>     if (op.quiet >= 3  &&  op.unix) {
>         swWrn(2, nugatory, "Q3 or Q4", "U (UNIX output)");

2.205>    if (*opch == '-'  &&  opch[1] == '\0')
2.206>        return FALSE;

1.339>    op.complain = 0;
2.364>    op.complain = OptiMaxComplain;

cmp warning: ..\5.15\CMP_OPTI.C line 463: last 1 char chopped
cmp warning: .\CMP_OPTI.C line 488: last 1 char chopped

** Time: 0.0 s    Lines in file 1: 474   file 2: 499
** The files are significantly different (5+30 lines in 6 blocks)

** summary: 2 pairs compared -- same 1, different 1, missing 0

cmp warning: lines were truncated -- use /W85 for complete comparison

Thanks for trying cmp. Your feedback is very welcome! If you like cmp, please
buy it at http://oakroadsystems.com/sharware/ -- if it doesn’t meet your needs,
please write to support@oakroadsystems.com and tell us how we can improve it.

The Input Stage

After scanning the environment variable and the command line, CMP reserves computer memory as needed for the lookahead buffer, according to the values set by the /L option and the /W option. Then CMP begins reading lines from the (first) two files to be compared.

The /Wwidth option is important in reading files. For binary files, CMP reads chunks of width characters at a time. For text files, CMP reads a line at a time, but ignores the excess on any line that is longer than width characters. CMP lets you know about every such line; use the /Q1 option to suppress such warnings.

After reading each line of a text file, CMP immediately discards any spaces and tabs at the end. Therefore, if two lines are the same except that one of them has some trailing spaces or tabs and the other does not, CMP considers them to be the same. Those trailing spaces and tabs do count against the maximum width, however.

Empty lines are normally treated the same as any other lines, but you can use the/E option to tell CMP to discard empty or blank lines. In that case, they are ignored in comparison and don’t appear in difference reports. (They are still counted, so that line numbers in the output are be correct.)

“Massaged” Lines

Upon reading each line, CMP may store it in memory as it was read from the file, in a “massaged” form, or both. If the /I option is set, CMP massages the line by changing all letters A-Z to lower case. If the /B option is set (for text files), CMP massages the line by changing all runs of spaces and/or tabs to a single space. (If neither the /B option nor the /I option is set, there is no massaging of lines.) It is the massaged lines that CMP compares between files.

When lines are massaged, CMP normally stores both forms, so that the difference reports show the lines exactly as they were in the files. But if the /M option is set then CMP doesn’t save the original lines for display. In that case the difference reports show the massaged lines, but you have more memory available for lookahead. I recommend the /M option with CMP16, but not with CMP32.

Difference Blocks, Lookahead, and Resync

As long as corresponding lines from the two files are the same (after any massaging), CMP discards them and keeps reading. But when they don’t match, CMP recognizes the beginning of a difference block. Now CMP keeps reading lines trying to resynchronize the files.

The /Llookahead,resync option limits this lookahead procedure. CMP may accumulate up to lookahead lines from each file, trying to find lines that match again. CMP considers that it has resynchronized the files if resync consecutive lines are the same between the two.

An example may help clarify the significance of lookahead and resync. Suppose CMP finds, after the first 31 lines of the two files match, that line 32 of file 1 doesn’t match line 32 of file 2. In this case, CMP has to look ahead at line 33 of file 1 and line 33 of file 2.

              file 1               file 2
        ------------------   ------------------
        (two files identical to this point)
        (31) line d          (31) line d
        (32) line e          (32) something different
        (33) ??              (33) ??

Maybe the two lines 33 will match, or maybe line 32 of file 1 will match line 33 of file 2 (meaning that line 32 of file 2 is new in that file and doesn’t exist in file 1). Maybe there are 25 new lines in file 2, and line 32 of file 1 will match line 57 of file 2. CMP needs to keep looking ahead until it does find a match.

If CMP can’t resynchronize files within the specified lookahead depth (/L option), it displays the message

        cmp warning: lookahead lines (/L) from both files with no match

and then report the differing lines. Then it proceeds to the next files to be compared, if there are any. To avoid this message, run the comparison again with a higher lookahead value in the /L option.

The Resync Value

After a difference, finding just one line from file 1 that matches a line from file 2 may not be enough. This is where the resync value of the /L option comes in. CMP does not consider the two files resynchronized until that number of lines from the two files are the same.

The resync value affects the quality of difference reports, meaning how differences are grouped. CMP always finds all differences, but depending on your value of resync the comparison report from the same two files may be longer or shorter. Yes, CMP’s default is optimal in most situations, but it’s not even theoretically possible to set one value that is always best for all possible file pairs.

This is quite a long section. If you find yourself getting bored, you may prefer to skip it and simply try come compares, experimenting with different values for both numbers on the /L option. The supplied demo can help you explore this.

Here are two examples that show graphically what difference the resync value makes. By the way, CMP can report differences in traditional format or UNIX diff format, depending on the /U option. Example 1 shows traditional format, and Example 2 shows UNIX diff format.)

Example 1: Consider the lilies of the field, and this scenario:

             file 1                 file 2
        -----------------    -------------------
        (80) Four score       (90) Four score
        (81) and seven        (91) and seven
                              (92) (i.e., 87)
        (82) years ago,       (93) years ago,
        (83) our fathers      (94) somebody
        (84) brought forth    (95) brought forth
        (85) upon this        (96) on this
        (86) continent a      (97) continent a
        (87) new nation,      (98) mighty nation,
        (88) conceived in     (99) born in
        (89) liberty and     (100) liberty and
        (90) dedicated to    (101) dedicated to

As you can see, a number of edits have been made in this one paragraph of Lincoln’s famous speech. Do you want each edit reported as a separate difference, or would you prefer to see all the differences in a paragraph as one connected change?

With a resync value of 1 (the /L,1 option), each difference is reported separately, like this:

        2.92>(i.e., 87)

        1.83>our fathers
        2.94>somebody

        1.85>upon this
        2.96>on this

        1.87>new nation,
        1.88>conceived in
        2.98>mighty nation,
        2.99>born in

With resync = 1, as shown above, CMP sees that file 1 line 82 matches file 2 line 93, so it considers that difference block at an end; then one line later it starts a new difference block because file 1 line 83 is different from file 1 line 94.

But you might prefer that CMP not consider the files matched up again until it finds more than one consecutive matching line, like lines 89-90 and 100-101 in the above example — you want longer difference blocks but fewer of them. With resync set to 2 (the /L,2 option, which is CMP’s default), CMP reports a single connected series of edits on the above passage:

        1.82>years ago,
        1.83>our fathers
        1.84>brought forth
        1.85>upon this
        1.86>continent a
        1.87>new nation,
        1.88>conceived in
        2.92>(i.e., 87)
        2.93>years ago,
        2.94>somebody
        2.95>brought forth
        2.96>on this
        2.97>continent a
        2.98>mighty nation,
        2.99>born in 

Higher values of resync are allowed, but for the above passage higher values would have the same effect as resync = 2.

Which resync value is right? CMP sets resync = 2 by default, but which resync value is “right” depends on the specifics of the data. If CMP seems to be reporting a lot of differences for files that have clusters of changes like the above, you may find the report is more useful if you set a higher resync value with the /L option. But don’t make resync too large: you’ll slow CMP down without making the reports better. I recommend setting resync no higher than about 5.

CMP must be able to find resync identical lines within the lookahead limit. For instance, suppose you specify the /L option as /L10,2. That tells CMP to look ahead ten lines at a time, but of those ten lines two must resynchronize. That means that, with /L10,2, upon reading any difference block longer than 10-2 = 8 lines CMP gives up on those two files and moves on to the next files, if any.

If you need to reduce resync to 1 for some reason, you probably want to turn on the /E option as well. That prevents CMP from synchronizing on blank lines.

Example 2: Here’s an even clearer example of how resync can make a difference. The problem is especially likely to crop up if you have sections of text separated by blank lines, because then CMP resynchronizes on the blank lines instead of actual matching text. (Blank lines can be ignored by setting the /E option, but the same problem also applies to lines of dashes, the closing */ and } in C or C++ code, and so forth.)

Consider this excerpt:

             file 1                 file 2
        -----------------    -------------------
        (20) line A           (20) line A
        (21) end.             (21) end.
        (22) line B
        (23) end.
        (24) line D           (22) line D
        (25) line E           (23) line E
        (26) end.             (24) end.
        (27) line G           (25) line G
        (28) line H           (26) line H
        (29) end.             (27) end.
        (30) same after this  (28) same after this

As you see, file 1 lines 22-23 do not exist in file 2; otherwise the files are identical.

Suppose resync = 1. CMP sees that the two lines 22 don’t match and reads ahead to file 1 line 23 and file 2 line 24, which do match; so CMP reports a difference block of file 1 line 22 and file 2 lines 22-23. (This is illustrated immediately below this paragraph.) But now the next sections don’t match: file 1 lines 24-25 are different from file 2 lines 25-26. So CMP reports another difference, which ends at file 1 line 26 and file 2 line 27. Then there’s another mismatch, and so on right down the file. CMP never does resynchronize:

        22c22,23
        < line B
        ---
        > line D
        > line E
        24,25c25,26
        < line D
        < line E
        ---
        > line G
        > line H

and so on for a very long report from just one real difference.

With resync = 2, CMP recognizes that there is really only one difference. CMP doesn’t consider file 1 line 23 and file 2 line 24 as a match because resync = 2 requires two consecutive matching lines. So CMP keeps looking and finds that file 1 lines 24-25 match file 2 lines 22-23. For these particular files, CMP reports just one difference:

        22,23d21
        < line B
        < end.

For this particular pair of files, a resync value of 2 is definitely better. Other pairs of files may work best with a different resync, but 2 is usually a good first choice, which is why it’s CMP’s default.

Lookahead and Memory Use

The lookahead buffer uses your computer’s memory. CMP32 can use all memory including virtual memory, but CMP16 can use only DOS memory.

The lookahead buffer uses, in bytes, either roughly the lookahead value in the /L option times the width in the /W option, or double that product. Why double? If you set an option that causes input lines to be massaged, CMP stores two copies of each line, one massaged for comparison and one original for display in difference reports. In that case, you can free up memory for the lookahead buffer by setting the /M option (recommended for CMP16).

You don’t need to remember all this. If you exceed the available memory with the combined options, CMP displays a message suggesting you try lower values for the /L option or the /W option, or turn on the /M option if that would help.

Lookahead and Program Run Times

In a difference block, CMP has to compare each new line from each file with all the non-matching lines from the other file. This means that the number of compares grows as the square of the number of different lines, and therefore the program may run rather slowly on files that have very long difference blocks.

For instance, if you set /L2500, you are telling CMP that whenever it finds a difference between the two files, it should look ahead as far as 2500 lines in each file to try to resynchronize. If in fact the next 2499 lines of the two files are different, CMP performs roughly 2499² = over 6 million comparisons on that block alone. (The number of lines in the file is not an issue, just the number of consecutive lines that are actually different.) If you have files with long runs of differing lines, you can make CMP run faster by using a smaller lookahead value.

Reporting Difference Blocks

CMP normally reports each difference block to the screen; you can add >reportfile on the command line to send this output to a file instead. You have a number of options for modifying the output format.

Your biggest choice is between UNIX diff format and traditional format (both illustrated below and in the interactive demo). If you choose traditional format there are additional options for line numbers and separators.

For either format, if you choose to compress runs of white space with the /B option or to ignore case with the /I option, CMP normally displays the original lines in the difference blocks. To reduce use of computer memory, if that’s a problem, use the /M option. This tells CMP to display the “massaged” lines in difference reports, and frees up extra memory for a larger lookahead buffer.

UNIX diff format (the /U option) shows the lines without line numbers, but precedes each difference block with the numbers of the lines added, changed, or deleted, like this:

    1a2,5
    >                  SHERLOCK HOLMES
    >         THE ADVENTURE OF THE SPECKLED BAND
    >             by Sir Arthur Conan Doyle
    >
    8,10c12,14
    < the acquirement of wealth, he refused to associate
    < with any investigation which did not tend
    < towards the unusual, and even the fantastic. Of
    ---
    > the acquisition of wealth, he refused to associate
    > himself with any investigation which did not tend
    > toward the unusual, and even the fantastic. Of
    52,54d59
    <   "My dear fellow, I would not miss it for
    < anything."
    <

By contrast, the traditional CMP report form shows the differing lines from file 1 and file 2 with their line numbers, like this:

    2.2>                 SHERLOCK HOLMES
    2.3>        THE ADVENTURE OF THE SPECKLED BAND
    2.4>            by Sir Arthur Conan Doyle
    2.5>

    1.8>the acquirement of wealth, he refused to associate
    1.9>with any investigation which did not tend
    1.10>towards the unusual, and even the fantastic. Of
    2.12>the acquisition of wealth, he refused to associate
    2.13>himself with any investigation which did not tend
    2.14>toward the unusual, and even the fantastic. Of

    1.53>  "My dear fellow, I would not miss it for
    1.54>anything."
    1.55>

With the traditional report form, a block of added lines is shown by leading 2s with no leading 1s, changed lines have some of each, and deleted lines have leading 1s with no corresponding leading 2s.

You can customize the traditional report form in several ways:

• Line numbers are normally free format as shown above, but with the /F option you can left or right justify them in a fixed width.
• Line numbers are normally separated from the text of the lines by a greater-than sign (>), but with the /N option you can specify a string of up to six characters.
• The difference blocks are normally separated by blank lines, but the /Q2 option suppresses them.

Summary Report

After comparing each pair of files, CMP summarizes what it found for that pair. The message depends on whether differences were found, and also on what constraints were laid on the comparison by options. This section shows you all the possible summary messages.

The longer form of summary message appears if you didn’t set the /Q3 /Q4 option. This form is written to stderr if you specified the /Q2 option or the /J1* or /J2* option; otherwise it’s written to stdout.

In the longer form of summary message there are two lines, one for the elapsed time and line counts, one for the result of comparison and number of differences found. The first line (time and line counts) is suppressed if you set the /A option or the /Q1 option.

Here are the possibilities for the longer form (if the /Q3 or /Q4 option isn’t set):

** Time: 0.2 s    Lines in file 1: 120   file 2: 125
** The files are significantly different. (17+42 lines in 7 blocks)

** Time: 0.2 s    Lines in file 1: 120   file 2: 120
** The files are identical.

** Time: 0.2 s    Lines in file 1: 120   file 2: 124
** The files are effectively identical for the options chosen.

** Time: 0.1 s    Lines in file 1: 86   file 2: 86
** The files are effectively identical within the /W width.

** Time: 0.1 s    Lines in file 1: 86   file 2: 86
** The files are effectively identical for the options and /W width.

cmp warning: ..\5.15\demo\DEMO52.OUT not found in second directory

Registered users can set the /Q3 or /Q4 option, and then CMP will compress the “comparing” header and summary into a single line per file, suppressing difference blocks entirely. In this case, you’ll see one of the following messages:

different: CMP_OPTI/H and ..\5.15\CMP_OPTI.H
identical: CMP_OPTI/H and ..\5.15\CMP_OPTI.H
identical/massaged: CMP_OPTI/H and ..\5.15\CMP_OPTI.H
identical/truncated: CMP_OPTI/H and ..\5.15\CMP_OPTI.H
identical/truncated/massaged: CMP_OPTI/H and ..\5.15\CMP_OPTI.H
not found: ..\5.15\demo\DEMO52.OUT

These correspond to the cases above, depending on whether differences were found, the setting of the /B option, /E option, and /I option, and whether any lines in the file were longer than width characters (see the /W option). With the /Q4 option, CMP suppresses even the four types of “identical” messages, showing only the “different” and “not found” messages for the most compact output possible.

After processing all files in multiple compare, CMP writes one final über-summary of this form to stderr:

** summary: 2 pairs compared -- same 1, different 1, missing 0

Options

CMP’s operation can be modified by quite a number of options, either on the command line or in an environment variable.

Because there are a great many options, they are presented below both by category and alphabetically.

How to Specify Options

You have a lot of freedom about how you enter options:

• You can use a leading hyphen or slash.

• You can use upper- or lower-case letters. (This document always uses capital letters for the options, to make it easier to distinguish letter l and figure 1.)

• You can put options anywhere on the command line, before, among, or after the filespecs; or you can specify them in an environment variable.

• When specifying more than one option, you can leave spaces between options or combine them.

For instance, the following are just some of the different ways of turning on both the /W100 option and the /B option: /w100 /b, /w100-b, /w100/b, /w100B, -W100-B, -W100 /b.

Options by Category

(Some options are listed in multiple categories to make them easier to find.)

These options affect file input:

• Are you comparing binary files? Use the /R option.
• Use the /W option to specify the maximum line width for text files or the block size for binary files.
• With the /S option, you can compare entire directory trees.

These options affect the comparison process:

• When the files are different, the /L option tells CMP how far to look ahead to try to resynchronize them, and how stringent to be.
• You can ignore case with the /I option.
• You can compare only the first parts of text lines with the /W option.
• Want just the first few differences in each file? Use the /A option.
• If comparing text files, you can treat all runs of blanks and tabs as equal (/B option) and ignore blank lines (/E option).
• With the /2 option, CMP always arranges comparisons so that the newer file is file 2 and the older file is file 1.

These options affect output:

• You can select UNIX diff-style output in preference to CMP’s traditional format (/U option).
• With traditional output, you can control the formatting of line numbers (/F option) and the separator between line numbers and lines (/N option).
• To get only lines that are in one file but not the other, use the /J option.
• If comparing case blind or compressing strings of blanks, you can use the /M option to display difference lines as massaged, not as read from the files.
• You can suppress non-essential messages with the /Q option, or even restrict output to a single line per comparison. On the other hand, with the /D option you can get extra information about CMP’s operation and progress.

Finally, here are the general program options:

• The /Z option tells CMP to ignore any options that were set in the ORS_CMP environment variable.
• The /C option tells CMP to display warning messages when expected files are not found.
• With the /0 or /1 option, you control the status values sent to DOS or the command processor. You can test that return status in a makefile, or with if errorlevel in a batch file.
• Don’t have this user guide handy? Use the /? option for a summary of operating instructions for CMP.

Environment Variable

If you use certain options frequently, and you have the registered version of CMP, you can put them in the ORS_CMP environment variable. You have the same freedom with the format of options that you have on the command line: leading slashes or hyphens, space separation or options run together, caps or lower case.

You can use a SET command on the command line to set the environment variable temporarily for that session. For example:

        set ORS_CMP=/u /i 

In recent versions of Windows, to set an environment variable permanently, right-click Computer or This PC and select Properties, then Advanced system settings, then Environment Variables. Set the variable in the user list or the system list. This will be effective in any command windows that you open after setting the variable.

In DOS and older versions of Windows, you can make a permanent setting by including a SET command in your AUTOEXEC.BAT file.

CMP processes the environment variable before any command-line options, and therefore an option on the command line overrides the corresponding option in the environment variable.

The toggles, /2 /B /E /I /M /R /S /U, reverse their state every time you specify them. So if you usually want case-blind comparisons, put the /I option in the environment variable; then, if you want case-sensitive comparisons for a particular run, put the /I option on the command line to reverse the setting from the environment variable.

To alter the settings of other options, like the /L option and /F option, put the option on the command line with the new desired setting.

You may want to specify options without regard to what might be in the environment variable. To ensure this, put the /Z option first on the command line. I strongly recommend you do this in any batch files.

If you have any question which options are in effect, use /D option on the command line to display all option values.

Alphabetical List of Options

Here’s a quick hyperlink to each option:

?   0   1   2   A   B   C   D   E   F   I   J   L   M   N   Q   R   S   U   W   Z

/? — Show help

CMP displays a help message and option summary, then exits with no further processing.

You can redirect or pipe this information. For instance, you can display the help text one screen at a time by typing

        cmp /? | more

/0 and /1 — Select return values

Normally, CMP returns 0 in ERRORLEVEL if it finishes normally, whether it found any differences or not. These options let you control the values that CMP returns in ERRORLEVEL if the run finishes normally:

For more details, see Return Values, later in this user guide.

/2 — Compare old to new

With this option, CMP checks the date and time each file was last modified, and it considers the older file as file 1. This can be particularly helpful with diff-style output (the /U option), which reports lines added to or deleted from file 1 to make file 2.

CMP always displays the file names in the difference report, so you know which file is which.

Example:

        cmp /2 cat dog

If file cat was changed more recently than file dog, CMP makes dog file 1 for purposes of comparison, equivalent to

        cmp dog cat

Dependencies: The /2 option is ignored when comparing a file to - (standard input or stdin); the /Q2 option or higher suppresses the warning message.

/An — Stop after n difference blocks

With this option set, CMP stops reading each pair of files after reporting n difference blocks for that pair. If you expect some files to have lots of differences, you can use this option to limit the output and make CMP run faster.

If you just want to know whether files are the same or different without seeing the actual differences, use the /Q3 or /Q4 option, not the /A option. (When /Q3 or /Q4 option is set, any /A option is ignored and /A1 is implied.)

The parameter n limits the number of difference blocks reported, not the number of different lines, and it applies to each pair of files. Example:

        cmp code\*.cpp \bkup /A4

compares all .cpp files in the code subdirectory to files of the same names in the bkup root directory. CMP reports no more than 4 difference blocks between any one pair of files. This would be a good choice when you think most files are the same or nearly the same, but a few have lots of differences.

The default is to read every file to the end and report all difference blocks; that’s equivalent to /A0.

/B — Compress blanks and tabs

CMP compresses all runs of blanks and/or tabs in each line of a text file to a single blank, for purposes of comparison and display. With this option, CMP considers “a    b”, “a b”, “a{tab}b”, and “a  {tab} b” identical.

Runs of blanks and/or tabs are compressed to a single space, not completely removed. Thus CMP always considers “ab” (with no space between “a” and “b”) different from “a b” (any spaces or tabs between “a” and “b”). Carriage return and line feed are not compressed: in other words, blank and tab compression with the /B option operates only on runs of blanks and/or tabs within one line at a time.

Regardless of this option, CMP always ignores spaces and tabs at the ends of lines in text files. Some more details are given above in Overview: The Input Stage.

Dependencies: The /B option is ignored when the /R option (binary files) is set.

/C — Complain about missing files

CMP normally warns you about any missing files, but with the /C option you can fine tune which sorts of missing files CMP warns you about during multiple compares.

Caution: The default has changed, effective in release 5.2. The old default was /C0, a poor choice because CMP did nothing when users unknowingly mistyped a file name, and then they couldn’t understand why they got no output. The new default is /C3.

This option may have any of four values:

For more on missing files, including circumstances under which messages are written to stderr or stdout or both, please see Multiple Compare and Missing Files, earlier.

Dependencies: The /C option is meaningful only in multiple compare. By contrast, in single compare, a missing file is always an error since there is nothing for CMP to do.

/Dfile  or  /D-  or  /D — Display Debugging Output

Debugging information is very extensive, and includes whether you’re running CMP16 or CMP32, whether this program is registered, the contents of the environment variable, the values of all options specified or implied, the files specified, and details of every file scanned.

This information is normally suppressed, but you may find it helpful if CMP seems to behave in a way you don’t expect. Also if you report a problem I’ll ask to see the debugging output.

You can weed through the debugging output to some extent. CMP writes the following unique strings on most lines of output, so you can send debug output to a file and then grep the file for

• cmp CC: parsing the command line
• cmp CF: expanding directory and filespecs, including subdirectories
• cmp CM: memory usage
• cmp CP: comparison process
• cmp CQ: messages suppressed by the /Q option

The GREP utility from Oak Road Systems can be very helpful in scanning output.

/E — Ignore empty lines

With the /E option, CMP can do a much better job on some text files, because /E keeps CMP from resynchronizing on an empty line. Please see Example 2 in the overview. (Even if empty lines are ignored in the comparison, they’re still counted, so that line numbers are reported consistently.)

Without the /E option, CMP keeps track of blank lines and report added or deleted blank lines as differences.

A line is considered empty if it contains no characters at all, or contains only blanks and tabs.

Dependencies: The /E option is ignored when the /R option (binary files) is set.

/Fn  or  /F0n  or  /F-n — Fix the width of line numbers

With the /F option, CMP formats line numbers in a field of n columns (n ≤ 10) when reporting difference blocks. The /F option lets you ensure that reported difference lines all line up visually.

• /Fn and /F0n right justify the line numbers, filling unused positions with spaces and zeroes respectively.
• /F-n left justifies the line numbers.

n is a minimum field width, but the whole line number is always displayed. For example, if you specify /F4, /F04, or /F-4, line numbers for any differences in lines 1 through 9999 are justified in a four-character field. Any larger line numbers expand to the right, like this:

        /F4 output         /F04 output         /F-4 output
    1.  98>text1a      1.0098>text1a       1.98  >text1a
    2.  99>text1b      2.0099>text1b       2.99  >text1b
    2. 100>text1c      2.0100>text1c       2.100 >text1c

    1.2398>text2a      1.2398>text2a       1.2398>text2a
    2.2399>text2b      2.2399>text2b       2.2399>text2b

    1.234168>text3a    1.234168>text3a     1.234168>text3a
    1.234169>text3b    1.234169>text3b     1.234169>text3b
    2.234170>text3c    2.234170>text3c     2.234170>text3c

Without the /F option (or with plain /F0), CMP formats line numbers as however long they happen to be, with no padding. (You might wonder why CMP doesn’t just figure the necessary width on its own. To do that, CMP would have to read each file an extra time, just to count lines. That would slow the program down significantly.)

Dependencies: The /F option is ignored when you’ve set the /Q3 or /Q4 option (don’t display difference blocks) or the /Jfilenum* option (suppress line numbers).

/I — Ignore case

With this option set, CMP treats letters A-Z the same as a-z for comparison.

Because of limitations in the MSVC library, the /I option affects only the English letters A through Z. Accented or non-English lower-case letters are always considered different from the corresponding upper-case letters.

/Jfilenum* or /Jfilenum — Display difference lines from just one file

Normally CMP shows lines from both files in the difference report. If you want just the lines that are in file 1 but not file 2 (or vice versa), the /J option does the job. This can be very handy when piping lines to another program.

Here are the values of the /J option:

With a non-default /J option, the other options have their usual meanings. For instance, you can suppress empty lines with the /E option, stop comparing early with the /A option, and so forth.

The /L option does behave slightly differently. With the default or /J0 option, if a difference block is longer than the specified lookahead, CMP stops without reading the rest of the file. But with a non-default /J option, if a difference block is longer than lookahead lines, CMP reports those lines and then every line till the end of that file. For example, if you have /J1 /L200 and CMP finds a difference block of more than 200 lines, it reports those lines and every line from there to the end of file 1. You still see a warning message (unless you’ve specified the /Q1 option or higher), and can adjust the lookahead value in the /L option if this is an issue.

Dependencies:

With any /J option other than /J0, CMP ignores the /U option (UNIX output).

With the /J1* and /J2*, which suppress line numbers, CMP ignores the /F option and /N option, which set line number formats.

/Llookahead,resync  or  /Llookahead  or  /L,resync — Set lookahead

When a difference is found, CMP looks ahead as many as lookahead lines in each file to find where the files become the same again, and considers that the files are the same again only when resync lines from the two files are the same. (If the E option is set, empty lines don’t count against either resync or lookahead.) Please see the explanation and examples in Overview: Difference Blocks and Lookahead.

The default is /L20,2 in CMP16 and /L100,2 in CMP32. As the option forms above show, you can specify either resync or lookahead without changing the other.

resync can be 1 or greater. lookahead must be at least resync + 2 but may not exceed 32000 or available memory. Even if CMP and available memory let you set lookahead as large as 32000, values greater than a few hundred are not recommended. Please see the note on run times in the Overview.

/M — Save memory by displaying massaged lines

Normally you want the difference report to contain lines as they were formatted in the original files. But if your computer memory is scarce, set the /M option to tell CMP to use half as much memory. The tradeoff is that CMP then displays lines as they were massaged according to the /B option or /I option, not as they appear in the files.

This option is available in both CMP16 and CMP32, but isn’t really needed with CMP32 because virtual memory is available to the 32-bit program. It’s CMP16 that might have memory problems, depending on the lookahead value in the /L option.

CMP normally retains copies of the original lines from file for display in reporting difference blocks. This roughly doubles the computer memory needed used for the lookahead buffer, which could be a problem for CMP16. If you’re short on memory and you’re willing to see approximate versions of the original lines in the difference reports, by setting the /M option you increase the space available for lookahead.

Dependencies: The /M option has effect only if you have turned on the /B option or /I option or both and if you have not set the /Q3 or /Q4 option to suppress output of the difference blocks.

/Nstr — Set number separator

CMP separates line numbers from lines by str instead of the default > character when reporting difference blocks in traditional form.

You can specify a string of up to six characters; the string is terminated by the next space or tab. Don’t use quotes with this option unless you want them in the output.

If you want certain characters like =, |, <, or space in your separator, you can’t simply type them because DOS or the command prompt gives them special meanings. Use special “numeric escape sequences” to represent those characters in the /N option. For example, to make your output look like this:

        1. 98 : text1a
        2. 99 : text1b
        2.100 : text1c

        1.398 : text2a
        2.399 : text2b

use the sequence \32 to represent the space character. The entire command looks like this:

        cmp /N\32:\32 /F3 file1 file2

The numeric escape sequences are a backslash (\) followed by the numeric value of the character, up to three decimal digits. A leading 0 denotes octal; a leading 0x or 0X denotes hexadecimal. Here are some sample sequences:

The above are only examples: you can enter any character as a numeric sequence. For example, capital A would be \65, \0x41, or \0101.

Dependencies: The /N option is ignored when you’ve set the /U option (UNIX diff-style output), the /Jfilenum* option (suppress line numbers), or the /Q3 or /Q4 option (don’t display difference blocks).

/Qlevel — Set quietness level

(registered program only) Suppress some output that you may not want. Please see the Overview for discussion of the normal output from CMP. Please see the /C option for additional control on warning messages for missing files.

Caution: The /Q option hides diagnostic messages that you’ll actually want to see if there’s a problem. When your run of CMP doesn’t work as you expect, please remove the /Q option and try again — you may find an explanation of what’s wrong. In a batch file, I recommend you don’t use any level higher than /Q1 until you’ve established that your batch runs as expected.

    cmp /Q2 /F6 file1 file2 >report

/Q without a following number is normally the same as /Q1. The old /QQ option still works and is about the same as /Q2. For historical reasons, a plain /Q after any previous /Q option resets the quietness level to 0.

Dependencies: When /Q3 or /Q4 is set, the /A option and the /U option are ignored.

/R — Compare files as binary

CMP compares files in fixed-length blocks instead of variable-length lines; the block size is given by the /W option. This is useful for non-text files such as some word-processing files, spreadsheets, databases, and executable programs.

A text file has lines ending with carriage return (ASCII 13), line feed (ASCII 10), or both; and the first Control-Z (ASCII 26) marks the end of file. Also, a text file doesn’t contain any NUL characters (ASCII 0). Binary files, on the other hand, may have NUL and Control-Z characters in the middle, and often don’t have “lines” separated by anything.

DOS and Windows don’t mark files as binary or text, and therefore CMP has no way to know which a given file may be. By default it reads all files as text, but if you specify the R option then CMP reads all files as binary.

Your choice of text or binary mode also affects how CMP displays lines in difference blocks. In normal text mode, any differing lines are displayed as simple strings. Non-printing characters, like tab (ASCII 9) or Control-X (ASCII 24), are given no special treatment and appear just as the TYPE command displays them; thus screen output may appear strange if a text file contains non-printing characters. But in binary mode, non-printing characters are displayed using their numeric values in hex, such as <09> or <18>.

If all you care about is whether two binary files are the same or different, I recommend the /Q3 or /Q4 option to suppress the display of difference blocks, or the /A option to stop reporting after the first difference.

Dependencies:

When the /R option is set, the /B option and the /E option are ignored.

When comparing a file to - (stdin or standard input), you can’t use the /R option because stdin is always read as text.

/S — Compare subdirectories

After comparing the indicated files, CMP works down the subdirectory tree to compare matching files in subdirectories, including directories marked hidden or system. (The registered version of CMP travels all the way down; the evaluation version searches only two levels, the initial level and one level of subdirectories below that.)

The /S option is most useful with wild cards. Consider this example:

        cmp /s *.htm d:\new

Here CMP compares all .htm files in the current directory to files with the same names in directory d:\new. Then CMP works its way down all subdirectories below the current directory, and whenever it finds a corresponding file in a corresponding subdirectory under d:\new it compares them.

The first set of files need not be in the current directory. For example, suppose that you made a backup a couple of days ago. Since then you’ve edited a lot of files, and now you want to list all the changes you made. If the backup is rooted at directory janbkup on drive E:, and the current files are rooted at directory working on drive C:, you could use this command:

        cmp /s e:\janbkup\*.h *.cpp c:\working

Wherever there’s a .h or .cpp file in e:\janbkup or a subdirectory, such as e:\janbkup\westregn, CMP tries to compare it to a file of the same name the corresponding subdirectory (c:\working\westregn). Please see Multiple Compare and Missing Files for details of how CMP diagnoses missing files.

/U — Set UNIX diff-style output

CMP displays UNIX-style output, putting line numbers above each difference block with a letter for added, changed, or deleted. (Traditional CMP output displays the line number with each line.) Please see Overview: Reporting Difference Blocks for sample outputs, or run the interactive demo.

When selecting UNIX-style output, you probably want the /2 option also. The reports list added or deleted lines, but “added” and “deleted” make sense only if the first file is actually older.

The freeware Vim editor color-codes UNIX-style difference reports, if your terminal can display colors.

Dependencies:

When the /Q3 or /Q4 option or higher is set, the /U option is ignored.

When the /U option is set, the /N option is ignored.

/Wwidth — Set line or block width

CMP compares text lines only up to width characters or binary files in width-character blocks. The default width is 254 width can be 2 to 32764 in CMP16 and 2 to 2147483644 in CMP32. But the width is also limited by available memory; see Lookahead and Memory Use in the Overview.

Comparing text files

CMP examines each line only up to the specified width, and displays a warning message for any lines that exceed it. The /Q1 option or higher suppresses these line-by-line warnings.

In addition to the warning for each line, if any lines were truncated then CMP displays a single warning at the end of execution to tell you the longest line that was read from any file. Then you know the exact value to use with /W if you want to run CMP again and have it compare all lines to the end. The /Q3 or /Q4 option suppresses this summary warning.

If you want to predict the needed width for a given file, simply compare the file to itself with a small width value and the /Q1 option to suppress messages about individual lines, like this:

        cmp /Q1W10 file1 file1

Comparing binary files

CMP reads the files in chunks of width bytes and compares them. There is no question of truncation.

/Z — Reset all options

CMP disregards all options read up to this point. This can be useful in batch files, to make sure that the action of CMP is controlled only by the options on the command line, and not by any settings in the environment variable.

If you use the Z option on the command line, CMP disregards any options in the environment variable, as well as any preceding options on the command line.

The Z option is the only one whose effect can’t be reversed. If you use /Z more than once, CMP disregards the environment variable and all command-line options up through the last /Z.

Return Values (ERRORLEVEL)

By default, CMP returns one of the following values, which you can test with if errorlevel in a batch file or a makefile:

You might want to use CMP in a batch file or a makefile and take different actions depending on whether two files are the same or different. To do this, use the /0 or /1 option. The /1 option emulates UNIX diff by returning an error level of 1 if the files are different or 0 if they’re the same. /0 is the opposite: it returns 0 if the files are different or 1 if they’re the same. In other words, the /0 option or /1 option gives the value CMP should return if differences are found.

When comparing multiple files, the /1 option tells CMP to return an error level of 1 if any files compare as different, or 0 if all files compare as identical. The /0 option returns 0 if any files compare different, or 1 if all files compare identical. Missing files do not count as different, whether or not you have turned on warning messages for them.

Caution: if errorlevel tests whether ERRORLEVEL is greater than or equal to the specified number, not whether it’s equal. If you want to test for a specific error number, in later NT-based systems you can test a special environment variable:

if %errorlevel% == 1 ...

but in Windows 9x and earlier you must make two tests, one that ERRORLEVEL is greater than your target value (in which case you skip the next test) and one that it’s greater or equal. For instance, you test for an error level equal to 1 with these two lines:

if errorlevel 2 goto some_label

if errorlevel 1 ...

Full Table of Contents