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