mirror of
https://git.hardenedbsd.org/hardenedbsd/HardenedBSD.git
synced 2024-11-25 01:55:19 +01:00
0ba51e3b63
This is from the Advanced UNIX Programming Course (Fall’23) at NTHU. MFC after: 3 days Pull Request: https://github.com/freebsd/freebsd-src/pull/929
345 lines
10 KiB
Groff
345 lines
10 KiB
Groff
.\" Copyright (c) 1987, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd November 19, 2020
|
|
.Dt FSTAT 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fstat
|
|
.Nd identify active files
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl fmnsv
|
|
.Op Fl M Ar core
|
|
.Op Fl N Ar system
|
|
.Op Fl p Ar pid
|
|
.Op Fl u Ar user
|
|
.Op Ar
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility identifies open files.
|
|
A file is considered open by a process if it was explicitly opened,
|
|
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 for processes the user has access to.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width "-N system"
|
|
.It Fl f
|
|
Restrict examination to files open in the same file systems as
|
|
the named file arguments, or to the file system containing the
|
|
current directory if there are no additional filename arguments.
|
|
For example, to find all files open in the file system where the
|
|
directory
|
|
.Pa /usr/src
|
|
resides, type
|
|
.Ql fstat -f /usr/src .
|
|
.It Fl M Ar core
|
|
Extract values associated with the name list from the specified core
|
|
instead of the default
|
|
.Pa /dev/kmem .
|
|
.It Fl m
|
|
Include memory-mapped files in the listing; normally these are excluded
|
|
due to the extra processing required.
|
|
.It Fl N Ar system
|
|
Extract the name list from the specified system instead of the default,
|
|
which is the kernel image the system has booted from.
|
|
.It Fl n
|
|
Numerical format.
|
|
Print the device number (maj,min) of the file system
|
|
the file resides in rather than the mount point name; for special
|
|
files, print the
|
|
device number that the special device refers to rather than the filename
|
|
in
|
|
.Pa /dev ;
|
|
and print the mode of the file in octal instead of symbolic form.
|
|
.It Fl p Ar pid
|
|
Report all files open by the specified process.
|
|
.It Fl s
|
|
Print socket endpoint information.
|
|
.It Fl u Ar user
|
|
Report all files open by the specified user.
|
|
.It Fl v
|
|
Verbose mode.
|
|
Print error messages upon failures to locate particular
|
|
system data structures rather than silently ignoring them.
|
|
Most of
|
|
these data structures are dynamically created or deleted and it is
|
|
possible for them to disappear while
|
|
.Nm
|
|
is running.
|
|
This
|
|
is normal and unavoidable since the rest of the system is running while
|
|
.Nm
|
|
itself is running.
|
|
.It Ar
|
|
Restrict reports to the specified files.
|
|
.El
|
|
.Pp
|
|
The following fields are printed:
|
|
.Bl -tag -width MOUNT
|
|
.It Sy USER
|
|
The username of the owner of the process (effective uid).
|
|
.It Sy CMD
|
|
The command name of the process.
|
|
.It Sy PID
|
|
The process id.
|
|
.It Sy FD
|
|
The file number in the per-process open file table or one of the following
|
|
special names:
|
|
.Pp
|
|
.Bl -tag -width jail -offset indent -compact
|
|
.It Sy jail
|
|
jail root directory
|
|
.It Sy mmap
|
|
memory-mapped file
|
|
.It Sy root
|
|
root inode
|
|
.It Sy text
|
|
executable text inode
|
|
.It Sy tr
|
|
kernel trace file
|
|
.It Sy wd
|
|
current working directory
|
|
.El
|
|
.Pp
|
|
If the file number is followed by an asterisk
|
|
.Pq Ql * ,
|
|
the file is
|
|
not an inode, but rather a socket, FIFO, or there is an error.
|
|
In this case the remainder of the line does not
|
|
correspond to the remaining headers\(em the format of the line
|
|
is described later under
|
|
.Sx SOCKETS .
|
|
.It Sy MOUNT
|
|
If the
|
|
.Fl n
|
|
flag was not specified, this header is present and is the
|
|
pathname that the file system the file resides in is mounted on.
|
|
.It Sy DEV
|
|
If the
|
|
.Fl n
|
|
flag is specified, this header is present and is the
|
|
number of the device that this file resides in.
|
|
.It Sy INUM
|
|
The inode number of the file.
|
|
.It Sy MODE
|
|
The mode of the file.
|
|
If the
|
|
.Fl n
|
|
flag is not specified, the mode is printed
|
|
using a symbolic format (see
|
|
.Xr strmode 3 ) ;
|
|
otherwise, the mode is printed
|
|
as an octal number.
|
|
.It Sy SZ\&|DV
|
|
If the file is a semaphore,
|
|
prints the current value of the semaphore.
|
|
If the file is not a character or block special, prints the size of
|
|
the file in bytes.
|
|
Otherwise, if the
|
|
.Fl n
|
|
flag is not specified, prints
|
|
the name of the special file as located in
|
|
.Pa /dev .
|
|
If that cannot be
|
|
located, or the
|
|
.Fl n
|
|
flag is specified, prints the major/minor device
|
|
number that the special device refers to.
|
|
.It Sy R/W
|
|
This column describes the access mode that the file allows.
|
|
The letter
|
|
.Ql r
|
|
indicates open for reading;
|
|
the letter
|
|
.Ql w
|
|
indicates open for writing.
|
|
This field is useful when trying to find the processes that are
|
|
preventing a file system from being down graded to read-only.
|
|
.It Sy NAME
|
|
If filename arguments are specified and the
|
|
.Fl f
|
|
flag is not, then
|
|
this field is present and is the name associated with the given file.
|
|
Normally the name cannot be determined since there is no mapping
|
|
from an open file back to the directory entry that was used to open
|
|
that file.
|
|
Also, since different directory entries may reference
|
|
the same file (via
|
|
.Xr ln 1 ) ,
|
|
the name printed may not be the actual
|
|
name that the process originally used to open that file.
|
|
.El
|
|
.Sh SOCKETS
|
|
The formatting of open sockets depends on the protocol domain.
|
|
In all cases the first field is the domain name, the second field
|
|
is the socket type (stream, dgram, etc.), and the third is the socket
|
|
flags field (in hex).
|
|
The remaining fields are protocol dependent.
|
|
For TCP, it is the address of the tcpcb, and for UDP, the inpcb (socket pcb).
|
|
For UNIX-domain sockets, its the address of the socket pcb and the address
|
|
of the connected pcb (if connected).
|
|
Otherwise the protocol number and address of the socket itself are printed.
|
|
.Pp
|
|
For example, the addresses mentioned above are the addresses which the
|
|
.Ql netstat -A
|
|
command would print for TCP, UDP, and UNIX-domain.
|
|
Note that since pipes are implemented using sockets, a pipe appears as a
|
|
connected UNIX-domain stream socket.
|
|
A unidirectional UNIX-domain socket indicates the direction of flow with
|
|
an arrow
|
|
.Po Ql <-
|
|
or
|
|
.Ql ->
|
|
.Pc ,
|
|
and a full duplex socket shows a double arrow
|
|
.Pq Ql <-> .
|
|
.Pp
|
|
When the
|
|
.Fl s
|
|
flag is used, socket endpoint information is shown after the address of the
|
|
socket.
|
|
For internet sockets the local and remote addresses are shown, separated with
|
|
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 descending 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 ,
|
|
.Xr nfsstat 1 ,
|
|
.Xr procstat 1 ,
|
|
.Xr ps 1 ,
|
|
.Xr sockstat 1 ,
|
|
.Xr systat 1 ,
|
|
.Xr tcp 4 ,
|
|
.Xr unix 4 ,
|
|
.Xr iostat 8 ,
|
|
.Xr pstat 8 ,
|
|
.Xr vmstat 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in
|
|
.Bx 4.3 tahoe .
|
|
.Sh BUGS
|
|
Since
|
|
.Nm
|
|
takes a snapshot of the system, it is only correct for a very short period
|
|
of time.
|