From f0f718ce96f74076ea14bff7e71e578573d80641 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fernando=20Apestegu=C3=ADa?= <fernape@FreeBSD.org>
Date: Thu, 24 Sep 2020 16:11:53 +0000
Subject: [PATCH] which(1): Add EXAMPLES section to manpage

Add EXAMPLES section showing the use of -a and -s flags and how which(1)
treates duplicates.

Approved by:	manpages (gbe@)
Differential Revision:	https://reviews.freebsd.org/D26182
---
 usr.bin/which/which.1 | 44 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/usr.bin/which/which.1 b/usr.bin/which/which.1
index 0c0dce82e769..6606c4ed9aab 100644
--- a/usr.bin/which/which.1
+++ b/usr.bin/which/which.1
@@ -29,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 13, 2006
+.Dd September 24, 2020
 .Dt WHICH 1
 .Os
 .Sh NAME
@@ -62,6 +62,48 @@ command which is similar or identical to this utility.
 Consult the
 .Xr builtin 1
 manual page.
+.Sh EXAMPLES
+Locate the
+.Xr ls 1
+and
+.Xr cp 1
+commands:
+.Bd -literal -offset indent
+$ /usr/bin/which ls cp
+/bin/ls
+/bin/cp
+.Ed
+.Pp
+Same as above with a specific
+.Va PATH
+and showing all occurrences:
+.Bd -literal -offset indent
+$ PATH=/bin:/rescue /usr/bin/which -a ls cp
+/bin/ls
+/rescue/ls
+/bin/cp
+/rescue/cp
+.Ed
+.Pp
+.Nm which
+will show duplicates if the same executable is find more than once:
+.Bd -literal -offset indent
+$ PATH=/bin:/bin /usr/bin/which -a ls
+/bin/ls
+/bin/ls
+.Ed
+.Pp
+Do not show output.
+Just exit with an appropriate return code:
+.Bd -literal -offset indent
+$ /usr/bin/which -s ls cp
+$ echo $?
+0
+
+$ /usr/bin/which -s fakecommand
+$ echo $?
+1
+.Ed
 .Sh SEE ALSO
 .Xr builtin 1 ,
 .Xr csh 1 ,