1.\" $OpenBSD: fstat.1,v 1.31 2004/07/13 23:36:56 jmc 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 February 25, 1994 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 fnov 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 file ... 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 pure 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. 86.It Fl p Ar pid 87Report all files open by the specified process. 88.It Fl u Ar user 89Report all files open by the specified user. 90.It Fl v 91Verbose mode. 92Print error messages upon failures to locate particular 93system data structures rather than silently ignoring them. 94Most of these data structures are dynamically created or deleted and it is 95possible for them to disappear while 96.Nm 97is running. 98This is normal and unavoidable since the rest of the system is running while 99.Nm 100itself is running. 101.It Ar file ... 102Restrict reports to the specified files. 103.El 104.Pp 105The following fields are printed: 106.Bl -tag -width MOUNT 107.It Li USER 108The username of the owner of the process (effective UID). 109.It Li CMD 110The command name of the process. 111.It Li PID 112The process ID. 113.It Li FD 114The file number in the per-process open file table or one of the following 115special names: 116.Bd -literal -offset indent 117text \- pure text inode 118wd \- current working directory 119root \- root inode 120tr \- kernel trace file 121.Ed 122.Pp 123If the file number is followed by an asterisk 124.Pq Ql * , 125the file is not an inode, but rather a socket, 126.Tn FIFO , 127or there is an error. 128In this case the remainder of the line doesn't 129correspond to the remaining headers -- the format of the line 130is described later under 131.Sx SOCKETS . 132.It Li MOUNT 133If the 134.Fl n 135flag wasn't specified, this header is present and is the 136pathname that the file system the file resides in is mounted on. 137.It Li DEV 138If the 139.Fl n 140flag is specified, this header is present and is the 141major/minor number of the device that this file resides in. 142.It Li INUM 143The inode number of the file. 144.It Li MODE 145The mode of the file. 146If the 147.Fl n 148flag isn't specified, the mode is printed 149using a symbolic format (see 150.Xr strmode 3 ) ; 151otherwise, the mode is printed 152as an octal number. 153.It Li SZ\&|DV 154If the file is not a character or block special file, prints the size of 155the file in bytes. 156Otherwise, if the 157.Fl n 158flag is not specified, prints 159the name of the special file as located in 160.Pa /dev . 161If that cannot be located, or the 162.Fl n 163flag is specified, prints the major/minor device 164number that the special device refers to. 165.It Li R/W 166This column describes the access mode that the file allows. 167The letter 168.Sq r 169indicates open for reading; 170the letter 171.Sq w 172indicates open for writing. 173This field is useful when trying to find the processes that are 174preventing a file system from being downgraded to read-only. 175.It Li NAME 176If filename arguments are specified and the 177.Fl f 178flag is not, then 179this field is present and is the name associated with the given file. 180Normally the name cannot be determined since there is no mapping 181from an open file back to the directory entry that was used to open 182that file. 183Also, since different directory entries may reference 184the same file (via 185.Xr ln 1 ) , 186the name printed may not be the actual 187name that the process originally used to open that file. 188.El 189.Sh SOCKETS 190The formatting of open sockets depends on the protocol domain. 191In all cases the first field is the domain name, the second field 192is the socket type (stream, dgram, etc), and the third is the socket 193flags field (in hex). 194The remaining fields are protocol dependent. 195For TCP, it is the address of the tcpcb, and for UDP, the inpcb (socket pcb). 196For Unix domain sockets, it's the address of the socket pcb and the address 197of the connected pcb (if connected). 198Otherwise the protocol number and address of the socket itself are printed. 199The attempt is to make enough information available to 200permit further analysis without duplicating 201.Xr netstat 1 . 202.Pp 203For example, the addresses mentioned above are the addresses which the 204.Ic netstat -A 205command would print for TCP, UDP, and Unix domain. 206Note that since pipes are implemented using sockets, a pipe appears as a 207connected Unix domain stream socket. 208A unidirectional Unix domain socket indicates the direction of flow with 209an arrow 210.Pf ( Dq <- 211or 212.Dq -> ) , 213and a full duplex socket shows a double arrow 214.Pq Dq <-> . 215.Pp 216For 217.Dv AF_INET 218sockets, 219.Nm 220also attempts to print the internet address and port for the 221local end of a connection. 222If the socket is connected, it also prints the remote internet address 223and port. 224A 225.Ql * 226is used to indicate an 227.Dv INADDR_ANY 228binding. 229In this case, the 230use of the arrow 231.Pf ( Dq <-- 232or 233.Dq --> ) 234indicates the direction the socket connection was created. 235.Sh PIPES 236Every pipe is printed as an address which is the same for both sides of 237the pipe and a state that is built of the letters 238.Dq RWE . 239W \- The pipe blocks waiting for the reader to read data. 240R \- The pipe blocks waiting for the writer to write data. 241E \- The pipe is in EOF state. 242.Sh CRYPTO 243Each 244.Xr crypto 4 245device is printed with only the kernel address of the device private data. 246.Sh KQUEUE 247Each 248.Xr kqueue 2 249is printed with some information as to queue length. 250Since these things are normally serviced quickly, it is likely that 251nothing of real importance can be discerned. 252.Sh SYSTRACE 253Each systrace device is printed with only the kernel address of the 254device private data. 255.Sh SEE ALSO 256.Xr netstat 1 , 257.Xr nfsstat 1 , 258.Xr ps 1 , 259.Xr systat 1 , 260.Xr iostat 8 , 261.Xr pstat 8 , 262.Xr tcpdrop 8 , 263.Xr vmstat 8 264.Sh HISTORY 265The 266.Nm 267command appeared in 268.Bx 4.3 tahoe . 269.Sh CAVEATS 270Sockets in use by the kernel, such as those opened by 271.Xr nfsd 8 , 272will not be seen by 273.Nm , 274even though they appear in 275.Xr netstat 1 . 276.Sh BUGS 277Since 278.Nm 279takes a snapshot of the system, it is only correct for a very short period 280of time. 281.Pp 282Moreover, because DNS resolution and YP lookups cause many file 283descriptor changes, 284.Nm 285does not attempt to translate the internet address and port numbers into 286symbolic names. 287