xref: /freebsd/usr.bin/fstat/fstat.1 (revision 271c3a9060f2ee55607ebe146523f888e1db2654)
1.\" Copyright (c) 1987, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)fstat.1	8.3 (Berkeley) 2/25/94
33.\" $FreeBSD$
34.\"
35.Dd March 27, 2002
36.Dt FSTAT 1
37.Os
38.Sh NAME
39.Nm fstat
40.Nd identify active files
41.Sh SYNOPSIS
42.Nm
43.Op Fl fmnv
44.Op Fl M Ar core
45.Op Fl N Ar system
46.Op Fl p Ar pid
47.Op Fl u Ar user
48.Op Ar
49.Sh DESCRIPTION
50The
51.Nm
52utility identifies open files.
53A file is considered open by a process if it was explicitly opened,
54is the working directory, root directory, jail root directory,
55active executable text, or kernel trace file for that process.
56If no options are specified,
57.Nm
58reports on all open files in the system.
59.Pp
60The following options are available:
61.Bl -tag -width indent
62.It Fl f
63Restrict examination to files open in the same file systems as
64the named file arguments, or to the file system containing the
65current directory if there are no additional filename arguments.
66For example, to find all files open in the file system where the
67directory
68.Pa /usr/src
69resides, type
70.Dq Li fstat -f /usr/src .
71.It Fl M
72Extract values associated with the name list from the specified core
73instead of the default
74.Pa /dev/kmem .
75.It Fl N
76Extract the name list from the specified system instead of the default,
77which is the kernel image the system has booted from.
78.It Fl m
79Include memory-mapped files in the listing; normally these are excluded
80due to the extra processing required.
81.It Fl n
82Numerical format.
83Print the device number (maj,min) of the file system
84the file resides in rather than the mount point name; for special
85files, print the
86device number that the special device refers to rather than the filename
87in
88.Pa /dev ;
89and print the mode of the file in octal instead of symbolic form.
90.It Fl p
91Report all files open by the specified process.
92.It Fl u
93Report all files open by the specified user.
94.It Fl v
95Verbose mode.
96Print error messages upon failures to locate particular
97system data structures rather than silently ignoring them.
98Most of
99these data structures are dynamically created or deleted and it is
100possible for them to disappear while
101.Nm
102is running.
103This
104is normal and unavoidable since the rest of the system is running while
105.Nm
106itself is running.
107.It Ar
108Restrict reports to the specified files.
109.El
110.Pp
111The following fields are printed:
112.Bl -tag -width MOUNT
113.It Li USER
114The username of the owner of the process (effective uid).
115.It Li CMD
116The command name of the process.
117.It Li PID
118The process id.
119.It Li FD
120The file number in the per-process open file table or one of the following
121special names:
122.Pp
123.Bd -literal -offset indent -compact
124jail	- jail root directory
125mmap	- memory-mapped file
126root	- root inode
127text	- executable text inode
128tr	- kernel trace file
129wd 	- current working directory
130.Ed
131.Pp
132If the file number is followed by an asterisk (``*''), the file is
133not an inode, but rather a socket,
134.Tn FIFO ,
135or there is an error.
136In this case the remainder of the line does not
137correspond to the remaining headers -- the format of the line
138is described later under
139.Sx SOCKETS .
140.It Li MOUNT
141If the
142.Fl n
143flag was not specified, this header is present and is the
144pathname that the file system the file resides in is mounted on.
145.It Li DEV
146If the
147.Fl n
148flag is specified, this header is present and is the
149major/minor number of the device that this file resides in.
150.It Li INUM
151The inode number of the file.
152.It Li MODE
153The mode of the file.
154If the
155.Fl n
156flag is not specified, the mode is printed
157using a symbolic format (see
158.Xr strmode 3 ) ;
159otherwise, the mode is printed
160as an octal number.
161.It Li SZ\&|DV
162If the file is not a character or block special, prints the size of
163the file in bytes.
164Otherwise, if the
165.Fl n
166flag is not specified, prints
167the name of the special file as located in
168.Pa /dev .
169If that cannot be
170located, or the
171.Fl n
172flag is specified, prints the major/minor device
173number that the special device refers to.
174.It Li R/W
175This column describes the access mode that the file allows.
176The letter ``r'' indicates open for reading;
177the letter ``w'' indicates open for writing.
178This field is useful when trying to find the processes that are
179preventing a file system from being down graded to read-only.
180.It Li NAME
181If filename arguments are specified and the
182.Fl f
183flag is not, then
184this field is present and is the name associated with the given file.
185Normally the name cannot be determined since there is no mapping
186from an open file back to the directory entry that was used to open
187that file.
188Also, since different directory entries may reference
189the same file (via
190.Xr ln 1 ) ,
191the name printed may not be the actual
192name that the process originally used to open that file.
193.El
194.Sh SOCKETS
195The formating of open sockets depends on the protocol domain.
196In all cases the first field is the domain name, the second field
197is the socket type (stream, dgram, etc), and the third is the socket
198flags field (in hex).
199The remaining fields are protocol dependent.
200For tcp, it is the address of the tcpcb, and for udp, the inpcb (socket pcb).
201For unix domain sockets, its the address of the socket pcb and the address
202of the connected pcb (if connected).
203Otherwise the protocol number and address of the socket itself are printed.
204The attempt is to make enough information available to
205permit further analysis without duplicating
206.Xr netstat 1 .
207.Pp
208For example, the addresses mentioned above are the addresses which the
209.Dq Li netstat -A
210command would print for tcp, udp, and unixdomain.
211Note that since pipes are implemented using sockets, a pipe appears as a
212connected unix domain stream socket.
213A unidirectional unix domain socket indicates the direction of flow with
214an arrow (``<-'' or ``->''), and a full duplex socket shows a double arrow
215(``<->'').
216.Sh SEE ALSO
217.Xr netstat 1 ,
218.Xr nfsstat 1 ,
219.Xr ps 1 ,
220.Xr sockstat 1 ,
221.Xr systat 1 ,
222.Xr tcp 4 ,
223.Xr unix 4 ,
224.Xr iostat 8 ,
225.Xr pstat 8 ,
226.Xr vmstat 8
227.Sh HISTORY
228The
229.Nm
230command appeared in
231.Bx 4.3 tahoe .
232.Sh BUGS
233Since
234.Nm
235takes a snapshot of the system, it is only correct for a very short period
236of time.
237