jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: fstat.1,v 1.60 2025/12/12 06:33:18 tb Exp $
2.\"
3.\" Copyright (c) 1987, 1991, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. Neither the name of the University nor the names of its contributors
15.\" may be used to endorse or promote products derived from this software
16.\" without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" from: @(#)fstat.1 8.3 (Berkeley) 2/25/94
31.\"
32.Dd $Mdocdate: December 12 2025 $
33.Dt FSTAT 1
34.Os
35.Sh NAME
36.Nm fstat
37.Nd display status of open files
38.Sh SYNOPSIS
39.Nm fstat
40.Op Fl fnosv
41.Op Fl M Ar core
42.Op Fl N Ar system
43.Op Fl p Ar pid
44.Op Fl u Ar user
45.Op Ar
46.Sh DESCRIPTION
47.Nm
48identifies open files.
49A file is considered open by a process if it was explicitly opened,
50is the working directory, root directory, active executable text, or kernel
51trace file for that process.
52If no options are specified,
53.Nm
54reports on all open files in the system.
55.Pp
56The options are as follows:
57.Bl -tag -width Ds
58.It Fl f
59Restrict examination to files open in the same file systems as
60the named file arguments, or to the file system containing the
61current directory if there are no additional filename arguments.
62For example, to find all files open in the file system where the
63directory
64.Pa /usr/src
65resides, type
66.Pp
67.Dl # fstat -f /usr/src
68.It Fl M Ar core
69Extract values associated with the name list from the specified core
70instead of the running kernel.
71.It Fl N Ar system
72Extract the name list from the specified system instead of the running kernel.
73.It Fl n
74Numerical format.
75Print the device number (maj,min) of the file system
76the file resides in rather than the mount point name.
77For special files, print the
78device number that the special device refers to rather than the filename
79in
80.Pa /dev .
81Also, print the mode of the file in octal instead of symbolic form.
82.It Fl o
83Output file offset.
84Follow the size field with the descriptor's offset.
85Useful for checking progress as a process works through a large file.
86This information is only visible to the user or superuser.
87.It Fl p Ar pid
88Report all files open by the specified process.
89This option may be specified multiple times.
90.It Fl s
91Report per file io statistics in two additional columns
92.Sq XFERS
93and
94.Sq KBYTES .
95This information is only visible to the user or superuser.
96.It Fl u Ar user
97Report all files open by the specified user.
98This option may be specified multiple times.
99.It Fl v
100Verbose mode.
101Print error messages upon failures to locate particular
102system data structures rather than silently ignoring them.
103Most of these data structures are dynamically created or deleted and it is
104possible for them to disappear while
105.Nm
106is running.
107This is normal and unavoidable since the rest of the system is running while
108.Nm
109itself is running.
110.It Ar
111Restrict reports to the specified files.
112.El
113.Pp
114The following fields are printed:
115.Bl -tag -width MOUNT
116.It Li USER
117The username of the owner of the process (effective UID).
118.It Li CMD
119The command name of the process.
120.It Li PID
121The process ID.
122.It Li FD
123The file number in the per-process open file table or one of the following
124special names:
125.Pp
126.Bl -tag -width "text" -offset indent -compact
127.It text
128executable text inode
129.It wd
130current working directory
131.It root
132root inode
133.It tr
134kernel trace file
135.El
136.Pp
137If the file number is followed by an asterisk
138.Pq Ql * ,
139the file is not an inode, but rather a socket, or there is an error.
140In this case the remainder of the line doesn't
141correspond to the remaining headers \(em the format of the line
142is described later under
143.Sx SOCKETS .
144.It Li MOUNT
145If the
146.Fl n
147flag wasn't specified, this header is present and is the
148pathname that the file system the file resides in is mounted on.
149.It Li DEV
150If the
151.Fl n
152flag is specified, this header is present and is the
153major/minor number of the device that this file resides in.
154.It Li INUM
155The inode number of the file.
156It will be followed by an asterisk
157.Pq Ql *
158if the inode is unlinked from disk.
159.It Li MODE
160The mode of the file.
161If the
162.Fl n
163flag isn't specified, the mode is printed
164using a symbolic format (see
165.Xr strmode 3 ) ;
166otherwise, the mode is printed
167as an octal number.
168.It Li R/W
169This column describes the properties of the file descriptor:
170.Pp
171.Bl -tag -width indent -compact
172.It r
173Open for reading
174.It w
175Open for writing
176.It e
177close-on-exec flag is set
178.It f
179close-on-fork flag is set
180.It p
181Opened after
182.Xr pledge 2
183.El
184.Pp
185This field is useful when trying to find the processes that are
186preventing a file system from being downgraded to read-only.
187.It Li SZ | DV
188If the file is not a character or block special file, prints the size of
189the file in bytes.
190Otherwise, if the
191.Fl n
192flag is not specified, prints
193the name of the special file as located in
194.Pa /dev .
195If that cannot be located, or the
196.Fl n
197flag is specified, prints the major/minor device
198number that the special device refers to.
199.It Li NAME
200If filename arguments are specified and the
201.Fl f
202flag is not, then
203this field is present and is the name associated with the given file.
204Normally the name cannot be determined since there is no mapping
205from an open file back to the directory entry that was used to open
206that file.
207Also, since different directory entries may reference
208the same file (via
209.Xr ln 1 ) ,
210the name printed may not be the actual
211name that the process originally used to open that file.
212.It Li XFERS
213Displays number of total data transfers performed on the file.
214.It Li KBYTES
215Displays total number of Kbytes written and read to the file.
216.El
217.Sh SOCKETS
218The formatting of open sockets depends on the protocol domain.
219In all cases the first field is the domain name
220and the second field is the socket type (stream, dgram, etc).
221The remaining fields are protocol dependent.
222For TCP, it is the address of the tcpcb, and for UDP, the inpcb (socket pcb).
223For
224.Ux Ns -domain
225sockets, it's the address of the socket pcb and the address
226of the connected pcb (if connected).
227Otherwise the protocol number and address of the socket itself are printed.
228The attempt is to make enough information available to
229permit further analysis without duplicating
230.Xr netstat 1 .
231.Pp
232For example, the addresses mentioned above are the addresses which the
233.Ic netstat -A
234command would print for TCP, UDP, and
235.Ux Ns -domain.
236These addresses are only visible to the superuser, otherwise 0x0 is printed.
237Sockets that have been disassociated from a protocol control block
238will always print 0x0.
239A unidirectional
240.Ux Ns -domain
241socket indicates the direction of flow with
242an arrow
243.Pf ( Dq <-
244or
245.Dq -> ) ,
246and a full duplex socket shows a double arrow
247.Pq Dq <-> .
248.Pp
249For
250.Dv AF_INET
251and
252.Dv AF_INET6
253sockets,
254.Nm
255also attempts to print the internet address and port for the
256local end of a connection.
257If the socket is connected, it also prints the remote internet address
258and port.
259A
260.Ql *
261is used to indicate an
262.Dv INADDR_ANY
263binding.
264In this case, the
265use of the arrow
266.Pf ( Dq <--
267or
268.Dq --> )
269indicates the direction the socket connection was created.
270.Pp
271If the socket has been spliced to or from another socket (see
272.Xr setsockopt 2
273and
274.Dv SO_SPLICE )
275then
276.Nm
277prints a thick arrow
278.Pf ( Dq <==> ,
279.Dq <== ,
280or
281.Dq ==> ) ,
282followed by the address and endpoint information of the other socket
283in the splice,
284if available.
285.Sh PIPES
286Every pipe is printed as an address which is the same for both sides of
287the pipe and a state that is built of the letters
288.Dq RWE .
289W \- The pipe blocks waiting for the reader to read data.
290R \- The pipe blocks waiting for the writer to write data.
291E \- The pipe is in EOF state.
292.Sh KQUEUE
293Each
294.Xr kqueue 2
295is printed with some information as to queue length.
296Since these things are normally serviced quickly, it is likely that
297nothing of real importance can be discerned.
298.Sh SEE ALSO
299.Xr netstat 1 ,
300.Xr nfsstat 1 ,
301.Xr ps 1 ,
302.Xr systat 1 ,
303.Xr top 1 ,
304.Xr iostat 8 ,
305.Xr pstat 8 ,
306.Xr tcpdrop 8 ,
307.Xr vmstat 8
308.Sh HISTORY
309The
310.Nm
311command appeared in
312.Bx 4.3 tahoe .
313.Sh CAVEATS
314Sockets in use by the kernel, such as those opened by
315.Xr nfsd 8 ,
316will not be seen by
317.Nm ,
318even though they appear in
319.Xr netstat 1 .
320.Sh BUGS
321Since
322.Nm
323takes a snapshot of the system, it is only correct for a very short period
324of time.
325.Pp
326Moreover, because DNS resolution and YP lookups cause many file
327descriptor changes,
328.Nm
329does not attempt to translate the internet address and port numbers into
330symbolic names.