Annotation of src/usr.bin/fstat/fstat.1, Revision 1.20
1.20 ! miod 1: .\" $OpenBSD: fstat.1,v 1.19 2000/11/10 05:10:27 aaron 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.
14: .\" 3. All advertising materials mentioning features or use of this software
15: .\" must display the following acknowledgement:
16: .\" This product includes software developed by the University of
17: .\" California, Berkeley and its contributors.
18: .\" 4. Neither the name of the University nor the names of its contributors
19: .\" may be used to endorse or promote products derived from this software
20: .\" without specific prior written permission.
21: .\"
22: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32: .\" SUCH DAMAGE.
33: .\"
34: .\" from: @(#)fstat.1 8.3 (Berkeley) 2/25/94
35: .\"
36: .Dd February 25, 1994
37: .Dt FSTAT 1
1.11 aaron 38: .Os
1.1 deraadt 39: .Sh NAME
40: .Nm fstat
1.15 pjanzen 41: .Nd display status of open files
1.1 deraadt 42: .Sh SYNOPSIS
43: .Nm fstat
1.18 hugh 44: .Op Fl fnov
1.1 deraadt 45: .Op Fl M Ar core
46: .Op Fl N Ar system
47: .Op Fl p Ar pid
48: .Op Fl u Ar user
1.16 aaron 49: .Op Ar file ...
1.1 deraadt 50: .Sh DESCRIPTION
1.19 aaron 51: .Nm
1.1 deraadt 52: identifies open files.
53: A file is considered open by a process if it was explicitly opened,
54: is the working directory, root directory, active pure text, or kernel
55: trace file for that process.
56: If no options are specified,
1.19 aaron 57: .Nm
1.1 deraadt 58: reports on all open files in the system.
59: .Pp
1.14 aaron 60: The options are as follows:
1.1 deraadt 61: .Bl -tag -width Ds
62: .It Fl f
1.16 aaron 63: Restrict examination to files open in the same file systems as
64: the named file arguments, or to the file system containing the
1.1 deraadt 65: current directory if there are no additional filename arguments.
1.16 aaron 66: For example, to find all files open in the file system where the
1.1 deraadt 67: directory
68: .Pa /usr/src
69: resides, type
1.16 aaron 70: .Ic fstat -f /usr/src .
1.12 deraadt 71: .It Fl M Ar core
1.1 deraadt 72: Extract values associated with the name list from the specified core
1.20 ! miod 73: instead of the running kernel.
1.12 deraadt 74: .It Fl N Ar system
1.20 ! miod 75: Extract the name list from the specified system instead of the running kernel.
1.1 deraadt 76: .It Fl n
1.16 aaron 77: Numerical format.
78: Print the device number (maj,min) of the file system
1.17 aaron 79: the file resides in rather than the mount point name.
80: For special files, print the
1.1 deraadt 81: device number that the special device refers to rather than the filename
82: in
1.16 aaron 83: .Pa /dev .
84: Also, print the mode of the file in octal instead of symbolic form.
1.18 hugh 85: .It Fl o
86: Output file offset.
87: Follow the size field with the descriptor's offset.
88: Useful for checking progress as a process works through a large file.
1.19 aaron 89: .It Fl p Ar pid
1.1 deraadt 90: Report all files open by the specified process.
1.19 aaron 91: .It Fl u Ar user
1.1 deraadt 92: Report all files open by the specified user.
93: .It Fl v
1.16 aaron 94: Verbose mode.
95: Print error messages upon failures to locate particular
96: system data structures rather than silently ignoring them.
97: Most of these data structures are dynamically created or deleted and it is
1.1 deraadt 98: possible for them to disappear while
1.19 aaron 99: .Nm
1.16 aaron 100: is running.
1.17 aaron 101: This is normal and unavoidable since the rest of the system is running while
1.19 aaron 102: .Nm
1.1 deraadt 103: itself is running.
1.16 aaron 104: .It Ar file ...
1.1 deraadt 105: Restrict reports to the specified files.
106: .El
107: .Pp
108: The following fields are printed:
109: .Bl -tag -width MOUNT
110: .It Li USER
1.10 aaron 111: The username of the owner of the process (effective UID).
1.1 deraadt 112: .It Li CMD
113: The command name of the process.
114: .It Li PID
1.10 aaron 115: The process ID.
1.1 deraadt 116: .It Li FD
117: The file number in the per-process open file table or one of the following
118: special names:
119: .Pp
1.6 deraadt 120: .Bd -literal -ragged -offset indent -compact
1.1 deraadt 121: text - pure text inode
122: wd - current working directory
123: root - root inode
124: tr - kernel trace file
125: .Ed
126: .Pp
1.16 aaron 127: If the file number is followed by an asterisk
128: .Pq Ql * ,
129: the file is not an inode, but rather a socket,
1.1 deraadt 130: .Tn FIFO ,
131: or there is an error.
132: In this case the remainder of the line doesn't
133: correspond to the remaining headers -- the format of the line
134: is described later under
135: .Sx Sockets .
136: .It Li MOUNT
137: If the
138: .Fl n
139: flag wasn't specified, this header is present and is the
1.16 aaron 140: pathname that the file system the file resides in is mounted on.
1.1 deraadt 141: .It Li DEV
142: If the
143: .Fl n
144: flag is specified, this header is present and is the
145: major/minor number of the device that this file resides in.
146: .It Li INUM
147: The inode number of the file.
148: .It Li MODE
1.17 aaron 149: The mode of the file.
150: If the
1.1 deraadt 151: .Fl n
152: flag isn't specified, the mode is printed
153: using a symbolic format (see
154: .Xr strmode 3 ) ;
155: otherwise, the mode is printed
156: as an octal number.
157: .It Li SZ\&|DV
1.10 aaron 158: If the file is not a character or block special file, prints the size of
1.16 aaron 159: the file in bytes.
160: Otherwise, if the
1.1 deraadt 161: .Fl n
162: flag is not specified, prints
163: the name of the special file as located in
164: .Pa /dev .
1.16 aaron 165: If that cannot be located, or the
1.1 deraadt 166: .Fl n
167: flag is specified, prints the major/minor device
168: number that the special device refers to.
169: .It Li R/W
170: This column describes the access mode that the file allows.
1.16 aaron 171: The letter
172: .Sq r
173: indicates open for reading;
174: the letter
175: .Sq w
176: indicates open for writing.
1.1 deraadt 177: This field is useful when trying to find the processes that are
1.16 aaron 178: preventing a file system from being downgraded to read-only.
1.1 deraadt 179: .It Li NAME
180: If filename arguments are specified and the
181: .Fl f
182: flag is not, then
183: this field is present and is the name associated with the given file.
184: Normally the name cannot be determined since there is no mapping
185: from an open file back to the directory entry that was used to open
1.16 aaron 186: that file.
187: Also, since different directory entries may reference
1.1 deraadt 188: the same file (via
189: .Xr ln 2 ) ,
190: the name printed may not be the actual
191: name that the process originally used to open that file.
192: .El
193: .Sh SOCKETS
1.13 alex 194: The formatting of open sockets depends on the protocol domain.
1.1 deraadt 195: In all cases the first field is the domain name, the second field
196: is the socket type (stream, dgram, etc), and the third is the socket
197: flags field (in hex).
198: The remaining fields are protocol dependent.
1.10 aaron 199: For TCP, it is the address of the tcpcb, and for UDP, the inpcb (socket pcb).
200: For Unix domain sockets, it's the address of the socket pcb and the address
1.1 deraadt 201: of the connected pcb (if connected).
202: Otherwise the protocol number and address of the socket itself are printed.
1.11 aaron 203: The attempt is to make enough information available to
1.1 deraadt 204: permit further analysis without duplicating
205: .Xr netstat 1 .
206: .Pp
207: For example, the addresses mentioned above are the addresses which the
1.16 aaron 208: .Ic netstat -A
1.10 aaron 209: command would print for TCP, UDP, and Unix domain.
1.1 deraadt 210: Note that since pipes are implemented using sockets, a pipe appears as a
1.10 aaron 211: connected Unix domain stream socket.
212: A unidirectional Unix domain socket indicates the direction of flow with
1.16 aaron 213: an arrow
214: .Pf ( Dq <-
215: or
216: .Dq -> ) ,
217: and a full duplex socket shows a double arrow
218: .Pq Dq <-> ) .
1.4 deraadt 219: .Pp
1.19 aaron 220: For
221: .Dv AF_INET
222: sockets,
223: .Nm
1.4 deraadt 224: also attempts to print the internet address and port for the
225: local end of a connection.
226: If the socket is connected, it also prints the remote internet address
227: and port.
1.16 aaron 228: A
229: .Ql *
230: is used to indicate an
231: .Dv INADDR_ANY
232: binding.
233: In this case, the
234: use of the arrow
235: .Pf ( Dq <--
236: or
237: .Dq --> )
238: indicates the direction the socket connection was created.
1.8 art 239: .Sh PIPES
240: Every pipe is printed as an address which is the same for both sides of
1.16 aaron 241: the pipe and a state that is built of the letters
242: .Dq RWE .
1.8 art 243: W - The pipe blocks waiting for the reader to read data.
244: R - The pipe blocks waiting for the writer to write data.
245: E - The pipe is in EOF state.
1.1 deraadt 246: .Sh SEE ALSO
247: .Xr netstat 1 ,
248: .Xr nfsstat 1 ,
249: .Xr ps 1 ,
250: .Xr systat 1 ,
251: .Xr iostat 8 ,
252: .Xr pstat 8 ,
253: .Xr vmstat 8
254: .Sh HISTORY
255: The
256: .Nm
257: command appeared in
258: .Bx 4.3 tahoe .
1.19 aaron 259: .Sh BUGS
260: Since
261: .Nm
262: takes a snapshot of the system, it is only correct for a very short period
263: of time.
264: .Pp
265: Moreover, because DNS resolution and YP lookups cause many file
266: descriptor changes,
267: .Nm
268: does not attempt to translate the internet address and port numbers into
269: symbolic names.