summaryrefslogtreecommitdiffstats
path: root/man-pages-posix-2017/man1p/diff.1p
diff options
context:
space:
mode:
Diffstat (limited to 'man-pages-posix-2017/man1p/diff.1p')
-rw-r--r--man-pages-posix-2017/man1p/diff.1p1013
1 files changed, 1013 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/diff.1p b/man-pages-posix-2017/man1p/diff.1p
new file mode 100644
index 0000000..d6262ae
--- /dev/null
+++ b/man-pages-posix-2017/man1p/diff.1p
@@ -0,0 +1,1013 @@
+'\" et
+.TH DIFF "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+diff
+\(em compare two files
+.SH SYNOPSIS
+.LP
+.nf
+diff \fB[\fR-c|-e|-f|-u|-C \fIn\fR|-U \fIn\fB] [\fR-br\fB] \fIfile1 file2\fR
+.fi
+.SH DESCRIPTION
+The
+.IR diff
+utility shall compare the contents of
+.IR file1
+and
+.IR file2
+and write to standard output a list of changes necessary to convert
+.IR file1
+into
+.IR file2 .
+This list should be minimal. No output shall be produced if the files
+are identical.
+.SH OPTIONS
+The
+.IR diff
+utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Section 12.2" ", " "Utility Syntax Guidelines".
+.P
+The following options shall be supported:
+.IP "\fB\-b\fP" 10
+Cause any amount of white space at the end of a line to be treated as a
+single
+<newline>
+(that is, the white-space characters preceding the
+<newline>
+are ignored) and other strings of white-space characters, not including
+<newline>
+characters, to compare equal.
+.IP "\fB\-c\fP" 10
+Produce output in a form that provides three lines of copied context.
+.IP "\fB\-C\ \fIn\fR" 10
+Produce output in a form that provides
+.IR n
+lines of copied context (where
+.IR n
+shall be interpreted as a positive decimal integer).
+.IP "\fB\-e\fP" 10
+Produce output in a form suitable as input for the
+.IR ed
+utility, which can then be used to convert
+.IR file1
+into
+.IR file2 .
+.IP "\fB\-f\fP" 10
+Produce output in an alternative form, similar in format to
+.BR \-e ,
+but not intended to be suitable as input for the
+.IR ed
+utility, and in the opposite order.
+.IP "\fB\-r\fP" 10
+Apply
+.IR diff
+recursively to files and directories of the same name when
+.IR file1
+and
+.IR file2
+are both directories.
+.RS 10
+.P
+The
+.IR diff
+utility shall detect infinite loops; that is, entering a previously
+visited directory that is an ancestor of the last file encountered.
+When it detects an infinite loop,
+.IR diff
+shall write a diagnostic message to standard error and shall either
+recover its position in the hierarchy or terminate.
+.RE
+.IP "\fB\-u\fP" 10
+Produce output in a form that provides three lines of unified context.
+.IP "\fB\-U\ \fIn\fR" 10
+Produce output in a form that provides
+.IR n
+lines of unified context (where
+.IR n
+shall be interpreted as a non-negative decimal integer).
+.SH OPERANDS
+The following operands shall be supported:
+.IP "\fIfile1\fR,\ \fIfile2\fR" 10
+A pathname of a file to be compared. If either the
+.IR file1
+or
+.IR file2
+operand is
+.BR '\-' ,
+the standard input shall be used in its place.
+.P
+If both
+.IR file1
+and
+.IR file2
+are directories,
+.IR diff
+shall not compare block special files, character special files, or FIFO
+special files to any files and shall not compare regular files to
+directories.
+Further details are as specified in
+.IR "Diff Directory Comparison Format".
+The behavior of
+.IR diff
+on other file types is implementation-defined when found in directories.
+.P
+If only one of
+.IR file1
+and
+.IR file2
+is a directory,
+.IR diff
+shall be applied to the non-directory file and the file contained in
+the directory file with a filename that is the same as the last
+component of the non-directory file.
+.SH STDIN
+The standard input shall be used only if one of the
+.IR file1
+or
+.IR file2
+operands references standard input. See the INPUT FILES section.
+.SH "INPUT FILES"
+The input files may be of any type.
+.SH "ENVIRONMENT VARIABLES"
+The following environment variables shall affect the execution of
+.IR diff :
+.IP "\fILANG\fP" 10
+Provide a default value for the internationalization variables that are
+unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
+.IR "Section 8.2" ", " "Internationalization Variables"
+for the precedence of internationalization variables used to determine
+the values of locale categories.)
+.IP "\fILC_ALL\fP" 10
+If set to a non-empty string value, override the values of all the
+other internationalization variables.
+.IP "\fILC_CTYPE\fP" 10
+Determine the locale for the interpretation of sequences of bytes of
+text data as characters (for example, single-byte as opposed to
+multi-byte characters in arguments and input files).
+.IP "\fILC_MESSAGES\fP" 10
+.br
+Determine the locale that should be used to affect the format and
+contents of diagnostic messages written to standard error and
+informative messages written to standard output.
+.IP "\fILC_TIME\fP" 10
+Determine the locale for affecting the format of file timestamps
+written with the
+.BR \-C
+and
+.BR \-c
+options.
+.IP "\fINLSPATH\fP" 10
+Determine the location of message catalogs for the processing of
+.IR LC_MESSAGES .
+.IP "\fITZ\fP" 10
+Determine the timezone used for calculating file timestamps written
+with a context format. If
+.IR TZ
+is unset or null, an unspecified default timezone shall be used.
+.SH "ASYNCHRONOUS EVENTS"
+Default.
+.SH STDOUT
+.SS "Diff Directory Comparison Format"
+.P
+If both
+.IR file1
+and
+.IR file2
+are directories, the following output formats shall be used.
+.P
+In the POSIX locale, each file that is present in only one directory
+shall be reported using the following format:
+.sp
+.RS 4
+.nf
+
+"Only in %s: %s\en", <\fIdirectory pathname\fP>, <\fIfilename\fR>
+.fi
+.P
+.RE
+.P
+In the POSIX locale, subdirectories that are common to the two
+directories may be reported with the following format:
+.sp
+.RS 4
+.nf
+
+"Common subdirectories: %s and %s\en", <\fIdirectory1 pathname\fR>,
+ <\fIdirectory2 pathname\fR>
+.fi
+.P
+.RE
+.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 and file
+serial number, or are both block special files that refer to the
+same device, or are both character special files that refer to the
+same device, in the POSIX locale the output format is unspecified.
+Otherwise, in the POSIX locale an unspecified format shall be used
+that contains the pathnames of the two files.
+.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
+files differ, the following format is written:
+.sp
+.RS 4
+.nf
+
+"diff %s %s %s\en", <\fIdiff_options\fR>, <\fIfilename1\fR>, <\fIfilename2\fR>
+.fi
+.P
+.RE
+.P
+where <\fIdiff_options\fP> are the options as specified on the command
+line.
+.P
+All directory pathnames listed in this section shall be relative to the
+original command line arguments. All other names of files listed in
+this section shall be filenames (pathname components).
+.SS "Diff Binary Output Format"
+.P
+In the POSIX locale, if one or both of the files being compared are not
+text files, it is implementation-defined whether
+.IR diff
+uses the binary file output format or the other formats as specified
+below. The binary file output format shall contain the pathnames of
+two files being compared and the string
+.BR \(dqdiffer\(dq .
+.P
+If both files being compared are text files, depending on the options
+specified, one of the following formats shall be used to write the
+differences.
+.SS "Diff Default Output Format"
+.P
+The default (without
+.BR \-e ,
+.BR \-f ,
+.BR \-c ,
+.BR \-C ,
+.BR \-u ,
+or
+.BR \-U
+options)
+.IR diff
+utility output shall contain lines of these forms:
+.sp
+.RS 4
+.nf
+
+"%da%d\en", <\fInum1\fR>, <\fInum2\fR>
+.P
+"%da%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
+.P
+"%dd%d\en", <\fInum1\fR>, <\fInum2\fR>
+.P
+"%d,%dd%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
+.P
+"%dc%d\en", <\fInum1\fR>, <\fInum2\fR>
+.P
+"%d,%dc%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
+.P
+"%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>
+.P
+"%d,%dc%d,%d\en", <\fInum1\fR>, <\fInum2\fR>, <\fInum3\fR>, <\fInum4\fR>
+.fi
+.P
+.RE
+.P
+These lines resemble
+.IR ed
+subcommands to convert
+.IR file1
+into
+.IR file2 .
+The line numbers before the action letters shall pertain to
+.IR file1 ;
+those after shall pertain to
+.IR file2 .
+Thus, by exchanging
+.IR a
+for
+.IR d
+and reading the line in reverse order, one can also determine how to
+convert
+.IR file2
+into
+.IR file1 .
+As in
+.IR ed ,
+identical pairs (where
+.IR num1 =
+.IR num2 )
+are abbreviated as a single number.
+.P
+Following each of these lines,
+.IR diff
+shall write to standard output all lines affected in the first
+file using the format:
+.sp
+.RS 4
+.nf
+
+"< %s", <\fIline\fR>
+.fi
+.P
+.RE
+.P
+and all lines affected in the second file using the format:
+.sp
+.RS 4
+.nf
+
+"> %s", <\fIline\fR>
+.fi
+.P
+.RE
+.P
+If there are lines affected in both
+.IR file1
+and
+.IR file2
+(as with the
+.BR c
+subcommand), the changes are separated with a line consisting of three
+<hyphen-minus>
+characters:
+.sp
+.RS 4
+.nf
+
+"---\en"
+.fi
+.P
+.RE
+.SS "Diff \-e Output Format"
+.P
+With the
+.BR \-e
+option, a script shall be produced that shall, when provided as input
+to
+.IR ed ,
+along with an appended
+.BR w
+(write) command, convert
+.IR file1
+into
+.IR file2 .
+Only the
+.BR a
+(append),
+.BR c
+(change),
+.BR d
+(delete),
+.BR i
+(insert), and
+.BR s
+(substitute) commands of
+.IR ed
+shall be used in this script. Text lines, except those consisting of
+the single character
+<period>
+(\c
+.BR '.' ),
+shall be output as they appear in the file.
+.SS "Diff \-f Output Format"
+.P
+With the
+.BR \-f
+option, an alternative format of script shall be produced. It is
+similar to that produced by
+.BR \-e ,
+with the following differences:
+.IP " 1." 4
+It is expressed in reverse sequence; the output of
+.BR \-e
+orders changes from the end of the file to the beginning; the
+.BR \-f
+from beginning to end.
+.IP " 2." 4
+The command form <\fIlines\fP> <\fIcommand-letter\fR> used by
+.BR \-e
+is reversed. For example, 10\fIc\fP with
+.BR \-e
+would be
+.IR c 10
+with
+.BR \-f .
+.IP " 3." 4
+The form used for ranges of line numbers is
+<space>-separated,
+rather than
+<comma>-separated.
+.SS "Diff \-c or \-C Output Format"
+.P
+With the
+.BR \-c
+or
+.BR \-C
+option, the output format shall consist of affected lines along with
+surrounding lines of context. The affected lines shall show which ones
+need to be deleted or changed in
+.IR file1 ,
+and those added from
+.IR file2 .
+With the
+.BR \-c
+option, three lines of context, if available, shall be written before
+and after the affected lines. With the
+.BR \-C
+option, the user can specify how many lines of context are written.
+The exact format follows.
+.P
+The name and last modification time of each file shall be output in the
+following format:
+.sp
+.RS 4
+.nf
+
+"*** %s %s\en", \fIfile1\fR, <\fIfile1 timestamp\fR>
+"--- %s %s\en", \fIfile2\fR, <\fIfile2 timestamp\fR>
+.fi
+.P
+.RE
+.P
+Each <\fIfile\fP> field shall be the pathname of the corresponding
+file being compared. The pathname written for standard input is
+unspecified.
+.P
+In the POSIX locale, each <\fItimestamp\fP> field shall be equivalent
+to the output from the following command:
+.sp
+.RS 4
+.nf
+
+date "+%a %b %e %T %Y"
+.fi
+.P
+.RE
+.P
+without the trailing
+<newline>,
+executed at the time of last modification of the corresponding file (or
+the current time, if the file is standard input).
+.P
+Then, the following output formats shall be applied for every set of
+changes.
+.P
+First, a line shall be written in the following format:
+.sp
+.RS 4
+.nf
+
+"***************\en"
+.fi
+.P
+.RE
+.P
+Next, the range of lines in
+.IR file1
+shall be written in the following format if the range contains
+two or more lines:
+.sp
+.RS 4
+.nf
+
+"*** %d,%d ****\en", <\fIbeginning line number\fR>, <\fIending line number\fR>
+.fi
+.P
+.RE
+.P
+and the following format otherwise:
+.sp
+.RS 4
+.nf
+
+"*** %d ****\en", <\fIending line number\fR>
+.fi
+.P
+.RE
+.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 file.
+.P
+Next, the affected lines along with lines of context (unaffected lines)
+shall be written. Unaffected lines shall be written in the following
+format:
+.sp
+.RS 4
+.nf
+
+" %s", <\fIunaffected_line\fR>
+.fi
+.P
+.RE
+.P
+Deleted lines shall be written as:
+.sp
+.RS 4
+.nf
+
+"- %s", <\fIdeleted_line\fR>
+.fi
+.P
+.RE
+.P
+Changed lines shall be written as:
+.sp
+.RS 4
+.nf
+
+"! %s", <\fIchanged_line\fR>
+.fi
+.P
+.RE
+.P
+Next, the range of lines in
+.IR file2
+shall be written in the following format if the range contains two
+or more lines:
+.sp
+.RS 4
+.nf
+
+"--- %d,%d ----\en", <\fIbeginning line number\fR>, <\fIending line number\fR>
+.fi
+.P
+.RE
+.P
+and the following format otherwise:
+.sp
+.RS 4
+.nf
+
+"--- %d ----\en", <\fIending line number\fR>
+.fi
+.P
+.RE
+.P
+Then, lines of context and changed lines shall be written as described in
+the previous formats. Lines added from
+.IR file2
+shall be written in the following format:
+.sp
+.RS 4
+.nf
+
+"+ %s", <\fIadded_line\fR>
+.fi
+.P
+.RE
+.SS "Diff \-u or \-U Output Format"
+.P
+The
+.BR \-u
+or
+.BR \-U
+options behave like the
+.BR \-c
+or
+.BR \-C
+options, except that the context lines are not repeated; instead,
+the context, deleted, and added lines are shown together, interleaved.
+The exact format follows.
+.P
+The name and last modification time of each file shall be output
+in the following format:
+.sp
+.RS 4
+.nf
+
+"--- %s\et%s%s %s\en", file1, <file1 timestamp>, <file1 frac>, <file1 zone>
+"+++ %s\et%s%s %s\en", file2, <file2 timestamp>, <file2 frac>, <file2 zone>
+.fi
+.P
+.RE
+.P
+Each <\fIfile\fR> field shall be the pathname of the corresponding file
+being compared, or the single character
+.BR '\-'
+if standard input is being compared. However, if the pathname contains
+a
+<tab>
+or a
+<newline>,
+or if it does not consist entirely of characters taken
+from the portable character set, the behavior is implementation-defined.
+.P
+Each <\fItimestamp\fR> field shall be equivalent to the output from the
+following command:
+.sp
+.RS 4
+.nf
+
+date \(aq+%Y-%m-%d %H:%M:%S\(aq
+.fi
+.P
+.RE
+.P
+without the trailing
+<newline>,
+executed at the time of last modification of the corresponding file
+(or the current time, if the file is standard input).
+.P
+Each <\fIfrac\fR> field shall be either empty, or a decimal point
+followed by at least one decimal digit, indicating the
+fractional-seconds part (if any) of the file timestamp. The
+number of fractional digits shall be at least the number needed to
+represent the file's timestamp without loss of information.
+.P
+Each <\fIzone\fR> field shall be of the form
+.BR \(dqshhmm\(dq ,
+where
+.BR \(dqshh\(dq
+is a signed two-digit decimal number in the range \-24 through +25, and
+.BR \(dqmm\(dq
+is an unsigned two-digit decimal number in the range 00 through 59.
+It represents the timezone of the timestamp as the number of hours
+(hh) and minutes (mm) east (+) or west (\-) of UTC for the timestamp.
+If the hours and minutes are both zero, the sign shall be
+.BR '+' .
+However, if the timezone is not an integral number of minutes away
+from UTC, the <\fIzone\fR> field is implementation-defined.
+.P
+Then, the following output formats shall be applied for every set
+of changes.
+.P
+First, the range of lines in each file shall be written in the
+following format:
+.sp
+.RS 4
+.nf
+
+"@@ -%s +%s @@", <file1 range>, <file2 range>
+.fi
+.P
+.RE
+.P
+Each <\fIrange\fR> field shall be of the form:
+.sp
+.RS 4
+.nf
+
+"%1d", <beginning line number>
+.fi
+.P
+.RE
+.P
+or:
+.sp
+.RS 4
+.nf
+
+"%1d,1", <beginning line number>
+.fi
+.P
+.RE
+.P
+if the range contains exactly one line, and:
+.sp
+.RS 4
+.nf
+
+"%1d,%1d", <beginning line number>, <number of lines>
+.fi
+.P
+.RE
+.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 empty
+range starts the file.
+.P
+Next, the affected lines along with lines of context shall be written.
+Each non-empty unaffected line shall be written in the following format:
+.sp
+.RS 4
+.nf
+
+" %s", <unaffected_line>
+.fi
+.P
+.RE
+.P
+where the contents of the unaffected line shall be taken from
+.IR file1 .
+It is implementation-defined whether an empty unaffected line is written
+as an empty line or a line containing a single
+<space>
+character. This line also represents the same line of
+.IR file2 ,
+even though
+.IR file2 's
+line may contain different contents due to the
+.BR \-b .
+Deleted lines shall be written as:
+.sp
+.RS 4
+.nf
+
+"-%s", <deleted_line>
+.fi
+.P
+.RE
+.P
+Added lines shall be written as:
+.sp
+.RS 4
+.nf
+
+"+%s", <added_line>
+.fi
+.P
+.RE
+.P
+The order of lines written shall be the same as that of the
+corresponding file. A deleted line shall never be written
+immediately after an added line.
+.P
+If
+.BR \-U
+.IR n
+is specified, the output shall contain no more than 2\c
+.IR n
+consecutive unaffected lines; and if the output contains an
+affected line and this line is adjacent to up to
+.IR n
+consecutive unaffected lines in the corresponding file, the output shall
+contain these unaffected lines.
+.BR \-u
+shall act like
+.BR \-U 3.
+.SH STDERR
+The standard error shall be used only for diagnostic messages.
+.SH "OUTPUT FILES"
+None.
+.SH "EXTENDED DESCRIPTION"
+None.
+.SH "EXIT STATUS"
+The following exit values shall be returned:
+.IP "\00" 6
+No differences were found.
+.IP "\01" 6
+Differences were found.
+.IP >1 6
+An error occurred.
+.SH "CONSEQUENCES OF ERRORS"
+Default.
+.LP
+.IR "The following sections are informative."
+.SH "APPLICATION USAGE"
+If lines at the end of a file are changed and other lines are added,
+.IR diff
+output may show this as a delete and add, as a change, or as a change
+and add;
+.IR diff
+is not expected to know which happened and users should not care about
+the difference in output as long as it clearly shows the differences
+between the files.
+.SH EXAMPLES
+If
+.BR dir1
+is a directory containing a directory named
+.BR x ,
+.BR dir2
+is a directory containing a directory named
+.BR x ,
+.BR dir1/x
+and
+.BR dir2/x
+both contain files named
+.BR date.out ,
+and
+.BR dir2/x
+contains a file named
+.BR y ,
+the command:
+.sp
+.RS 4
+.nf
+
+diff -r dir1 dir2
+.fi
+.P
+.RE
+.P
+could produce output similar to:
+.sp
+.RS 4
+.nf
+
+Common subdirectories: dir1/x and dir2/x
+Only in dir2/x: y
+diff -r dir1/x/date.out dir2/x/date.out
+1c1
+< Mon Jul 2 13:12:16 PDT 1990
+---
+> Tue Jun 19 21:41:39 PDT 1990
+.fi
+.P
+.RE
+.SH RATIONALE
+The
+.BR \-h
+option was omitted because it was insufficiently specified and does not
+add to applications portability.
+.P
+Historical implementations employ algorithms that do not always produce
+a minimum list of differences; the current language about making every
+effort is the best this volume of POSIX.1\(hy2017 can do, as there is no metric that could be
+employed to judge the quality of implementations against any and all
+file contents. The statement ``This list should be minimal'' clearly
+implies that implementations are not expected to provide the following
+output when comparing two 100-line files that differ in only one
+character on a single line:
+.sp
+.RS 4
+.nf
+
+1,100c1,100
+all 100 lines from file1 preceded with "< "
+---
+all 100 lines from file2 preceded with "> "
+.fi
+.P
+.RE
+.P
+The ``Only in'' messages required when the
+.BR \-r
+option is specified are not used by most historical implementations if
+the
+.BR \-e
+option is also specified. It is required here because it provides
+useful information that must be provided to update a target directory
+hierarchy to match a source hierarchy. The ``Common subdirectories''
+messages are written by System V and 4.3 BSD when the
+.BR \-r
+option is specified. They are allowed here but are not required because
+they are reporting on something that is the same, not reporting a
+difference, and are not needed to update a target hierarchy.
+.P
+The
+.BR \-c
+option, which writes output in a format using lines of context, has
+been included. The format is useful for a variety of reasons, among
+them being much improved readability and the ability to understand
+difference changes when the target file has line numbers that differ
+from another similar, but slightly different, copy. The
+.IR patch
+utility is most valuable when working with difference listings using
+a context format. The BSD version of
+.BR \-c
+takes an optional argument specifying the amount of context. Rather
+than overloading
+.BR \-c
+and breaking the Utility Syntax Guidelines for
+.IR diff ,
+the standard developers decided to add a separate option for specifying
+a context diff with a specified amount of context (\c
+.BR \-C ).
+Also, the format for context
+.IR diff s
+was extended slightly in 4.3 BSD to allow multiple changes that are
+within context lines from each other to be merged together. The output
+format contains an additional four
+<asterisk>
+characters after the range of affected lines in the first filename. This
+was to provide a flag for old programs (like old versions of
+.IR patch )
+that only understand the old context format. The version of context
+described here does not require that multiple changes within context
+lines be merged, but it does not prohibit it either. The extension is
+upwards-compatible, so any vendors that wish to retain the old version
+of
+.IR diff
+can do so by adding the extra four
+<asterisk>
+characters (that is, utilities that currently use
+.IR diff
+and understand the new merged format will also understand the old
+unmerged format, but not \fIvice versa\fP).
+.P
+The
+.BR \-u
+and
+.BR \-U
+options of GNU
+.IR diff
+have been included. Their output format, designed by Wayne Davison,
+takes up less space than
+.BR \-c
+and
+.BR \-C
+format, and in many cases is easier to read. The format's timestamps
+do not vary by locale, so
+.IR LC_TIME
+does not affect it. The format's line numbers are rendered with the
+.BR %1d
+format, not
+.BR %d ,
+because the file format notation rules would allow extra
+<blank>
+characters to appear around the numbers.
+.P
+The substitute command was added as an additional format for the
+.BR \-e
+option. This was added to provide implementations with a way to fix the
+classic ``dot alone on a line'' bug present in many versions of
+.IR diff .
+Since many implementations have fixed this bug, the standard developers
+decided not to standardize broken behavior, but rather to provide the
+necessary tool for fixing the bug. One way to fix this bug is to output
+two periods whenever a lone period is needed, then terminate the append
+command with a period, and then use the substitute command to convert
+the two periods into one period.
+.P
+The BSD-derived
+.BR \-r
+option was added to provide a mechanism for using
+.IR diff
+to compare two file system trees. This behavior is useful, is standard
+practice on all BSD-derived systems, and is not easily reproducible
+with the
+.IR find
+utility.
+.P
+The requirement that
+.IR diff
+not compare files in some circumstances, even though they have the same
+name, is based on the actual output of historical implementations.
+The specified behavior precludes the problems arising from running
+into FIFOs and other files that would cause
+.IR diff
+to hang waiting for input with no indication to the user that
+.IR diff
+was hung. An earlier version of this standard specified the output
+format more precisely, but in practice this requirement was widely
+ignored and the benefit of standardization seemed small, so it is now
+unspecified. In most common usage,
+.IR diff
+.BR \-r
+should indicate differences in the file hierarchies, not the difference
+of contents of devices pointed to by the hierarchies.
+.P
+Many early implementations of
+.IR diff
+require seekable files. Since the System Interfaces volume of POSIX.1\(hy2017 supports named pipes, the
+standard developers decided that such a restriction was unreasonable.
+Note also that the allowed filename
+.BR \-
+almost always refers to a pipe.
+.P
+No directory search order is specified for
+.IR diff .
+The historical ordering is, in fact, not optimal, in that it prints out
+all of the differences at the current level, including the statements
+about all common subdirectories before recursing into those
+subdirectories.
+.P
+The message:
+.sp
+.RS 4
+.nf
+
+"diff %s %s %s\en", <\fIdiff_options\fP>, <\fIfilename1\fP>, <\fIfilename2\fP>
+.fi
+.P
+.RE
+.P
+does not vary by locale because it is the representation of a command,
+not an English sentence.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIcmp\fR\^",
+.IR "\fIcomm\fR\^",
+.IR "\fIed\fR\^",
+.IR "\fIfind\fR\^"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "Chapter 8" ", " "Environment Variables",
+.IR "Section 12.2" ", " "Utility Syntax Guidelines"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .