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