Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
diff.html (34136B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>diff</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/df.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/dirname.html" accesskey="N">Next
19 >>></a></td>
20 </tr>
21 </table>
22 <hr align="left" width="100%"></div>
23 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
24 <center><font size="2">The Open Group Base Specifications Issue 8<br>
25 IEEE Std 1003.1-2024<br>
26 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
27 <hr size="2" noshade>
28 <a name="top" id="top"></a> <a name="diff" id="diff"></a> <a name="tag_20_34" id="tag_20_34"></a><!-- diff -->
29 <h4 class="mansect"><a name="tag_20_34_01" id="tag_20_34_01"></a>NAME</h4>
30 <blockquote>diff — compare two files</blockquote>
31 <h4 class="mansect"><a name="tag_20_34_02" id="tag_20_34_02"></a>SYNOPSIS</h4>
32 <blockquote class="synopsis">
33 <p><code><tt>diff</tt> <b>[</b><tt>-c|-e|-f|-u|-C</tt> <i>n</i><tt>|-U</tt> <i>n</i><b>] [</b><tt>-br</tt><b>]</b> <i>file1 file2</i></code></p>
34 </blockquote>
35 <h4 class="mansect"><a name="tag_20_34_03" id="tag_20_34_03"></a>DESCRIPTION</h4>
36 <blockquote>
37 <p>The <i>diff</i> utility shall compare the contents of <i>file1</i> and <i>file2</i> and write to standard output a list of
38 changes necessary to convert <i>file1</i> into <i>file2</i>. This list should be minimal. No output shall be produced if the files
39 are identical.</p>
40 </blockquote>
41 <h4 class="mansect"><a name="tag_20_34_04" id="tag_20_34_04"></a>OPTIONS</h4>
42 <blockquote>
43 <p>The <i>diff</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
44 Guidelines</i></a> .</p>
45 <p>The following options shall be supported:</p>
46 <dl compact>
47 <dd></dd>
48 <dt><b>-b</b></dt>
49 <dd>Cause any amount of white space at the end of a line to be treated as a single <newline> (that is, the white-space
50 characters preceding the <newline> are ignored) and other strings of white-space characters, not including <newline>
51 characters, to compare equal.</dd>
52 <dt><b>-c</b></dt>
53 <dd>Produce output in a form that provides three lines of copied context.</dd>
54 <dt><b>-C </b><i>n</i></dt>
55 <dd>Produce output in a form that provides <i>n</i> lines of copied context (where <i>n</i> shall be interpreted as a positive
56 decimal integer).</dd>
57 <dt><b>-e</b></dt>
58 <dd>Produce output in a form suitable as input for the <a href="../utilities/ed.html"><i>ed</i></a> utility, which can then be used
59 to convert <i>file1</i> into <i>file2</i>.</dd>
60 <dt><b>-f</b></dt>
61 <dd>Produce output in an alternative form, similar in format to <b>-e</b>, but not intended to be suitable as input for the
62 <a href="../utilities/ed.html"><i>ed</i></a> utility, and in the opposite order.</dd>
63 <dt><b>-r</b></dt>
64 <dd>Apply <i>diff</i> recursively to files and directories of the same name when <i>file1</i> and <i>file2</i> are both
65 directories.
66 <p>The <i>diff</i> utility shall detect infinite loops; that is, entering a previously visited directory that is an ancestor of the
67 last file encountered. When it detects an infinite loop, <i>diff</i> shall write a diagnostic message to standard error and shall
68 either recover its position in the hierarchy or terminate.</p>
69 </dd>
70 <dt><b>-u</b></dt>
71 <dd>Produce output in a form that provides three lines of unified context.</dd>
72 <dt><b>-U </b><i>n</i></dt>
73 <dd>Produce output in a form that provides <i>n</i> lines of unified context (where <i>n</i> shall be interpreted as a non-negative
74 decimal integer).</dd>
75 </dl>
76 </blockquote>
77 <h4 class="mansect"><a name="tag_20_34_05" id="tag_20_34_05"></a>OPERANDS</h4>
78 <blockquote>
79 <p>The following operands shall be supported:</p>
80 <dl compact>
81 <dd></dd>
82 <dt><i>file1</i>, <i>file2</i></dt>
83 <dd>A pathname of a file to be compared. If either the <i>file1</i> or <i>file2</i> operand is <tt>'-'</tt>, the standard input
84 shall be used in its place.</dd>
85 </dl>
86 <p>If both <i>file1</i> and <i>file2</i> are directories, <i>diff</i> shall not compare block special files, character special
87 files, or FIFO special files to any files and shall not compare regular files to directories. Further details are as specified in
88 <a href="#tag_20_34_10_01">Diff Directory Comparison Format</a> . The behavior of <i>diff</i> on other file types is
89 implementation-defined when found in directories.</p>
90 <p>If only one of <i>file1</i> and <i>file2</i> is a directory, <i>diff</i> shall be applied to the non-directory file and the file
91 contained in the directory file with a filename that is the same as the last component of the non-directory file.</p>
92 </blockquote>
93 <h4 class="mansect"><a name="tag_20_34_06" id="tag_20_34_06"></a>STDIN</h4>
94 <blockquote>
95 <p>The standard input shall be used only if one of the <i>file1</i> or <i>file2</i> operands references standard input. See the
96 INPUT FILES section.</p>
97 </blockquote>
98 <h4 class="mansect"><a name="tag_20_34_07" id="tag_20_34_07"></a>INPUT FILES</h4>
99 <blockquote>
100 <p>The input files may be of any type.</p>
101 </blockquote>
102 <h4 class="mansect"><a name="tag_20_34_08" id="tag_20_34_08"></a>ENVIRONMENT VARIABLES</h4>
103 <blockquote>
104 <p>The following environment variables shall affect the execution of <i>diff</i>:</p>
105 <dl compact>
106 <dd></dd>
107 <dt><i>LANG</i></dt>
108 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
109 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
110 variables used to determine the values of locale categories.)</dd>
111 <dt><i>LC_ALL</i></dt>
112 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
113 <dt><i>LC_CTYPE</i></dt>
114 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
115 opposed to multi-byte characters in arguments and input files).</dd>
116 <dt><i>LC_MESSAGES</i></dt>
117 <dd><br>
118 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and
119 informative messages written to standard output.</dd>
120 <dt><i>LC_TIME</i></dt>
121 <dd>Determine the locale for affecting the format of file timestamps written with the <b>-C</b> and <b>-c</b> options.</dd>
122 <dt><i>NLSPATH</i></dt>
123 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
124 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
125 "0"></dd>
126 <dt><i>TZ</i></dt>
127 <dd>Determine the timezone used for calculating file timestamps written with a context format. If <i>TZ</i> is unset or null, an
128 unspecified default timezone shall be used.</dd>
129 </dl>
130 </blockquote>
131 <h4 class="mansect"><a name="tag_20_34_09" id="tag_20_34_09"></a>ASYNCHRONOUS EVENTS</h4>
132 <blockquote>
133 <p>Default.</p>
134 </blockquote>
135 <h4 class="mansect"><a name="tag_20_34_10" id="tag_20_34_10"></a>STDOUT</h4>
136 <blockquote>
137 <h5><a name="tag_20_34_10_01" id="tag_20_34_10_01"></a>Diff Directory Comparison Format</h5>
138 <p>If both <i>file1</i> and <i>file2</i> are directories, the following output formats shall be used.</p>
139 <p>In the POSIX locale, each file that is present in only one directory shall be reported using the following format:</p>
140 <pre>
141 <tt>"Only in %s: %s\n", <</tt><i>directory pathname</i><tt>>, <</tt><i>filename</i><tt>>
142 </tt></pre>
143 <p>In the POSIX locale, subdirectories that are common to the two directories may be reported with the following format:</p>
144 <pre>
145 <tt>"Common subdirectories: %s and %s\n", <</tt><i>directory1 pathname</i><tt>>,
146 <</tt><i>directory2 pathname</i><tt>>
147 </tt></pre>
148 <p>For each file common to the two directories, if the two files are not to be compared: if the two files have the same device ID
149 and file serial number, or are both block special files that refer to the same device, or are both character special files that
150 refer to the same device, in the POSIX locale the output format is unspecified. Otherwise, in the POSIX locale an unspecified
151 format shall be used that contains the pathnames of the two files.</p>
152 <p>For each file common to the two directories, if the files are compared and are identical, no output shall be written. If the two
153 files differ, the following format is written:</p>
154 <pre>
155 <tt>"diff %s %s %s\n", <</tt><i>diff_options</i><tt>>, <</tt><i>filename1</i><tt>>, <</tt><i>filename2</i><tt>>
156 </tt></pre>
157 <p>where <<i>diff_options</i>> are the options as specified on the command line.</p>
158 <p>All directory pathnames listed in this section shall be relative to the original command line arguments. All other names of
159 files listed in this section shall be filenames (pathname components).</p>
160 <h5><a name="tag_20_34_10_02" id="tag_20_34_10_02"></a>Diff Binary Output Format</h5>
161 <p>In the POSIX locale, if one or both of the files being compared are not text files, it is implementation-defined whether
162 <i>diff</i> uses the binary file output format or the other formats as specified below. The binary file output format shall contain
163 the pathnames of two files being compared and the string <tt>"differ"</tt>.</p>
164 <p>If both files being compared are text files, depending on the options specified, one of the following formats shall be used to
165 write the differences.</p>
166 <h5><a name="tag_20_34_10_03" id="tag_20_34_10_03"></a>Diff Default Output Format</h5>
167 <p>The default (without <b>-e</b>, <b>-f</b>, <b>-c</b>, <b>-C</b>, <b>-u</b>, or <b>-U</b> options) <i>diff</i> utility output
168 shall contain lines of these forms:</p>
169 <pre>
170 <tt>"%da%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>
171 <br>
172 "%da%d,%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>>
173 <br>
174 "%dd%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>
175 <br>
176 "%d,%dd%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>>
177 <br>
178 "%dc%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>
179 <br>
180 "%d,%dc%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>>
181 <br>
182 "%dc%d,%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>>
183 <br>
184 "%d,%dc%d,%d\n", <</tt><i>num1</i><tt>>, <</tt><i>num2</i><tt>>, <</tt><i>num3</i><tt>>, <</tt><i>num4</i><tt>>
185 </tt></pre>
186 <p>These lines resemble <a href="../utilities/ed.html"><i>ed</i></a> subcommands to convert <i>file1</i> into <i>file2</i>. The
187 line numbers before the action letters shall pertain to <i>file1</i>; those after shall pertain to <i>file2</i>. Thus, by
188 exchanging <i>a</i> for <i>d</i> and reading the line in reverse order, one can also determine how to convert <i>file2</i> into
189 <i>file1</i>. As in <a href="../utilities/ed.html"><i>ed</i></a>, identical pairs (where <i>num1</i>= <i>num2</i>) are abbreviated
190 as a single number.</p>
191 <p>Following each of these lines, <i>diff</i> shall write to standard output all lines affected in the first file using the
192 format:</p>
193 <pre>
194 <tt>"<Δ%s", <</tt><i>line</i><tt>>
195 </tt></pre>
196 <p>and all lines affected in the second file using the format:</p>
197 <pre>
198 <tt>">Δ%s", <</tt><i>line</i><tt>>
199 </tt></pre>
200 <p>If there are lines affected in both <i>file1</i> and <i>file2</i> (as with the <b>c</b> subcommand), the changes are separated
201 with a line consisting of three <hyphen-minus> characters:</p>
202 <pre>
203 <tt>"---\n"
204 </tt></pre>
205 <h5><a name="tag_20_34_10_04" id="tag_20_34_10_04"></a>Diff -e Output Format</h5>
206 <p>With the <b>-e</b> option, a script shall be produced that shall, when provided as input to <a href=
207 "../utilities/ed.html"><i>ed</i></a>, along with an appended <b>w</b> (write) command, convert <i>file1</i> into <i>file2</i>. Only
208 the <b>a</b> (append), <b>c</b> (change), <b>d</b> (delete), <b>i</b> (insert), and <b>s</b> (substitute) commands of <a href=
209 "../utilities/ed.html"><i>ed</i></a> shall be used in this script. Text lines, except those consisting of the single character
210 <period> (<tt>'.'</tt>), shall be output as they appear in the file.</p>
211 <h5><a name="tag_20_34_10_05" id="tag_20_34_10_05"></a>Diff -f Output Format</h5>
212 <p>With the <b>-f</b> option, an alternative format of script shall be produced. It is similar to that produced by <b>-e</b>, with
213 the following differences:</p>
214 <ol>
215 <li>
216 <p>It is expressed in reverse sequence; the output of <b>-e</b> orders changes from the end of the file to the beginning; the
217 <b>-f</b> from beginning to end.</p>
218 </li>
219 <li>
220 <p>The command form <<i>lines</i>> <<i>command-letter</i>> used by <b>-e</b> is reversed. For example, 10<i>c</i> with
221 <b>-e</b> would be <i>c</i>10 with <b>-f</b>.</p>
222 </li>
223 <li>
224 <p>The form used for ranges of line numbers is <space>-separated, rather than <comma>-separated.</p>
225 </li>
226 </ol>
227 <h5><a name="tag_20_34_10_06" id="tag_20_34_10_06"></a>Diff -c or -C Output Format</h5>
228 <p>With the <b>-c</b> or <b>-C</b> option, the output format shall consist of affected lines along with surrounding lines of
229 context. The affected lines shall show which ones need to be deleted or changed in <i>file1</i>, and those added from <i>file2</i>.
230 With the <b>-c</b> option, three lines of context, if available, shall be written before and after the affected lines. With the
231 <b>-C</b> option, the user can specify how many lines of context are written. The exact format follows.</p>
232 <p>The name and last modification time of each file shall be output in the following format:</p>
233 <pre>
234 <tt>"*** %s %s\n", </tt><i>file1</i><tt>, <</tt><i>file1 timestamp</i><tt>>
235 "--- %s %s\n", </tt><i>file2</i><tt>, <</tt><i>file2 timestamp</i><tt>>
236 </tt></pre>
237 <p>Each <<i>file</i>> field shall be the pathname of the corresponding file being compared. The pathname written for standard
238 input is unspecified.</p>
239 <p>In the POSIX locale, each <<i>timestamp</i>> field shall be equivalent to the output from the following command:</p>
240 <pre>
241 <tt>date "+%a %b %e %T %Y"
242 </tt></pre>
243 <p>without the trailing <newline>, executed at the time of last modification of the corresponding file (or the current time,
244 if the file is standard input).</p>
245 <p>Then, the following output formats shall be applied for every set of changes.</p>
246 <p>First, a line shall be written in the following format:</p>
247 <pre>
248 <tt>"***************\n"
249 </tt></pre>
250 <p>Next, the range of lines in <i>file1</i> shall be written in the following format if the range contains two or more lines:</p>
251 <pre>
252 <tt>"*** %d,%d ****\n", <</tt><i>beginning line number</i><tt>>, <</tt><i>ending line number</i><tt>>
253 </tt></pre>
254 <p>and the following format otherwise:</p>
255 <pre>
256 <tt>"*** %d ****\n", <</tt><i>ending line number</i><tt>>
257 </tt></pre>
258 <p>The ending line number of an empty range shall be the number of the preceding line, or 0 if the range is at the start of the
259 file.</p>
260 <p>Next, the affected lines along with lines of context (unaffected lines) shall be written. Unaffected lines shall be written in
261 the following format:</p>
262 <pre>
263 <tt>"ΔΔ%s", <</tt><i>unaffected_line</i><tt>>
264 </tt></pre>
265 <p>Deleted lines shall be written as:</p>
266 <pre>
267 <tt>"-Δ%s", <</tt><i>deleted_line</i><tt>>
268 </tt></pre>
269 <p>Changed lines shall be written as:</p>
270 <pre>
271 <tt>"!Δ%s", <</tt><i>changed_line</i><tt>>
272 </tt></pre>
273 <p>Next, the range of lines in <i>file2</i> shall be written in the following format if the range contains two or more lines:</p>
274 <pre>
275 <tt>"--- %d,%d ----\n", <</tt><i>beginning line number</i><tt>>, <</tt><i>ending line number</i><tt>>
276 </tt></pre>
277 <p>and the following format otherwise:</p>
278 <pre>
279 <tt>"--- %d ----\n", <</tt><i>ending line number</i><tt>>
280 </tt></pre>
281 <p>Then, lines of context and changed lines shall be written as described in the previous formats. Lines added from <i>file2</i>
282 shall be written in the following format:</p>
283 <pre>
284 <tt>"+Δ%s", <</tt><i>added_line</i><tt>>
285 </tt></pre>
286 <h5><a name="tag_20_34_10_07" id="tag_20_34_10_07"></a>Diff -u or -U Output Format</h5>
287 <p>The <b>-u</b> or <b>-U</b> options behave like the <b>-c</b> or <b>-C</b> options, except that the context lines are not
288 repeated; instead, the context, deleted, and added lines are shown together, interleaved. The exact format follows.</p>
289 <p>The name and last modification time of each file shall be output in the following format:</p>
290 <pre>
291 <tt>"---Δ%s\t%s%sΔ%s\n", file1, <file1 timestamp>, <file1 frac>, <file1 zone>
292 "+++Δ%s\t%s%sΔ%s\n", file2, <file2 timestamp>, <file2 frac>, <file2 zone>
293 </tt></pre>
294 <p>Each <<i>file</i>> field shall be the pathname of the corresponding file being compared, or the single character
295 <tt>'-'</tt> if standard input is being compared. However, if the pathname contains a <tab> or a <newline>, or if it
296 does not consist entirely of characters taken from the portable character set, the behavior is implementation-defined.</p>
297 <p>Each <<i>timestamp</i>> field shall be equivalent to the output from the following command:</p>
298 <pre>
299 <tt>date '+%Y-%m-%dΔ%H:%M:%S'
300 </tt></pre>
301 <p>without the trailing <newline>, executed at the time of last modification of the corresponding file (or the current time,
302 if the file is standard input).</p>
303 <p>Each <<i>frac</i>> field shall be either empty, or a decimal point followed by at least one decimal digit, indicating the
304 fractional-seconds part (if any) of the file timestamp. The number of fractional digits shall be at least the number needed to
305 represent the file's timestamp without loss of information.</p>
306 <p>Each <<i>zone</i>> field shall be of the form <tt>"shhmm"</tt>, where <tt>"shh"</tt> is a signed two-digit decimal number
307 in the range -24 through +25, and <tt>"mm"</tt> is an unsigned two-digit decimal number in the range 00 through 59. It represents
308 the timezone of the timestamp as the number of hours (hh) and minutes (mm) east (+) or west (-) of UTC for the timestamp. If the
309 hours and minutes are both zero, the sign shall be <tt>'+'</tt>. However, if the timezone is not an integral number of minutes away
310 from UTC, the <<i>zone</i>> field is implementation-defined.</p>
311 <p>Then, the following output formats shall be applied for every set of changes.</p>
312 <p>First, the range of lines in each file shall be written in the following format:</p>
313 <pre>
314 <tt>"@@Δ-%sΔ+%sΔ@@", <file1 range>, <file2 range>
315 </tt></pre>
316 <p>Each <<i>range</i>> field shall be of the form:</p>
317 <pre>
318 <tt>"%1d", <beginning line number>
319 </tt></pre>
320 <p>or:</p>
321 <pre>
322 <tt>"%1d,1", <beginning line number>
323 </tt></pre>
324 <p>if the range contains exactly one line, and:</p>
325 <pre>
326 <tt>"%1d,%1d", <beginning line number>, <number of lines>
327 </tt></pre>
328 <p>otherwise. If a range is empty, its beginning line number shall be the number of the line just before the range, or 0 if the
329 empty range starts the file.</p>
330 <p>Next, the affected lines along with lines of context shall be written. Each non-empty unaffected line shall be written in the
331 following format:</p>
332 <pre>
333 <tt>"Δ%s", <unaffected_line>
334 </tt></pre>
335 <p>where the contents of the unaffected line shall be taken from <i>file1</i>. It is implementation-defined whether an empty
336 unaffected line is written as an empty line or a line containing a single <space> character. This line also represents the
337 same line of <i>file2</i>, even though <i>file2</i>'s line may contain different contents due to the <b>-b</b>. Deleted lines shall
338 be written as:</p>
339 <pre>
340 <tt>"-%s", <deleted_line>
341 </tt></pre>
342 <p>Added lines shall be written as:</p>
343 <pre>
344 <tt>"+%s", <added_line>
345 </tt></pre>
346 <p>The order of lines written shall be the same as that of the corresponding file. A deleted line shall never be written
347 immediately after an added line.</p>
348 <p>If <b>-U</b> <i>n</i> is specified, the output shall contain no more than 2<i>n</i> consecutive unaffected lines; and if the
349 output contains an affected line and this line is adjacent to up to <i>n</i> consecutive unaffected lines in the corresponding
350 file, the output shall contain these unaffected lines. <b>-u</b> shall act like <b>-U</b>3.</p>
351 </blockquote>
352 <h4 class="mansect"><a name="tag_20_34_11" id="tag_20_34_11"></a>STDERR</h4>
353 <blockquote>
354 <p>The standard error shall be used only for diagnostic messages.</p>
355 </blockquote>
356 <h4 class="mansect"><a name="tag_20_34_12" id="tag_20_34_12"></a>OUTPUT FILES</h4>
357 <blockquote>
358 <p>None.</p>
359 </blockquote>
360 <h4 class="mansect"><a name="tag_20_34_13" id="tag_20_34_13"></a>EXTENDED DESCRIPTION</h4>
361 <blockquote>
362 <p>None.</p>
363 </blockquote>
364 <h4 class="mansect"><a name="tag_20_34_14" id="tag_20_34_14"></a>EXIT STATUS</h4>
365 <blockquote>
366 <p>The following exit values shall be returned:</p>
367 <dl compact>
368 <dd></dd>
369 <dt> 0</dt>
370 <dd>No differences were found.</dd>
371 <dt> 1</dt>
372 <dd>Differences were found and all differences were successfully output.</dd>
373 <dt>>1</dt>
374 <dd>An error occurred.</dd>
375 </dl>
376 </blockquote>
377 <h4 class="mansect"><a name="tag_20_34_15" id="tag_20_34_15"></a>CONSEQUENCES OF ERRORS</h4>
378 <blockquote>
379 <p>Default.</p>
380 </blockquote>
381 <hr>
382 <div class="box"><em>The following sections are informative.</em></div>
383 <h4 class="mansect"><a name="tag_20_34_16" id="tag_20_34_16"></a>APPLICATION USAGE</h4>
384 <blockquote>
385 <p>If lines at the end of a file are changed and other lines are added, <i>diff</i> output may show this as a delete and add, as a
386 change, or as a change and add; <i>diff</i> is not expected to know which happened and users should not care about the difference
387 in output as long as it clearly shows the differences between the files.</p>
388 </blockquote>
389 <h4 class="mansect"><a name="tag_20_34_17" id="tag_20_34_17"></a>EXAMPLES</h4>
390 <blockquote>
391 <p>If <b>dir1</b> is a directory containing a directory named <b>x</b>, <b>dir2</b> is a directory containing a directory named
392 <b>x</b>, <b>dir1/x</b> and <b>dir2/x</b> both contain files named <b>date.out</b>, and <b>dir2/x</b> contains a file named
393 <b>y</b>, the command:</p>
394 <pre>
395 <tt>diff -r dir1 dir2
396 </tt></pre>
397 <p>could produce output similar to:</p>
398 <pre>
399 <tt>Common subdirectories: dir1/x and dir2/x
400 Only in dir2/x: y
401 diff -r dir1/x/date.out dir2/x/date.out
402 1c1
403 < Mon Jul 2 13:12:16 PDT 1990
404 ---
405 > Tue Jun 19 21:41:39 PDT 1990
406 </tt></pre></blockquote>
407 <h4 class="mansect"><a name="tag_20_34_18" id="tag_20_34_18"></a>RATIONALE</h4>
408 <blockquote>
409 <p>The <b>-h</b> option was omitted because it was insufficiently specified and does not add to applications portability.</p>
410 <p>Historical implementations employ algorithms that do not always produce a minimum list of differences; the current language
411 about making every effort is the best this volume of POSIX.1-2024 can do, as there is no metric that could be employed to judge the
412 quality of implementations against any and all file contents. The statement "This list should be minimal" clearly implies that
413 implementations are not expected to provide the following output when comparing two 100-line files that differ in only one
414 character on a single line:</p>
415 <pre>
416 <tt>1,100c1,100
417 all 100 lines from file1 preceded with "< "
418 ---
419 all 100 lines from file2 preceded with "> "
420 </tt></pre>
421 <p>The "Only in" messages required when the <b>-r</b> option is specified are not used by most historical implementations if the
422 <b>-e</b> option is also specified. It is required here because it provides useful information that must be provided to update a
423 target directory hierarchy to match a source hierarchy. The "Common subdirectories" messages are written by System V and 4.3 BSD
424 when the <b>-r</b> option is specified. They are allowed here but are not required because they are reporting on something that is
425 the same, not reporting a difference, and are not needed to update a target hierarchy.</p>
426 <p>The <b>-c</b> option, which writes output in a format using lines of context, has been included. The format is useful for a
427 variety of reasons, among them being much improved readability and the ability to understand difference changes when the target
428 file has line numbers that differ from another similar, but slightly different, copy. The <a href=
429 "../utilities/patch.html"><i>patch</i></a> utility is most valuable when working with difference listings using a context format.
430 The BSD version of <b>-c</b> takes an optional argument specifying the amount of context. Rather than overloading <b>-c</b> and
431 breaking the Utility Syntax Guidelines for <i>diff</i>, the standard developers decided to add a separate option for specifying a
432 context diff with a specified amount of context (<b>-C</b>). Also, the format for context <i>diff</i>s was extended slightly in 4.3
433 BSD to allow multiple changes that are within context lines from each other to be merged together. The output format contains an
434 additional four <asterisk> characters after the range of affected lines in the first filename. This was to provide a flag for
435 old programs (like old versions of <a href="../utilities/patch.html"><i>patch</i></a>) that only understand the old context format.
436 The version of context described here does not require that multiple changes within context lines be merged, but it does not
437 prohibit it either. The extension is upwards-compatible, so any vendors that wish to retain the old version of <i>diff</i> can do
438 so by adding the extra four <asterisk> characters (that is, utilities that currently use <i>diff</i> and understand the new
439 merged format will also understand the old unmerged format, but not <i>vice versa</i>).</p>
440 <p>The <b>-u</b> and <b>-U</b> options of GNU <i>diff</i> have been included. Their output format, designed by Wayne Davison, takes
441 up less space than <b>-c</b> and <b>-C</b> format, and in many cases is easier to read. The format's timestamps do not vary by
442 locale, so <i>LC_TIME</i> does not affect it. The format's line numbers are rendered with the <tt>%1d</tt> format, not <tt>%d</tt>,
443 because the file format notation rules would allow extra <blank> characters to appear around the numbers.</p>
444 <p>The substitute command was added as an additional format for the <b>-e</b> option. This was added to provide implementations
445 with a way to fix the classic "dot alone on a line" bug present in many versions of <i>diff</i>. Since many implementations have
446 fixed this bug, the standard developers decided not to standardize broken behavior, but rather to provide the necessary tool for
447 fixing the bug. One way to fix this bug is to output two periods whenever a lone period is needed, then terminate the append
448 command with a period, and then use the substitute command to convert the two periods into one period.</p>
449 <p>The BSD-derived <b>-r</b> option was added to provide a mechanism for using <i>diff</i> to compare two file system trees. This
450 behavior is useful, is standard practice on all BSD-derived systems, and is not easily reproducible with the <a href=
451 "../utilities/find.html"><i>find</i></a> utility.</p>
452 <p>The requirement that <i>diff</i> not compare files in some circumstances, even though they have the same name, is based on the
453 actual output of historical implementations. The specified behavior precludes the problems arising from running into FIFOs and
454 other files that would cause <i>diff</i> to hang waiting for input with no indication to the user that <i>diff</i> was hung. An
455 earlier version of this standard specified the output format more precisely, but in practice this requirement was widely ignored
456 and the benefit of standardization seemed small, so it is now unspecified. In most common usage, <i>diff</i> <b>-r</b> should
457 indicate differences in the file hierarchies, not the difference of contents of devices pointed to by the hierarchies.</p>
458 <p>Many early implementations of <i>diff</i> require seekable files. Since the System Interfaces volume of POSIX.1-2024 supports
459 named pipes, the standard developers decided that such a restriction was unreasonable. Note also that the allowed filename <b>-</b>
460 almost always refers to a pipe.</p>
461 <p>No directory search order is specified for <i>diff</i>. The historical ordering is, in fact, not optimal, in that it prints out
462 all of the differences at the current level, including the statements about all common subdirectories before recursing into those
463 subdirectories.</p>
464 <p>The message:</p>
465 <pre>
466 <tt>"diff %s %s %s\n", <</tt><i>diff_options</i><tt>>, <</tt><i>filename1</i><tt>>, <</tt><i>filename2</i><tt>>
467 </tt></pre>
468 <p>does not vary by locale because it is the representation of a command, not an English sentence.</p>
469 </blockquote>
470 <h4 class="mansect"><a name="tag_20_34_19" id="tag_20_34_19"></a>FUTURE DIRECTIONS</h4>
471 <blockquote>
472 <p>If this utility is directed to display a pathname that contains any bytes that have the encoded value of a <newline>
473 character when <newline> is a terminator or separator in the output format being used, implementations are encouraged to
474 treat this as an error. A future version of this standard may require implementations to treat this as an error.</p>
475 </blockquote>
476 <h4 class="mansect"><a name="tag_20_34_20" id="tag_20_34_20"></a>SEE ALSO</h4>
477 <blockquote>
478 <p><a href="../utilities/cmp.html#"><i>cmp</i></a> , <a href="../utilities/comm.html#"><i>comm</i></a> , <a href=
479 "../utilities/ed.html#"><i>ed</i></a> , <a href="../utilities/find.html#"><i>find</i></a></p>
480 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
481 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p>
482 </blockquote>
483 <h4 class="mansect"><a name="tag_20_34_21" id="tag_20_34_21"></a>CHANGE HISTORY</h4>
484 <blockquote>
485 <p>First released in Issue 2.</p>
486 </blockquote>
487 <h4 class="mansect"><a name="tag_20_34_22" id="tag_20_34_22"></a>Issue 5</h4>
488 <blockquote>
489 <p>The FUTURE DIRECTIONS section is added.</p>
490 </blockquote>
491 <h4 class="mansect"><a name="tag_20_34_23" id="tag_20_34_23"></a>Issue 6</h4>
492 <blockquote>
493 <p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>
494 <ul>
495 <li>
496 <p>The <b>-f</b> option is added.</p>
497 </li>
498 </ul>
499 <p>The output format for <b>-c</b> or <b>-C</b> format is changed to align with changes to the IEEE P1003.2b draft standard
500 resulting from IEEE PASC Interpretation 1003.2 #71.</p>
501 <p>The normative text is reworded to avoid use of the term "must" for application requirements.</p>
502 <p>IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/20 is applied, changing the STDOUT section. This changes the
503 specification of <i>diff</i> <b>-c</b> so that it agrees with existing practice when contexts contain zero lines or one line.</p>
504 </blockquote>
505 <h4 class="mansect"><a name="tag_20_34_24" id="tag_20_34_24"></a>Issue 7</h4>
506 <blockquote>
507 <p>Austin Group Interpretations 1003.1-2001 #115 and #114 are applied.</p>
508 <p>Austin Group Interpretation 1003.1-2001 #192 is applied, clarifying the behavior if both files are non-text files.</p>
509 <p>SD5-XCU-ERN-97 is applied, updating the SYNOPSIS.</p>
510 <p>SD5-XCU-ERN-103 and SD5-XCU-ERN-120 are applied, adding the <b>-u</b> option.</p>
511 <p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0082 [584], XCU/TC2-2008/0083 [950], XCU/TC2-2008/0084 [969], and
512 XCU/TC2-2008/0085 [929] are applied.</p>
513 </blockquote>
514 <h4 class="mansect"><a name="tag_20_34_25" id="tag_20_34_25"></a>Issue 8</h4>
515 <blockquote>
516 <p>Austin Group Defect 251 is applied, encouraging implementations to report an error if a utility is directed to display a
517 pathname that contains any bytes that have the encoded value of a <newline> character when <newline> is a terminator or
518 separator in the output format being used.</p>
519 <p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
520 <p>Austin Group Defect 1498 is applied, changing the EXIT STATUS section.</p>
521 </blockquote>
522 <div class="box"><em>End of informative text.</em></div>
523 <hr>
524 <p> </p>
525 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
526 <hr size="2" noshade>
527 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
528 POSIX™ is a Trademark of The IEEE.<br>
529 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
530 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
531 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
532 ]</font></center>
533 <hr size="2" noshade>
534 <div class="NAVHEADER">
535 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
536 <tr class="nav">
537 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/df.html" accesskey="P"><<<
538 Previous</a></td>
539 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
540 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/dirname.html" accesskey="N">Next
541 >>></a></td>
542 </tr>
543 </table>
544 <hr align="left" width="100%"></div>
545 </body>
546 </html>