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 May 18, 2015 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 CHhn 37.Op Fl w Ar interval 38.Op Fl b | c | e | f | i | j | k | l | r | s | S | t | v | x 39.Op Fl a | Ar pid | Ar core ... 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. 48It can also display information extracted from a process core file, if 49the core file is specified as the argument. 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 e 60Display environment variables for the process. 61.It Fl f 62Display file descriptor information for the process. 63.It Fl i 64Display signal pending and disposition information for the process. 65.It Fl j 66Display signal pending and blocked information for the process's threads. 67.It Fl k 68Display the stacks of kernel threads in the process, excluding stacks of 69threads currently running on a CPU and threads with stacks swapped to disk. 70If the flag is repeated, function offsets as well as function names are 71printed. 72.It Fl l 73Display resource limits for the process. 74.It Fl r 75Display resource usage information for the process. 76.It Fl s 77Display security credential information for the process. 78.It Fl S 79Display the cpuset information for the thread. 80.It Fl t 81Display thread information for the process. 82.It Fl v 83Display virtual memory mappings for the process. 84.It Fl x 85Display ELF auxiliary vector for the process. 86.El 87.Pp 88All options generate output in the format of a table, the first field of 89which is the process ID to which the row of information corresponds. 90The 91.Fl h 92flag may be used to suppress table headers. 93.Pp 94The 95.Fl w 96flag may be used to specify a wait interval at which to repeat the printing 97of the requested process information. 98If the 99.Fl w 100flag is not specified, the output will not repeat. 101.Pp 102The 103.Fl C 104flag requests the printing of additional capability information in the file 105descriptor view. 106.Pp 107The 108.Fl H 109flag may be used to request per-thread statistics rather than per-process 110statistics for some options. 111For those options, the second field in the table will list the thread ID 112to which the row of information corresponds. 113The 114.Fl H 115flag is implied for the 116.Fl S 117mode. 118.Pp 119Information for VM, file descriptor, and cpuset options is available 120only to the owner of a process or the superuser. 121A cpuset value displayed as -1 means that the information is either invalid 122or not available. 123.Ss Binary Information 124Display the process ID, command, and path to the process binary: 125.Pp 126.Bl -tag -width indent -compact 127.It PID 128process ID 129.It COMM 130command 131.It OSREL 132osreldate for process binary 133.It PATH 134path to process binary (if available) 135.El 136.Ss Command Line Arguments 137Display the process ID, command, and command line arguments: 138.Pp 139.Bl -tag -width indent -compact 140.It PID 141process ID 142.It COMM 143command 144.It ARGS 145command line arguments (if available) 146.El 147.Ss Environment Variables 148Display the process ID, command, and environment variables: 149.Pp 150.Bl -tag -width "ENVIRONMENT" -compact 151.It PID 152process ID 153.It COMM 154command 155.It ENVIRONMENT 156environment variables (if available) 157.El 158.Ss File Descriptors 159Display detailed information about each file descriptor referenced by a 160process, including the process ID, command, file descriptor number, and 161per-file descriptor object information, such as object type and file system 162path. 163By default, the following information will be printed: 164.Pp 165.Bl -tag -width indent -compact 166.It PID 167process ID 168.It COMM 169command 170.It FD 171file descriptor number or cwd/root/jail 172.It T 173file descriptor type 174.It V 175vnode type 176.It FLAGS 177file descriptor flags 178.It REF 179file descriptor reference count 180.It OFFSET 181file descriptor offset 182.It PRO 183network protocol 184.It NAME 185file path or socket addresses (if available) 186.El 187.Pp 188The following file descriptor types may be displayed: 189.Pp 190.Bl -tag -width X -compact 191.It c 192crypto 193.It e 194POSIX semaphore 195.It f 196fifo 197.It h 198shared memory 199.It k 200kqueue 201.It m 202message queue 203.It p 204pipe 205.It s 206socket 207.It t 208pseudo-terminal master 209.It v 210vnode 211.El 212.Pp 213The following vnode types may be displayed: 214.Pp 215.Bl -tag -width X -compact 216.It - 217not a vnode 218.It b 219block device 220.It c 221character device 222.It d 223directory 224.It f 225fifo 226.It l 227symbolic link 228.It r 229regular file 230.It s 231socket 232.It x 233revoked device 234.El 235.Pp 236The following file descriptor flags may be displayed: 237.Pp 238.Bl -tag -width X -compact 239.It r 240read 241.It w 242write 243.It a 244append 245.It s 246async 247.It f 248fsync 249.It n 250non-blocking 251.It d 252direct I/O 253.It l 254lock held 255.El 256.Pp 257If the 258.Fl C 259flag is specified, the vnode type, reference count, and offset fields will be 260omitted, and a new capabilities field will be included listing capabilities, 261as described in 262.Xr cap_rights_limit 2 , 263present for each capability descriptor. 264.Ss Signal Disposition Information 265Display signal pending and disposition for a process: 266.Pp 267.Bl -tag -width indent -compact 268.It PID 269process ID 270.It COMM 271command 272.It SIG 273signal name 274.It FLAGS 275process signal disposition details, three symbols 276.Bl -tag -width X -compact 277.It P 278if signal is pending in the global process queue, - otherwise 279.It I 280if signal delivery disposition is SIGIGN, - otherwise 281.It C 282if signal delivery is to catch it, - otherwise 283.El 284.El 285.Pp 286If 287.Fl n 288switch is given, the signal numbers are shown instead of signal names. 289.Ss Thread Signal Information 290Display signal pending and blocked for a process's threads: 291.Pp 292.Bl -tag -width indent -compact 293.It PID 294process ID 295.It TID 296thread ID 297.It COMM 298command 299.It SIG 300signal name 301.It FLAGS 302thread signal delivery status, two symbols 303.Bl -tag -width X -compact 304.It P 305if signal is pending for the thread, - otherwise 306.It B 307if signal is blocked in the thread signal mask, - if not blocked 308.El 309.El 310.Pp 311The 312.Fl n 313switch has the same effect as for the 314.Fl i 315switch: the signal numbers are shown instead of signal names. 316.Ss Kernel Thread Stacks 317Display kernel thread stacks for a process, allowing further interpretation 318of thread wait channels. 319If the 320.Fl k 321flag is repeated, function offsets, not just function names, are printed. 322.Pp 323This feature requires 324.Cd "options STACK" 325or 326.Cd "options DDB" 327to be compiled into the kernel. 328.Pp 329.Bl -tag -width indent -compact 330.It PID 331process ID 332.It TID 333thread ID 334.It COMM 335command 336.It TDNAME 337thread name 338.It KSTACK 339kernel thread call stack 340.El 341.Ss Resource Limits 342Display resource limits for a process: 343.Pp 344.Bl -tag -width indent -compact 345.It PID 346process ID 347.It COMM 348command 349.It RLIMIT 350resource limit name 351.It SOFT 352soft limit 353.It HARD 354hard limit 355.El 356.Ss Resource Usage 357Display resource usage for a process. 358If the 359.Fl H 360flag is specified, 361resource usage for individual threads is displayed instead. 362.Pp 363.Bl -tag -width "RESOURCE" -compact 364.It PID 365process ID 366.It TID 367thread ID 368.Po 369if 370.Fl H 371is specified 372.Pc 373.It COMM 374command 375.It RESOURCE 376resource name 377.It VALUE 378current usage 379.El 380.Ss Security Credentials 381Display process credential information: 382.Pp 383.Bl -tag -width indent -compact 384.It PID 385process ID 386.It COMM 387command 388.It EUID 389effective user ID 390.It RUID 391real user ID 392.It SVUID 393saved user ID 394.It EGID 395effective group ID 396.It RGID 397real group ID 398.It SVGID 399saved group ID 400.It UMASK 401file creation mode mask 402.It FLAGS 403credential flags 404.It GROUPS 405group set 406.El 407.Pp 408The following credential flags may be displayed: 409.Pp 410.Bl -tag -width X -compact 411.It C 412capability mode 413.El 414.Ss Thread Information 415Display per-thread information, including process ID, per-thread ID, name, 416CPU, and execution state: 417.Pp 418.Bl -tag -width indent -compact 419.It PID 420process ID 421.It TID 422thread ID 423.It COMM 424command 425.It TDNAME 426thread name 427.It CPU 428current or most recent CPU run on 429.It PRI 430thread priority 431.It STATE 432thread state 433.It WCHAN 434thread wait channel 435.El 436.Ss Virtual Memory Mappings 437Display process virtual memory mappings, including addresses, mapping 438meta-data, and mapped object information: 439.Pp 440.Bl -tag -width indent -compact 441.It PID 442process ID 443.It START 444starting address of mapping 445.It END 446ending address of mapping 447.It PRT 448protection flags 449.It RES 450resident pages 451.It PRES 452private resident pages 453.It REF 454reference count 455.It SHD 456shadow page count 457.It FLAG 458mapping flags 459.It TP 460VM object type 461.El 462.Pp 463The following protection flags may be displayed: 464.Pp 465.Bl -tag -width X -compact 466.It r 467read 468.It w 469write 470.It x 471execute 472.El 473.Pp 474The following VM object types may be displayed: 475.Pp 476.Bl -tag -width XX -compact 477.It -- 478none 479.It dd 480dead 481.It df 482default 483.It dv 484device 485.It md 486device with managed pages 487.Pq GEM/TTM 488.It ph 489physical 490.It sg 491scatter/gather 492.It sw 493swap 494.It vn 495vnode 496.El 497.Pp 498The following mapping flags may be displayed: 499.Pp 500.Bl -tag -width X -compact 501.It C 502copy-on-write 503.It N 504needs copy 505.It S 506one or more superpage mappings are used 507.It D 508grows down (top-down stack) 509.It U 510grows up (bottom-up stack) 511.El 512.Ss ELF Auxiliary Vector 513Display ELF auxiliary vector values: 514.Pp 515.Bl -tag -width indent -compact 516.It PID 517process ID 518.It COMM 519command 520.It AUXV 521auxiliary vector name 522.It VALUE 523auxiliary vector value 524.El 525.Sh EXIT STATUS 526.Ex -std 527.Sh SEE ALSO 528.Xr fstat 1 , 529.Xr ps 1 , 530.Xr sockstat 1 , 531.Xr cap_enter 2 , 532.Xr cap_rights_limit 2 , 533.Xr libprocstat 3 , 534.Xr ddb 4 , 535.Xr stack 9 536.Sh AUTHORS 537.An Robert N M Watson 538.Sh BUGS 539Some field values may include spaces, which limits the extent to which the 540output of 541.Nm 542may be mechanically parsed. 543.Pp 544The display of open file or memory mapping pathnames is implemented using the 545kernel's name cache. 546If a file system does not use the name cache, or the path to a file is not in 547the cache, a path will not be displayed. 548.Pp 549.Nm 550currently supports extracting data only from a live kernel, and not from 551kernel crash dumps. 552