usr.bin/cmp/cmp.1

   1 .\" Copyright (c) 1987, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the Institute of Electrical and Electronics Engineers, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd September 23, 2021
  32 .Dt CMP 1
  33 .Os
  34 .Sh NAME
  35 .Nm cmp
  36 .Nd compare two files
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl l | s | x
  40 .Op Fl bhz
  41 .Op Fl -ignore-initial Ns Cm = Ns Ar num1 Ns Op :num2
  42 .Op Fl -bytes Ns Cm = Ns Ar num
  43 .Ar file1 file2
  44 .Op Ar skip1 Op Ar skip2
  45 .Sh DESCRIPTION
  46 The
  47 .Nm
  48 utility compares two files of any type and writes the results
  49 to the standard output.
  50 By default,
  51 .Nm
  52 is silent if the files are the same; if they differ, the byte
  53 and line number at which the first difference occurred is reported.
  54 .Pp
  55 Bytes and lines are numbered beginning with one.
  56 .Pp
  57 The following options are available:
  58 .Bl -tag -width indent
  59 .It Fl b , Fl -print-bytes
  60 Print each byte when a difference is found.
  61 .It Fl h
  62 Do not follow symbolic links.
  63 .It Fl i Ar num1 Ns Oo :num2 Oc , Fl -ignore-initial= Ns Ar num1 Ns Op :num2
  64 Skip
  65 .Ar num1
  66 bytes from
  67 .Ar file1 ,
  68 and optionally skip
  69 .Ar num2
  70 bytes from
  71 .Ar file2 .
  72 If
  73 .Ar num2
  74 is not specified, then
  75 .Ar num1
  76 is applied for both
  77 .Ar file1
  78 and
  79 .Ar file2 .
  80 .It Fl l , Fl -verbose
  81 Print the byte number (decimal) and the differing
  82 byte values (octal) for each difference.
  83 .It Fl n Ar num , Fl -bytes= Ns num
  84 Only compare up to
  85 .Ar num
  86 bytes.
  87 .It Fl s , Fl -silent , Fl -quiet
  88 Print nothing for differing files; return exit
  89 status only.
  90 .It Fl x
  91 Like
  92 .Fl l
  93 but prints in hexadecimal and using zero as index
  94 for the first byte in the files.
  95 .It Fl z
  96 For regular files compare file sizes first, and fail the comparison if they
  97 are not equal.
  98 .El
  99 .Pp
 100 The optional arguments
 101 .Ar skip1
 102 and
 103 .Ar skip2
 104 are the byte offsets from the beginning of
 105 .Ar file1
 106 and
 107 .Ar file2 ,
 108 respectively, where the comparison will begin.
 109 The offset is decimal by default, but may be expressed as a hexadecimal
 110 or octal value by preceding it with a leading ``0x'' or ``0''.
 111 .Pp
 112 .Ar skip1
 113 and
 114 .Ar skip2
 115 may also be specified with SI size suffixes.
 116 .Sh EXIT STATUS
 117 The
 118 .Nm
 119 utility exits with one of the following values:
 120 .Bl -tag -width 4n
 121 .It 0
 122 The files are identical.
 123 .It 1
 124 The files are different; this includes the case
 125 where one file is identical to the first part of
 126 the other.
 127 In the latter case, if the
 128 .Fl s
 129 option has not been specified,
 130 .Nm
 131 writes to standard error that EOF was reached in the shorter
 132 file (before any differences were found).
 133 .It >1
 134 An error occurred.
 135 .El
 136 .Sh EXAMPLES
 137 Assuming a file named
 138 .Pa example.txt
 139 with the following contents:
 140 .Bd -literal -offset indent
 141 a
 142 b
 143 c
 144 .Ed
 145 .Pp
 146 Compare stdin with
 147 .Pa example.txt :
 148 .Bd -literal -offset indent
 149 $ echo -e "a\\nb\\nc" | cmp - example.txt
 150 .Ed
 151 .Pp
 152 Same as above but introducing a change in the third byte of stdin.
 153 Show the byte number (decimal) and differing byte (octal):
 154 .Bd -literal -offset indent
 155 $ echo -e "a\\nR\\nc" | cmp -l - example.txt
 156      3 122 142
 157 .Ed
 158 .Pp
 159 Compare file sizes of
 160 .Pa example.txt
 161 and
 162 .Pa /boot/loader.conf
 163 and return 1 if they are not equal.
 164 Note that
 165 .Fl z
 166 can only be used with regular files:
 167 .Bd -literal -offset indent
 168 $ cmp -z example.txt /boot/loader.conf
 169 example.txt /boot/loader.conf differ: size
 170 .Ed
 171 .Pp
 172 Compare stdin with
 173 .Pa example.txt
 174 omitting the first 4 bytes from stdin and the first 2 bytes from
 175 .Pa example.txt :
 176 .Bd -literal -offset indent
 177 $ echo -e "a\\nR\\nb\\nc" | cmp - example.txt 4 2
 178 .Ed
 179 .Sh SEE ALSO
 180 .Xr diff 1 ,
 181 .Xr diff3 1
 182 .Sh STANDARDS
 183 The
 184 .Nm
 185 utility is expected to be
 186 .St -p1003.2
 187 compatible.
 188 The
 189 .Fl b ,
 190 .Fl h ,
 191 .Fl i ,
 192 .Fl n ,
 193 .Fl x ,
 194 and
 195 .Fl z
 196 options are extensions to the standard.
 197 .Ar skip1
 198 and
 199 .Ar skip2
 200 arguments are extensions to the standard.
 201 .Sh HISTORY
 202 A
 203 .Nm
 204 command appeared in
 205 .At v1 .
 206 .Sh BUGS
 207 The phrase
 208 .Dq SI size suffixes
 209 above refers to the traditional power of two convention, as described in
 210 .Xr expand_number 3 .