xref: /freebsd/usr.bin/procstat/procstat.1 (revision 6472ac3d8a86336899b6cfb789a4cd9897e3fab5)
1.\"-
2.\" Copyright (c) 2007-2009 Robert N. M. Watson
3.\" 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.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd August 14, 2011
29.Dt PROCSTAT 1
30.Os
31.Sh NAME
32.Nm procstat
33.Nd get detailed process information
34.Sh SYNOPSIS
35.Nm
36.Op Fl h
37.Op Fl n
38.Op Fl C
39.Op Fl w Ar interval
40.Op Fl b | c | f | i | j | k | s | t | v
41.Op Fl a | Ar pid ...
42.Sh DESCRIPTION
43The
44.Nm
45utility displays detailed information about the processes identified by the
46.Ar pid
47arguments, or if the
48.Fl a
49flag is used, all processes.
50.Pp
51By default, basic process statistics are printed; one of the following
52options may be specified in order to select more detailed process information
53for printing:
54.Bl -tag -width indent
55.It Fl b
56Display binary information for the process.
57.It Fl c
58Display command line arguments for the process.
59.It Fl f
60Display file descriptor information for the process.
61.It Fl i
62Display signal pending and disposition information for the process.
63.It Fl j
64Display signal pending and blocked information for the process threads.
65.It Fl k
66Display the stacks of kernel threads in the process, excluding stacks of
67threads currently running on a CPU and threads with stacks swapped to disk.
68If the flag is repeated, function offsets as well as function names are
69printed.
70.It Fl s
71Display security credential information for the process.
72.It Fl t
73Display thread information for the process.
74.It Fl v
75Display virtual memory mappings for the process.
76.El
77.Pp
78All options generate output in the format of a table, the first field of
79which is the process ID to which the row of information corresponds.
80The
81.Fl h
82flag may be used to suppress table headers.
83.Pp
84The
85.Fl w
86flag may be used to specify a wait interval at which to repeat the printing
87of the requested process information.
88If the
89.Fl w
90flag is not specified, the output will not repeat.
91.Pp
92The
93.Fl C
94flag requests the printing of additional capability information in the file
95descriptor view.
96.Pp
97Some information, such as VM and file descriptor information, is available
98only to the owner of a process or the superuser.
99.Ss Binary Information
100Display the process ID, command, and path to the process binary:
101.Pp
102.Bl -tag -width indent -compact
103.It PID
104process ID
105.It COMM
106command
107.It PATH
108path to process binary (if available)
109.El
110.Ss Command Line Arguments
111Display the process ID, command, and command line arguments:
112.Pp
113.Bl -tag -width indent -compact
114.It PID
115process ID
116.It COMM
117command
118.It ARGS
119command line arguments (if available)
120.El
121.Ss File Descriptors
122Display detailed information about each file descriptor referenced by a
123process, including the process ID, command, file descriptor number, and
124per-file descriptor object information, such as object type and file system
125path.
126By default, the following information will be printed:
127.Pp
128.Bl -tag -width indent -compact
129.It PID
130process ID
131.It COMM
132command
133.It FD
134file descriptor number or cwd/root/jail
135.It T
136file descriptor type
137.It V
138vnode type
139.It FLAGS
140file descriptor flags
141.It REF
142file descriptor reference count
143.It OFFSET
144file descriptor offset
145.It PRO
146network protocol
147.It NAME
148file path or socket addresses (if available)
149.El
150.Pp
151The following file descriptor types may be displayed:
152.Pp
153.Bl -tag -width X -compact
154.It c
155crypto
156.It e
157POSIX semaphore
158.It f
159fifo
160.It h
161shared memory
162.It k
163kqueue
164.It m
165message queue
166.It p
167pipe
168.It s
169socket
170.It t
171pseudo-terminal master
172.It v
173vnode
174.El
175.Pp
176The following vnode types may be displayed:
177.Pp
178.Bl -tag -width X -compact
179.It -
180not a vnode
181.It b
182block device
183.It c
184character device
185.It d
186directory
187.It f
188fifo
189.It l
190symbolic link
191.It r
192regular file
193.It s
194socket
195.It x
196revoked device
197.El
198.Pp
199The following file descriptor flags may be displayed:
200.Pp
201.Bl -tag -width X -compact
202.It r
203read
204.It w
205write
206.It a
207append
208.It s
209async
210.It f
211fsync
212.It n
213non-blocking
214.It d
215direct I/O
216.It l
217lock held
218.It c
219descriptor is a capability
220.El
221.Pp
222If the
223.Fl C
224flag is specified, the vnode type, reference count, and offset fields will be
225omitted, and a new capabilities field will be included listing capabilities,
226as described in
227.Xr cap_new 2 ,
228present for each capability descriptor.
229.Ss Signal Disposition Information
230Display signal pending and disposition for a process:
231.Pp
232.Bl -tag -width ident -compact
233.It PID
234process ID
235.It COMM
236command
237.It SIG
238signal name
239.It FLAGS
240process signal disposition details, three symbols
241.Bl -tag -width X -compact
242.It P
243if signal is pending in the global process queue, - otherwise
244.It I
245if signal delivery disposition is SIGIGN, - otherwise
246.It C
247if signal delivery is to catch it, - otherwise
248.El
249.El
250.Pp
251If
252.Fl n
253switch is given, the signal numbers are shown instead of signal names.
254.Ss Thread Signal Information
255Display signal pending and blocked for a process threads:
256.Pp
257.Bl -tag -width ident -compact
258.It PID
259process ID
260.It COMM
261command
262.It TID
263thread ID
264.It SIG
265signal name
266.It FLAGS
267thread signal delivery status, two symbols
268.Bl -tag -width X -compact
269.It P
270if signal is pending for the thread, - otherwise
271.It B
272if signal is blocked in the thread signal mask, - if not blocked
273.El
274.El
275.Pp
276The
277.Fl n
278switch has the same effect as for the
279.Fl i
280switch, the signals numbers are shown instead of signal names.
281.Ss Kernel Thread Stacks
282Display kernel thread stacks for a process, allowing further interpretation
283of thread wait channels.
284If the
285.Fl k
286flag is repeated, function offsets, not just function names, are printed.
287.Pp
288This feature requires
289.Cd "options STACK"
290or
291.Cd "options DDB"
292to be compiled into the kernel.
293.Pp
294.Bl -tag -width indent -compact
295.It PID
296process ID
297.It TID
298thread ID
299.It COMM
300command
301.It TDNAME
302thread name
303.It KSTACK
304kernel thread call stack
305.El
306.Ss Security Credentials
307Display process credential information:
308.Pp
309.Bl -tag -width indent -compact
310.It PID
311process ID
312.It COMM
313command
314.It EUID
315effective user ID
316.It RUID
317real user ID
318.It SVUID
319saved user ID
320.It EGID
321effective group ID
322.It RGID
323real group ID
324.It SVGID
325saved group ID
326.It FLAGS
327credential flags
328.It GROUPS
329group set
330.El
331.Pp
332The following credential flags may be displayed:
333.Pp
334.Bl -tag -width X -compact
335.It C
336capability mode
337.El
338.Ss Thread Information
339Display per-thread information, including process ID, per-thread ID, name,
340CPU, and execution state:
341.Pp
342.Bl -tag -width indent -compact
343.It PID
344process ID
345.It TID
346thread ID
347.It COMM
348command
349.It TDNAME
350thread name
351.It CPU
352current or most recent CPU run on
353.It PRI
354thread priority
355.It STATE
356thread state
357.It WCHAN
358thread wait channel
359.El
360.Ss Virtual Memory Mappings
361Display process virtual memory mappings, including addresses, mapping
362meta-data, and mapped object information:
363.Pp
364.Bl -tag -width indent -compact
365.It PID
366process ID
367.It START
368starting address of mapping
369.It END
370ending address of mapping
371.It PRT
372protection flags
373.It RES
374resident pages
375.It PRES
376private resident pages
377.It REF
378reference count
379.It SHD
380shadow page count
381.It FL
382mapping flags
383.It TP
384VM object type
385.El
386.Pp
387The following protection flags may be displayed:
388.Pp
389.Bl -tag -width X -compact
390.It r
391read
392.It w
393write
394.It x
395execute
396.El
397.Pp
398The following VM object types may be displayed:
399.Pp
400.Bl -tag -width XX -compact
401.It --
402none
403.It dd
404dead
405.It df
406default
407.It dv
408device
409.It ph
410physical
411.It sw
412swap
413.It vn
414vnode
415.El
416.Pp
417The following mapping flags may be displayed:
418.Pp
419.Bl -tag -width X -compact
420.It C
421copy-on-write
422.It N
423needs copy
424.El
425.Sh EXIT STATUS
426.Ex -std
427.Sh SEE ALSO
428.Xr fstat 1 ,
429.Xr ps 1 ,
430.Xr sockstat 1 ,
431.Xr cap_enter 2 ,
432.Xr cap_new 2 ,
433.Xr ddb 4 ,
434.Xr stack 9
435.Sh AUTHORS
436.An Robert N M Watson
437.Sh BUGS
438Some field values may include spaces, which limits the extent to which the
439output of
440.Nm
441may be mechanically parsed.
442.Pp
443The display of open file or memory mapping pathnames is implemented using the
444kernel's name cache.
445If a file system does not use the name cache, or the path to a file is not in
446the cache, a path will not be displayed.
447.Pp
448.Nm
449currently supports extracting data only from a live kernel, and not from
450kernel crash dumps.
451