[unix-history] / usr.bin / fstat / fstat.1

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