1CMP(1P)                    POSIX Programmer's Manual                   CMP(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       cmp — compare two files
13

SYNOPSIS

15       cmp [-l|-s] file1 file2
16

DESCRIPTION

18       The cmp utility shall compare two files. The cmp utility shall write no
19       output  if  the files are the same. Under default options, if they dif‐
20       fer, it shall write to standard output the  byte  and  line  number  at
21       which  the first difference occurred. Bytes and lines shall be numbered
22       beginning with 1.
23

OPTIONS

25       The cmp utility  shall  conform  to  the  Base  Definitions  volume  of
26       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
27
28       The following options shall be supported:
29
30       -l        (Lowercase ell.) Write the byte number (decimal) and the dif‐
31                 fering bytes (octal) for each difference.
32
33       -s        Write nothing to standard output or standard error when files
34                 differ;  indicate  differing  files through exit status only.
35                 It is unspecified whether a diagnostic message is written  to
36                 standard  error when an error is encountered; if a message is
37                 not written, the error is indicated through exit status only.
38

OPERANDS

40       The following operands shall be supported:
41
42       file1     A pathname of the first file to be compared. If file1 is '-',
43                 the standard input shall be used.
44
45       file2     A  pathname  of  the  second file to be compared. If file2 is
46                 '-', the standard input shall be used.
47
48       If both file1 and file2 refer to standard input or refer  to  the  same
49       FIFO special, block special, or character special file, the results are
50       undefined.
51

STDIN

53       The standard input shall be used only if the  file1  or  file2  operand
54       refers to standard input. See the INPUT FILES section.
55

INPUT FILES

57       The input files can be any file type.
58

ENVIRONMENT VARIABLES

60       The following environment variables shall affect the execution of cmp:
61
62       LANG      Provide  a  default  value for the internationalization vari‐
63                 ables that are unset or null. (See the Base Definitions  vol‐
64                 ume  of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
65                 ables for the precedence  of  internationalization  variables
66                 used to determine the values of locale categories.)
67
68       LC_ALL    If  set  to  a non-empty string value, override the values of
69                 all the other internationalization variables.
70
71       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
72                 bytes of text data as characters (for example, single-byte as
73                 opposed to multi-byte characters in arguments).
74
75       LC_MESSAGES
76                 Determine the locale that should be used to affect the format
77                 and contents of diagnostic messages written to standard error
78                 and informative messages written to standard output.
79
80       NLSPATH   Determine the location of message catalogs for the processing
81                 of LC_MESSAGES.
82

ASYNCHRONOUS EVENTS

84       Default.
85

STDOUT

87       In  the  POSIX  locale,  results  of the comparison shall be written to
88       standard output. When no options are used, the format shall be:
89
90
91           "%s %s differ: char %d, line %d\n", file1, file2,
92               <byte number>, <line number>
93
94       When the -l option is used, the format shall be:
95
96
97           "%d %o %o\n", <byte number>, <differing byte>,
98               <differing byte>
99
100       for each byte that differs. The first <differing byte> number  is  from
101       file1  while  the  second  is from file2.  In both cases, <byte number>
102       shall be relative to the beginning of the file, beginning with 1.
103
104       No output shall be written to standard output when  the  -s  option  is
105       used.
106

STDERR

108       The  standard  error shall be used only for diagnostic messages. If the
109       -l option is used and file1 and file2 differ in length, or  if  the  -s
110       option  is  not  used  and file1 and file2 are identical for the entire
111       length of the shorter file, in the POSIX locale the following  diagnos‐
112       tic message shall be written:
113
114
115           "cmp: EOF on %s%s\n", <name of shorter file>, <additional info>
116
117       The  <additional info>  field  shall  either  be  null or a string that
118       starts with a <blank> and contains no <newline> characters. Some imple‐
119       mentations report on the number of lines in this case.
120
121       If the -s option is used and an error occurs, it is unspecified whether
122       a diagnostic message is written to standard error.
123

OUTPUT FILES

125       None.
126

EXTENDED DESCRIPTION

128       None.
129

EXIT STATUS

131       The following exit values shall be returned:
132
133        0    The files are identical.
134
135        1    The files are different; this includes the case where one file is
136             identical to the first part of the other.
137
138       >1    An error occurred.
139

CONSEQUENCES OF ERRORS

141       Default.
142
143       The following sections are informative.
144

APPLICATION USAGE

146       Although  input  files to cmp can be any type, the results might not be
147       what would be expected on character special device  files  or  on  file
148       types  not  described  by the System Interfaces volume of POSIX.1‐2017.
149       Since this volume of POSIX.1‐2017 does not specify the block size  used
150       when  doing input, comparisons of character special files need not com‐
151       pare all of the data in those files.
152
153       For files which are not text files, line  numbers  simply  reflect  the
154       presence of a <newline>, without any implication that the file is orga‐
155       nized into lines.
156
157       Since the behavior of -s differs between implementations as to  whether
158       error  messages are written, the only way to ensure consistent behavior
159       of cmp when -s is used is to redirect standard error to /dev/null.
160
161       If error messages are wanted,  instead  of  using  -s  standard  output
162       should  be  redirected  to  /dev/null, and anything written to standard
163       error should be discarded if the exit status is 1. For example:
164
165
166           silent_cmp() {
167               # compare files with no output except error messages
168               message=$(cmp "$@" 2>&1 >/dev/null)
169               status=$?
170               case $status in
171               (0|1) ;;
172               (*) printf '%s\n' "$message" ;;
173               esac
174               return $status
175           }
176

EXAMPLES

178       None.
179

RATIONALE

181       The global language in Section 1.4, Utility Description Defaults  indi‐
182       cates  that  using  two  mutually-exclusive  options  together produces
183       unspecified results. Some System V implementations consider the  option
184       usage:
185
186
187           cmp -l -s ...
188
189       to be an error. They also treat:
190
191
192           cmp -s -l ...
193
194       as if no options were specified. Both of these behaviors are considered
195       bugs, but are allowed.
196
197       The word char in the  standard  output  format  comes  from  historical
198       usage,  even though it is actually a byte number. When cmp is supported
199       in other locales, implementations are encouraged to use the  word  byte
200       or  its equivalent in another language. Users should not interpret this
201       difference to indicate that the functionality of  the  utility  changed
202       between locales.
203
204       Some  implementations  report  on the number of lines in the identical-
205       but-shorter file case. This is allowed by the inclusion of  the  <addi‐
206       tional info>  fields  in the output format. The restriction on having a
207       leading <blank> and no <newline> characters is to make parsing for  the
208       filename easier. It is recognized that some filenames containing white-
209       space characters make parsing difficult  anyway,  but  the  restriction
210       does  aid  programs  used  on systems where the names are predominantly
211       well behaved.
212

FUTURE DIRECTIONS

214       Future versions of this standard may require that  diagnostic  messages
215       are written to standard error when the -s option is specified.
216

SEE ALSO

218       comm, diff
219
220       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment
221       Variables, Section 12.2, Utility Syntax Guidelines
222
224       Portions of this text are reprinted and reproduced in  electronic  form
225       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
226       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
227       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
228       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
229       event of any discrepancy between this version and the original IEEE and
230       The Open Group Standard, the original IEEE and The Open Group  Standard
231       is  the  referee document. The original Standard can be obtained online
232       at http://www.opengroup.org/unix/online.html .
233
234       Any typographical or formatting errors that appear  in  this  page  are
235       most likely to have been introduced during the conversion of the source
236       files to man page format. To report such errors,  see  https://www.ker
237       nel.org/doc/man-pages/reporting_bugs.html .
238
239
240
241IEEE/The Open Group                  2017                              CMP(1P)
Impressum