git: a19dcf584263 - stable/12 - cmp(1): Add EXAMPLES section

[Kyle Evans]

The branch stable/12 has been updated by kevans:

URL: https://cgit.FreeBSD.org/src/commit/?id=a19dcf584263d53038a9ae803f98ceb68842934a

commit a19dcf584263d53038a9ae803f98ceb68842934a
Author:     Fernando Apesteguía <fernape at FreeBSD.org>
AuthorDate: 2020-06-16 15:54:59 +0000
Commit:     Kyle Evans <kevans at FreeBSD.org>
CommitDate: 2021-10-03 05:19:53 +0000

    cmp(1): Add EXAMPLES section
    
    Add simple examples showing the use of -l, -z, stdin and offsets
    
    (cherry picked from commit 022ebaf5432d5a8112c7d75ab9d406176b3dfd39)
---
 usr.bin/cmp/cmp.1 | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/usr.bin/cmp/cmp.1 b/usr.bin/cmp/cmp.1
index f3bfdf651b51..094509dda08b 100644
--- a/usr.bin/cmp/cmp.1
+++ b/usr.bin/cmp/cmp.1
@@ -31,7 +31,7 @@
 .\"     @(#)cmp.1	8.1 (Berkeley) 6/6/93
 .\" $FreeBSD$
 .\"
-.Dd May 1, 2018
+.Dd June 16, 2020
 .Dt CMP 1
 .Os
 .Sh NAME
@@ -106,6 +106,40 @@ file (before any differences were found).
 .It >1
 An error occurred.
 .El
+.Sh EXAMPLES
+Assuming a file named example.txt with the following contents:
+.Bd -literal -offset indent
+a
+b
+c
+.Ed
+.Pp
+Compare stdin with example.txt:
+.Bd -literal -offset indent
+$ echo -e "a\\nb\\nc" | cmp - example.txt
+.Ed
+.Pp
+Same as above but introducing a change in byte three in stdin.
+Show the byte number (decimal) and differing byte (octal):
+.Bd -literal -offset indent
+$ echo -e "a\\nR\\nc" | cmp -l - example.txt
+     3 122 142
+.Ed
+.Pp
+Compare example.txt and /boot/loader.conf exiting if size differs.
+Note that
+.Fl z
+can only be used with regular files:
+.Bd -literal -offset indent
+$ cmp -z example.txt /boot/loader.conf
+example.txt /boot/loader.conf differ: size
+.Ed
+.Pp
+Compare stdin with file example.txt omitting the 4 first bytes from stdin and
+the 2 first bytes from example.txt:
+.Bd -literal -offset indent
+$ echo -e "a\\nR\\nb\\nc" | cmp - example.txt 4 2
+.Ed
 .Sh SEE ALSO
 .Xr diff 1 ,
 .Xr diff3 1