1.\"- 2.\" Copyright (c) 2007-2008 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 20, 2008 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 w Ar interval 38.Op Fl b | c | f | k | s | t | v 39.Op Fl a | Ar pid ... 40.Sh DESCRIPTION 41The 42.Nm 43utility displays detailed information about the processes identified by the 44.Ar pid 45arguments, or if the 46.Fl a 47flag is used, all processes. 48.Pp 49By default, basic process statistics are printed; one of the following 50options may be specified in order to select more detailed process information 51for printing: 52.Bl -tag -width indent 53.It Fl b 54Display binary information for the process. 55.It Fl c 56Display command line arguments for the process. 57.It Fl f 58Display file descriptor information for the process. 59.It Fl k 60Display the stacks of kernel threads in the process, excluding stacks of 61threads currently running on a CPU and threads with stacks swapped to disk. 62If the flag is repeated, function offsets as well as function names are 63printed. 64.It Fl s 65Display security credential information for the process. 66.It Fl t 67Display thread information for the process. 68.It Fl v 69Display virtual memory mappings for the process. 70.El 71.Pp 72All options generate output in the format of a table, the first field of 73which is the process ID to which the row of information corresponds. 74The 75.Fl h 76flag may be used to suppress table headers. 77.Pp 78The 79.Fl w 80flag may be used to specify a wait interval at which to repeat the printing 81of the requested process information. 82If the 83.Fl w 84flag is not specified, the output will not repeat. 85.Pp 86Some information, such as VM and file descriptor information, is available 87only to the owner of a process or the superuser. 88.Ss Binary Information 89Display the process ID, command, and path to the process binary: 90.Pp 91.Bl -tag -width indent -compact 92.It PID 93process ID 94.It COMM 95command 96.It PATH 97path to process binary (if available) 98.El 99.Ss Command Line Arguments 100Display the process ID, command, and command line arguments: 101.Pp 102.Bl -tag -width indent -compact 103.It PID 104process ID 105.It COMM 106command 107.It ARGS 108command line arguments (if available) 109.El 110.Ss File Descriptors 111Display detailed information about each file descriptor referenced by a 112process, including the process ID, command, file descriptor number, and 113per-file descriptor object information, such as object type and file system 114path: 115.Pp 116.Bl -tag -width indent -compact 117.It PID 118process ID 119.It COMM 120command 121.It FD 122file descriptor number or cwd/root/jail 123.It T 124file descriptor type 125.It V 126vnode type 127.It FLAGS 128file descriptor flags 129.It REF 130file descriptor reference count 131.It OFFSET 132file descriptor offset 133.It PRO 134network protocol 135.It NAME 136file path or socket addresses (if available) 137.El 138.Pp 139The following file descriptor types may be displayed: 140.Pp 141.Bl -tag -width X -compact 142.It c 143crypto 144.It e 145POSIX semaphore 146.It f 147fifo 148.It h 149shared memory 150.It k 151kqueue 152.It m 153message queue 154.It p 155pipe 156.It s 157socket 158.It t 159pseudo-terminal master 160.It v 161vnode 162.El 163.Pp 164The following vnode types may be displayed: 165.Pp 166.Bl -tag -width X -compact 167.It - 168not a vnode 169.It b 170block device 171.It c 172character device 173.It d 174directory 175.It f 176fifo 177.It l 178symbolic link 179.It r 180regular file 181.It s 182socket 183.It x 184revoked device 185.El 186.Pp 187The following file descriptor flags may be displayed: 188.Pp 189.Bl -tag -width X -compact 190.It r 191read 192.It w 193write 194.It a 195append 196.It s 197async 198.It f 199fsync 200.It n 201non-blocking 202.It d 203direct I/O 204.It l 205lock held 206.El 207.Ss Kernel Thread Stacks 208Display kernel thread stacks for a process, allowing further interpretation 209of thread wait channels. 210If the 211.Fl k 212flag is repeated, function offsets, not just function names, are printed. 213.Pp 214This feature requires 215.Cd "options STACK" 216or 217.Cd "options DDB" 218to be compiled into the kernel. 219.Pp 220.Bl -tag -width indent -compact 221.It PID 222process ID 223.It TID 224thread ID 225.It COMM 226command 227.It TDNAME 228thread name 229.It KSTACK 230kernel thread call stack 231.El 232.Ss Security Credentials 233Display process credential information: 234.Pp 235.Bl -tag -width indent -compact 236.It PID 237process ID 238.It COMM 239command 240.It EUID 241effective user ID 242.It RUID 243real user ID 244.It SVUID 245saved user ID 246.It EGID 247effective group ID 248.It RGID 249real group ID 250.It SVGID 251saved group ID 252.It GROUPS 253group set 254.El 255.Ss Thread Information 256Display per-thread information, including process ID, per-thread ID, name, 257CPU, and execution state: 258.Pp 259.Bl -tag -width indent -compact 260.It PID 261process ID 262.It TID 263thread ID 264.It COMM 265command 266.It TDNAME 267thread name 268.It CPU 269current or most recent CPU run on 270.It PRI 271thread priority 272.It STATE 273thread state 274.It WCHAN 275thread wait channel 276.El 277.Ss Virtual Memory Mappings 278Display process virtual memory mappings, including addresses, mapping 279meta-data, and mapped object information: 280.Pp 281.Bl -tag -width indent -compact 282.It PID 283process ID 284.It START 285starting address of mapping 286.It END 287ending address of mapping 288.It PRT 289protection flags 290.It RES 291resident pages 292.It PRES 293private resident pages 294.It REF 295reference count 296.It SHD 297shadow page count 298.It FL 299mapping flags 300.It TP 301VM object type 302.El 303.Pp 304The following protection flags may be displayed: 305.Pp 306.Bl -tag -width X -compact 307.It r 308read 309.It w 310write 311.It x 312execute 313.El 314.Pp 315The following VM object types may be displayed: 316.Pp 317.Bl -tag -width XX -compact 318.It -- 319none 320.It dd 321dead 322.It df 323default 324.It dv 325device 326.It ph 327physical 328.It sw 329swap 330.It vn 331vnode 332.El 333.Pp 334The following mapping flags may be displayed: 335.Pp 336.Bl -tag -width X -compact 337.It C 338copy-on-write 339.It N 340needs copy 341.El 342.Sh EXIT STATUS 343.Ex -std 344.Sh SEE ALSO 345.Xr fstat 1 , 346.Xr ps 1 , 347.Xr sockstat 1 , 348.Xr ddb 4 , 349.Xr stack 9 350.Sh AUTHORS 351.An Robert N M Watson 352.Sh BUGS 353Some field values may include spaces, which limits the extent to which the 354output of 355.Nm 356may be mechanically parsed. 357.Pp 358The display of open file or memory mapping pathnames is implemented using the 359kernel's name cache. 360If a file system does not use the name cache, or the path to a file is not in 361the cache, a path will not be displayed. 362.Pp 363.Nm 364currently supports extracting data only from a live kernel, and not from 365kernel crash dumps. 366