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