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