Annotation of src/usr.bin/fstat/fstat.1, Revision 1.59
1.59 ! jmc 1: .\" $OpenBSD: fstat.1,v 1.58 2019/03/31 01:08:09 procter Exp $
1.16 aaron 2: .\"
1.1 deraadt 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.
1.25 millert 14: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 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: .\"
1.59 ! jmc 32: .Dd $Mdocdate: March 31 2019 $
1.1 deraadt 33: .Dt FSTAT 1
1.11 aaron 34: .Os
1.1 deraadt 35: .Sh NAME
36: .Nm fstat
1.15 pjanzen 37: .Nd display status of open files
1.1 deraadt 38: .Sh SYNOPSIS
39: .Nm fstat
1.36 mickey 40: .Op Fl fnosv
1.1 deraadt 41: .Op Fl M Ar core
42: .Op Fl N Ar system
43: .Op Fl p Ar pid
44: .Op Fl u Ar user
1.41 millert 45: .Op Ar
1.1 deraadt 46: .Sh DESCRIPTION
1.19 aaron 47: .Nm
1.1 deraadt 48: identifies open files.
49: A file is considered open by a process if it was explicitly opened,
1.42 millert 50: is the working directory, root directory, active executable text, or kernel
1.1 deraadt 51: trace file for that process.
52: If no options are specified,
1.19 aaron 53: .Nm
1.1 deraadt 54: reports on all open files in the system.
55: .Pp
1.14 aaron 56: The options are as follows:
1.1 deraadt 57: .Bl -tag -width Ds
58: .It Fl f
1.16 aaron 59: Restrict examination to files open in the same file systems as
60: the named file arguments, or to the file system containing the
1.1 deraadt 61: current directory if there are no additional filename arguments.
1.16 aaron 62: For example, to find all files open in the file system where the
1.1 deraadt 63: directory
64: .Pa /usr/src
65: resides, type
1.28 deraadt 66: .Pp
1.31 jmc 67: .Dl # fstat -f /usr/src
1.12 deraadt 68: .It Fl M Ar core
1.1 deraadt 69: Extract values associated with the name list from the specified core
1.20 miod 70: instead of the running kernel.
1.12 deraadt 71: .It Fl N Ar system
1.20 miod 72: Extract the name list from the specified system instead of the running kernel.
1.1 deraadt 73: .It Fl n
1.16 aaron 74: Numerical format.
75: Print the device number (maj,min) of the file system
1.17 aaron 76: the file resides in rather than the mount point name.
77: For special files, print the
1.1 deraadt 78: device number that the special device refers to rather than the filename
79: in
1.16 aaron 80: .Pa /dev .
81: Also, print the mode of the file in octal instead of symbolic form.
1.18 hugh 82: .It Fl o
83: Output file offset.
84: Follow the size field with the descriptor's offset.
85: Useful for checking progress as a process works through a large file.
1.39 deraadt 86: This information is only visible to the user or superuser.
1.19 aaron 87: .It Fl p Ar pid
1.1 deraadt 88: Report all files open by the specified process.
1.57 martijn 89: This option may be specified multiple times.
1.36 mickey 90: .It Fl s
91: Report per file io statistics in two additional columns
92: .Sq XFERS
93: and
94: .Sq KBYTES .
1.39 deraadt 95: This information is only visible to the user or superuser.
1.19 aaron 96: .It Fl u Ar user
1.1 deraadt 97: Report all files open by the specified user.
1.57 martijn 98: This option may be specified multiple times.
1.1 deraadt 99: .It Fl v
1.16 aaron 100: Verbose mode.
101: Print error messages upon failures to locate particular
102: system data structures rather than silently ignoring them.
103: Most of these data structures are dynamically created or deleted and it is
1.1 deraadt 104: possible for them to disappear while
1.19 aaron 105: .Nm
1.16 aaron 106: is running.
1.17 aaron 107: This is normal and unavoidable since the rest of the system is running while
1.19 aaron 108: .Nm
1.1 deraadt 109: itself is running.
1.43 sobrado 110: .It Ar
1.1 deraadt 111: Restrict reports to the specified files.
112: .El
113: .Pp
114: The following fields are printed:
115: .Bl -tag -width MOUNT
116: .It Li USER
1.10 aaron 117: The username of the owner of the process (effective UID).
1.1 deraadt 118: .It Li CMD
119: The command name of the process.
120: .It Li PID
1.10 aaron 121: The process ID.
1.1 deraadt 122: .It Li FD
123: The file number in the per-process open file table or one of the following
124: special names:
1.58 procter 125: .Pp
1.59 ! jmc 126: .Bl -tag -width "text" -offset indent -compact
1.58 procter 127: .It text
128: executable text inode
129: .It wd
130: current working directory
131: .It root
132: root inode
133: .It tr
134: kernel trace file
135: .El
1.1 deraadt 136: .Pp
1.16 aaron 137: If the file number is followed by an asterisk
138: .Pq Ql * ,
1.33 pedro 139: the file is not an inode, but rather a socket, or there is an error.
1.1 deraadt 140: In this case the remainder of the line doesn't
1.56 schwarze 141: correspond to the remaining headers \(em the format of the line
1.1 deraadt 142: is described later under
1.27 jmc 143: .Sx SOCKETS .
1.1 deraadt 144: .It Li MOUNT
145: If the
146: .Fl n
147: flag wasn't specified, this header is present and is the
1.16 aaron 148: pathname that the file system the file resides in is mounted on.
1.1 deraadt 149: .It Li DEV
150: If the
151: .Fl n
152: flag is specified, this header is present and is the
153: major/minor number of the device that this file resides in.
154: .It Li INUM
155: The inode number of the file.
1.53 guenther 156: It will be followed by an asterisk
157: .Pq Ql *
158: if the inode is unlinked from disk.
1.1 deraadt 159: .It Li MODE
1.17 aaron 160: The mode of the file.
161: If the
1.1 deraadt 162: .Fl n
163: flag isn't specified, the mode is printed
164: using a symbolic format (see
165: .Xr strmode 3 ) ;
166: otherwise, the mode is printed
167: as an octal number.
1.38 sobrado 168: .It Li R/W
1.54 deraadt 169: This column describes the properties of the file descriptor:
1.58 procter 170: .Pp
171: .Bl -tag -width indent -compact
172: .It r
173: Open for reading
174: .It w
175: Open for writing
176: .It e
177: close-on-exec flag is set
178: .It p
179: Opened after
180: .Xr pledge 2
181: .El
1.54 deraadt 182: .Pp
1.38 sobrado 183: This field is useful when trying to find the processes that are
184: preventing a file system from being downgraded to read-only.
1.46 jmc 185: .It Li SZ | DV
1.10 aaron 186: If the file is not a character or block special file, prints the size of
1.16 aaron 187: the file in bytes.
188: Otherwise, if the
1.1 deraadt 189: .Fl n
190: flag is not specified, prints
191: the name of the special file as located in
192: .Pa /dev .
1.16 aaron 193: If that cannot be located, or the
1.1 deraadt 194: .Fl n
195: flag is specified, prints the major/minor device
196: number that the special device refers to.
197: .It Li NAME
198: If filename arguments are specified and the
199: .Fl f
200: flag is not, then
201: this field is present and is the name associated with the given file.
202: Normally the name cannot be determined since there is no mapping
203: from an open file back to the directory entry that was used to open
1.16 aaron 204: that file.
205: Also, since different directory entries may reference
1.1 deraadt 206: the same file (via
1.24 jmc 207: .Xr ln 1 ) ,
1.1 deraadt 208: the name printed may not be the actual
209: name that the process originally used to open that file.
1.36 mickey 210: .It Li XFERS
1.47 jmc 211: Displays number of total data transfers performed on the file.
1.36 mickey 212: .It Li KBYTES
213: Displays total number of Kbytes written and read to the file.
1.1 deraadt 214: .El
215: .Sh SOCKETS
1.13 alex 216: The formatting of open sockets depends on the protocol domain.
1.40 jmc 217: In all cases the first field is the domain name
218: and the second field is the socket type (stream, dgram, etc).
1.1 deraadt 219: The remaining fields are protocol dependent.
1.10 aaron 220: For TCP, it is the address of the tcpcb, and for UDP, the inpcb (socket pcb).
1.44 sobrado 221: For
1.45 sobrado 222: .Ux Ns -domain
223: sockets, it's the address of the socket pcb and the address
1.1 deraadt 224: of the connected pcb (if connected).
225: Otherwise the protocol number and address of the socket itself are printed.
1.11 aaron 226: The attempt is to make enough information available to
1.1 deraadt 227: permit further analysis without duplicating
228: .Xr netstat 1 .
229: .Pp
230: For example, the addresses mentioned above are the addresses which the
1.16 aaron 231: .Ic netstat -A
1.44 sobrado 232: command would print for TCP, UDP, and
1.45 sobrado 233: .Ux Ns -domain.
1.55 sthen 234: These addresses are only visible to the superuser, otherwise 0x0 is printed.
235: Sockets that have been disassociated from a protocol control block
236: will always print 0x0.
1.44 sobrado 237: A unidirectional
1.45 sobrado 238: .Ux Ns -domain
239: socket indicates the direction of flow with
1.16 aaron 240: an arrow
241: .Pf ( Dq <-
242: or
243: .Dq -> ) ,
244: and a full duplex socket shows a double arrow
1.26 jmc 245: .Pq Dq <-> .
1.4 deraadt 246: .Pp
1.19 aaron 247: For
248: .Dv AF_INET
1.48 guenther 249: and
250: .Dv AF_INET6
1.19 aaron 251: sockets,
252: .Nm
1.4 deraadt 253: also attempts to print the internet address and port for the
254: local end of a connection.
255: If the socket is connected, it also prints the remote internet address
256: and port.
1.16 aaron 257: A
258: .Ql *
259: is used to indicate an
260: .Dv INADDR_ANY
261: binding.
262: In this case, the
263: use of the arrow
264: .Pf ( Dq <--
265: or
266: .Dq --> )
267: indicates the direction the socket connection was created.
1.48 guenther 268: .Pp
1.51 jmc 269: If the socket has been spliced to or from another socket (see
1.48 guenther 270: .Xr setsockopt 2
271: and
1.49 jmc 272: .Dv SO_SPLICE )
273: then
1.48 guenther 274: .Nm
275: prints a thick arrow
276: .Pf ( Dq <==> ,
277: .Dq <== ,
278: or
279: .Dq ==> ) ,
280: followed by the address and endpoint information of the other socket
281: in the splice,
282: if available.
1.8 art 283: .Sh PIPES
284: Every pipe is printed as an address which is the same for both sides of
1.16 aaron 285: the pipe and a state that is built of the letters
286: .Dq RWE .
1.26 jmc 287: W \- The pipe blocks waiting for the reader to read data.
288: R \- The pipe blocks waiting for the writer to write data.
289: E \- The pipe is in EOF state.
1.21 deraadt 290: .Sh KQUEUE
1.22 deraadt 291: Each
292: .Xr kqueue 2
293: is printed with some information as to queue length.
1.23 avsm 294: Since these things are normally serviced quickly, it is likely that
1.21 deraadt 295: nothing of real importance can be discerned.
1.1 deraadt 296: .Sh SEE ALSO
297: .Xr netstat 1 ,
298: .Xr nfsstat 1 ,
299: .Xr ps 1 ,
300: .Xr systat 1 ,
1.32 jmc 301: .Xr top 1 ,
1.1 deraadt 302: .Xr iostat 8 ,
303: .Xr pstat 8 ,
1.30 jmc 304: .Xr tcpdrop 8 ,
1.1 deraadt 305: .Xr vmstat 8
306: .Sh HISTORY
307: The
308: .Nm
309: command appeared in
310: .Bx 4.3 tahoe .
1.29 otto 311: .Sh CAVEATS
312: Sockets in use by the kernel, such as those opened by
313: .Xr nfsd 8 ,
314: will not be seen by
315: .Nm ,
316: even though they appear in
317: .Xr netstat 1 .
1.19 aaron 318: .Sh BUGS
319: Since
320: .Nm
321: takes a snapshot of the system, it is only correct for a very short period
322: of time.
323: .Pp
324: Moreover, because DNS resolution and YP lookups cause many file
325: descriptor changes,
326: .Nm
327: does not attempt to translate the internet address and port numbers into
328: symbolic names.
![[BACK]](/icons/back.gif){kind=icon}
Return to fstat.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / fstat