Index: usr.bin/fstat/fstat.1
===================================================================
--- usr.bin/fstat/fstat.1
+++ usr.bin/fstat/fstat.1
@@ -51,7 +51,7 @@
 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 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,117 @@
 .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
+alice  bash         469   wd /home    16970191 drwxr-xr-x      11  r
+alice  bash         469 root /             4 drwxr-xr-x      36  r
+alice  bash         469 jail /             4 drwxr-xr-x      36  r
+alice  bash         469    0 /dev        346 crw--w----  pts/81 rw
+alice  bash         469    1 /dev        346 crw--w----  pts/81 rw
+alice  bash         469    2 /dev        346 crw--w----  pts/81 rw
+alice  bash         469  255 /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
+bob  bash         469 mmap /usr/local 143355 -rwxr-xr-x  1166448  r
+bob  bash         469 mmap /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
+USER     CMD          PID   FD MOUNT      INUM MODE         SZ|DV R/W
+alice  bash         469 text /usr/local 143355 -rwxr-xr-x  1166448  r
+.Ed
+.Pp
+Show number of pipes opened by firefox processes:
+.Bd -literal -offset indent
+$ fstat | awk '$2=="firefox" && $5=="pipe"' | wc -l
+      88
+.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  terminology 77845    2 /dev        103 crw-------   ttyv0 rw
+bob  firefox    77842    2 /dev        103 crw-------   ttyv0 rw
+bob  efreetd     1261    2 /dev        103 crw-------   ttyv0 rw
+bob  terminology  1260    2 /dev        103 crw-------   ttyv0 rw
+bob  fluxbox     1198    2 /dev        103 crw-------   ttyv0 rw
+bob  xinit       1194    2 /dev        103 crw-------   ttyv0 rw
+bob  sh          1181    2 /dev        103 crw-------   ttyv0 rw
+bob  bash        1179    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
+alice  firefox     1251   58* internet stream tcp fffff800743abb70
+alice  firefox     1250   58* internet stream tcp fffff800743abb70
+alice  firefox     1247  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;} END{printf "\n"}'
+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
+ 515 efreetd
+  50 tmux
+  38 terminology
+  23 bash
+  14 sort
+   9 conky
+   8 xinit
+   8 sh
+   8 fstat
+   8 fluxbox
+   7 awk
+.Ed
 .Sh SEE ALSO
 .Xr fuser 1 ,
 .Xr netstat 1 ,