Annotation of src/usr.bin/fstat/fstat.1, Revision 1.18
1.18 ! hugh 1: .\" $OpenBSD: fstat.1,v 1.17 2000/03/23 21:10:17 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.10 aaron 51: .Nm fstat
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,
57: .Nm fstat
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
73: instead of the default
74: .Pa /dev/kmem .
1.12 deraadt 75: .It Fl N Ar system
1.1 deraadt 76: Extract the name list from the specified system instead of the default
1.3 ccappuc 77: .Pa /bsd .
1.1 deraadt 78: .It Fl n
1.16 aaron 79: Numerical format.
80: Print the device number (maj,min) of the file system
1.17 aaron 81: the file resides in rather than the mount point name.
82: For special files, print the
1.1 deraadt 83: device number that the special device refers to rather than the filename
84: in
1.16 aaron 85: .Pa /dev .
86: Also, print the mode of the file in octal instead of symbolic form.
1.18 ! hugh 87: .It Fl o
! 88: Output file offset.
! 89: Follow the size field with the descriptor's offset.
! 90: Useful for checking progress as a process works through a large file.
1.12 deraadt 91: .It Fl p pid
1.1 deraadt 92: Report all files open by the specified process.
1.12 deraadt 93: .It Fl u user
1.1 deraadt 94: Report all files open by the specified user.
95: .It Fl v
1.16 aaron 96: Verbose mode.
97: Print error messages upon failures to locate particular
98: system data structures rather than silently ignoring them.
99: Most of these data structures are dynamically created or deleted and it is
1.1 deraadt 100: possible for them to disappear while
101: .Nm fstat
1.16 aaron 102: is running.
1.17 aaron 103: This is normal and unavoidable since the rest of the system is running while
1.1 deraadt 104: .Nm fstat
105: itself is running.
1.16 aaron 106: .It Ar file ...
1.1 deraadt 107: Restrict reports to the specified files.
108: .El
109: .Pp
110: The following fields are printed:
111: .Bl -tag -width MOUNT
112: .It Li USER
1.10 aaron 113: The username of the owner of the process (effective UID).
1.1 deraadt 114: .It Li CMD
115: The command name of the process.
116: .It Li PID
1.10 aaron 117: The process ID.
1.1 deraadt 118: .It Li FD
119: The file number in the per-process open file table or one of the following
120: special names:
121: .Pp
1.6 deraadt 122: .Bd -literal -ragged -offset indent -compact
1.1 deraadt 123: text - pure text inode
124: wd - current working directory
125: root - root inode
126: tr - kernel trace file
127: .Ed
128: .Pp
1.16 aaron 129: If the file number is followed by an asterisk
130: .Pq Ql * ,
131: the file is not an inode, but rather a socket,
1.1 deraadt 132: .Tn FIFO ,
133: or there is an error.
134: In this case the remainder of the line doesn't
135: correspond to the remaining headers -- the format of the line
136: is described later under
137: .Sx Sockets .
138: .It Li MOUNT
139: If the
140: .Fl n
141: flag wasn't specified, this header is present and is the
1.16 aaron 142: pathname that the file system the file resides in is mounted on.
1.1 deraadt 143: .It Li DEV
144: If the
145: .Fl n
146: flag is specified, this header is present and is the
147: major/minor number of the device that this file resides in.
148: .It Li INUM
149: The inode number of the file.
150: .It Li MODE
1.17 aaron 151: The mode of the file.
152: If the
1.1 deraadt 153: .Fl n
154: flag isn't specified, the mode is printed
155: using a symbolic format (see
156: .Xr strmode 3 ) ;
157: otherwise, the mode is printed
158: as an octal number.
159: .It Li SZ\&|DV
1.10 aaron 160: If the file is not a character or block special file, prints the size of
1.16 aaron 161: the file in bytes.
162: Otherwise, if the
1.1 deraadt 163: .Fl n
164: flag is not specified, prints
165: the name of the special file as located in
166: .Pa /dev .
1.16 aaron 167: If that cannot be located, or the
1.1 deraadt 168: .Fl n
169: flag is specified, prints the major/minor device
170: number that the special device refers to.
171: .It Li R/W
172: This column describes the access mode that the file allows.
1.16 aaron 173: The letter
174: .Sq r
175: indicates open for reading;
176: the letter
177: .Sq w
178: indicates open for writing.
1.1 deraadt 179: This field is useful when trying to find the processes that are
1.16 aaron 180: preventing a file system from being downgraded to read-only.
1.1 deraadt 181: .It Li NAME
182: If filename arguments are specified and the
183: .Fl f
184: flag is not, then
185: this field is present and is the name associated with the given file.
186: Normally the name cannot be determined since there is no mapping
187: from an open file back to the directory entry that was used to open
1.16 aaron 188: that file.
189: Also, since different directory entries may reference
1.1 deraadt 190: the same file (via
191: .Xr ln 2 ) ,
192: the name printed may not be the actual
193: name that the process originally used to open that file.
194: .El
195: .Sh SOCKETS
1.13 alex 196: The formatting of open sockets depends on the protocol domain.
1.1 deraadt 197: In all cases the first field is the domain name, the second field
198: is the socket type (stream, dgram, etc), and the third is the socket
199: flags field (in hex).
200: The remaining fields are protocol dependent.
1.10 aaron 201: For TCP, it is the address of the tcpcb, and for UDP, the inpcb (socket pcb).
202: For Unix domain sockets, it's the address of the socket pcb and the address
1.1 deraadt 203: of the connected pcb (if connected).
204: Otherwise the protocol number and address of the socket itself are printed.
1.11 aaron 205: The attempt is to make enough information available to
1.1 deraadt 206: permit further analysis without duplicating
207: .Xr netstat 1 .
208: .Pp
209: For example, the addresses mentioned above are the addresses which the
1.16 aaron 210: .Ic netstat -A
1.10 aaron 211: command would print for TCP, UDP, and Unix domain.
1.1 deraadt 212: Note that since pipes are implemented using sockets, a pipe appears as a
1.10 aaron 213: connected Unix domain stream socket.
214: A unidirectional Unix domain socket indicates the direction of flow with
1.16 aaron 215: an arrow
216: .Pf ( Dq <-
217: or
218: .Dq -> ) ,
219: and a full duplex socket shows a double arrow
220: .Pq Dq <-> ) .
1.4 deraadt 221: .Pp
222: For AF_INET sockets,
223: .Nm fstat
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 BUGS
247: Since
248: .Nm fstat
249: takes a snapshot of the system, it is only correct for a very short period
250: of time.
1.4 deraadt 251: .Pp
1.9 deraadt 252: Moreover, because DNS resolution and YP lookups cause many file
1.4 deraadt 253: descriptor changes,
254: .Nm fstat
1.7 deraadt 255: does not attempt to translate the internet address and port numbers into
1.4 deraadt 256: symbolic names.
1.1 deraadt 257: .Sh SEE ALSO
258: .Xr netstat 1 ,
259: .Xr nfsstat 1 ,
260: .Xr ps 1 ,
261: .Xr systat 1 ,
262: .Xr iostat 8 ,
263: .Xr pstat 8 ,
264: .Xr vmstat 8
265: .Sh HISTORY
266: The
267: .Nm
268: command appeared in
269: .Bx 4.3 tahoe .
![[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