fstat(1): Add EXAMPLES section

* Add examples covering -f, -m and -p flags.

While here, extend the initial description paragraph to note that fstat(1)
will report on all opened files, belonging to processes the user has access to.
The current paragraph may lead to understand that you can get information on
opened files from processes belonging to other users.

Reviewed by:	bjk@, danfe@, gbe@
Approved by:	manpages (gbe@)
Differential Revision:		https://reviews.freebsd.org/D26949

1 files changed, 90 insertions, 3 deletions

diff --git a/usr.bin/fstat/fstat.1 b/usr.bin/fstat/fstat.1
index 58d1e1f9aa225..77bfc8588c2aa 100644
--- a/usr.bin/fstat/fstat.1
+++ b/usr.bin/fstat/fstat.1
@@ -28,7 +28,7 @@
 .\"     @(#)fstat.1	8.3 (Berkeley) 2/25/94
 .\" $FreeBSD$
 .\"
-.Dd June 17, 2020
+.Dd November 19, 2020
 .Dt FSTAT 1
 .Os
 .Sh NAME
@@ -51,7 +51,7 @@ is the working directory, root directory, jail root directory,
 active executable text, or kernel trace file for that process.
 If no options are specified,
 .Nm
-reports on all open files in the system.
+reports on all open files in the system for processes the user has access to.
 .Pp
 The following options are available:
 .Bl -tag -width "-N system"
@@ -118,7 +118,7 @@ The process id.
 The file number in the per-process open file table or one of the following
 special names:
 .Pp
-.Bl -tag -offset indent -compact
+.Bl -tag -width jail -offset indent -compact
 .It Sy jail
 jail root directory
 .It Sy mmap
@@ -235,6 +235,93 @@ a double arrow
 .Pq Ql <-> .
 For UNIX/local sockets either the local or remote address is shown, depending
 on which one is available.
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+Show all open files except those opened by
+.Nm
+itself:
+.Bd -literal -offset indent
+$ fstat | awk '$2 != "fstat"'
+USER     CMD          PID   FD MOUNT      INUM MODE         SZ|DV R/W
+alice  bash         469 text /usr/local 143355 -rwxr-xr-x  1166448  r
+alice  bash         469 ctty /dev        346 crw--w----  pts/81 rw
+\&...
+.Ed
+.Pp
+Report all files opened by the current shell in the same file system as
+.Pa /usr/local
+including memory-mapped files:
+.Bd -literal -offset indent
+$ fstat -m -p $$ -f /usr/local
+USER     CMD          PID   FD MOUNT      INUM MODE         SZ|DV R/W
+bob  bash         469 text /usr/local 143355 -rwxr-xr-x  1166448  r
+bob  bash         469 mmap /usr/local 143355 -rwxr-xr-x  1166448  r
+\&...
+.Ed
+.Pp
+Requesting information about a file that is not opened results in just a
+header line instead of an error:
+.Bd -literal -offset indent
+$ fstat /etc/rc.conf
+USER     CMD          PID   FD MOUNT      INUM MODE         SZ|DV R/W NAME
+.Ed
+.Pp
+All parameters after
+.Fl f
+will be interpreted as files, so the following will not work as expected:
+.Bd -literal -offset indent
+$ fstat -f /usr/local -m -p $$
+fstat: -m: No such file or directory
+fstat: -p: No such file or directory
+fstat: 469: No such file or directory
+\&...
+.Ed
+.Pp
+Show number of pipes opened by firefox processes:
+.Bd -literal -offset indent
+$ fstat | awk '$2=="firefox" && $5=="pipe"' | wc -l
+.Ed
+.Pp
+Show processes belonging to user
+.Dq bob
+whose standard error descriptor is opened in ttyv0:
+.Bd -literal -offset indent
+$ fstat -u bob | awk '$4 == 2 && $8 == "ttyv0"'
+bob  firefox    77842    2 /dev        103 crw-------   ttyv0 rw
+bob  xinit       1194    2 /dev        103 crw-------   ttyv0 rw
+\&...
+.Ed
+.Pp
+Show opened TCP sockets.
+This output resembles the one produced by
+.Ql netstat -A -p tcp
+:
+.Bd -literal -offset indent
+$ fstat | awk '$7 == "tcp"'
+alice  firefox    77991   32* internet stream tcp fffff800b7f147a0
+alice  firefox    77991  137* internet stream tcp fffff800b7f12b70
+\&...
+.Ed
+.Pp
+Show a list of processes with files opened in the current directory
+mimicking the output of
+.Xr fuser 1
+:
+.Bd -literal -offset indent
+$ fstat . | awk 'NR > 1 {printf "%d%s(%s) ", $3, $4, $1;}'
+2133wd(alice) 2132wd(alice) 1991wd(alice)
+.Ed
+.Pp
+Create a list of processes sorted by number of opened files in desdencing order:
+.Bd -literal -offset indent
+$ fstat | awk 'NR > 1 {print $2;}' | sort | uniq -c | sort -r
+ 728 firefox
+  23 bash
+  14 sort
+   8 fstat
+   7 awk
+.Ed
 .Sh SEE ALSO
 .Xr fuser 1 ,
 .Xr netstat 1 ,