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 11, 2017 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 its 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.Pp 275The following network protocols may be displayed (grouped by address family): 276.Pp 277.Dv AF_INET , 278.Dv AF_INET6 279.Pp 280.Bl -tag -width indent -compact 281.It ICM 282.Dv IPPROTO_ICMP ; 283see 284.Xr icmp 4 . 285.It IPD 286.Dv IPPROTO_DIVERT ; 287see 288.Xr divert 4 . 289.It IP\? 290unknown protocol. 291.It RAW 292.Dv IPPROTO_RAW ; 293see 294.Xr ip 4 . 295.It SCT 296.Dv IPPROTO_SCTP ; 297see 298.Xr sctp 4 . 299.It TCP 300.Dv IPPROTO_TCP ; 301see 302.Xr tcp 4 . 303.It UDP 304.Dv IPPROTO_UDP ; 305see 306.Xr udp 4 . 307.El 308.Pp 309.Dv AF_LOCAL 310.Pp 311.Bl -tag -width indent -compact 312.It UDD 313.Dv IPPROTO_UDP ; 314see 315.Xr udp 4 . 316.It UDS 317.Dv IPPROTO_TCP ; 318see 319.Xr tcp 4 . 320.It UD\? 321unknown protocol. 322.El 323.Pp 324.Bl -tag -width indent -compact 325.It \? 326unknown address family. 327.El 328.Ss Signal Disposition Information 329Display signal pending and disposition for a process: 330.Pp 331.Bl -tag -width indent -compact 332.It PID 333process ID 334.It COMM 335command 336.It SIG 337signal name 338.It FLAGS 339process signal disposition details, three symbols 340.Bl -tag -width X -compact 341.It P 342if signal is pending in the global process queue; - otherwise. 343.It I 344if signal delivery disposition is 345.Dv SIG_IGN; 346- otherwise. 347.It C 348if the signal will be caught; - otherwise. 349.El 350.El 351.Pp 352If 353.Fl n 354switch is given, the signal numbers are shown instead of signal names. 355.Ss Thread Signal Information 356Display signal pending and blocked for a process's threads: 357.Pp 358.Bl -tag -width indent -compact 359.It PID 360process ID 361.It TID 362thread ID 363.It COMM 364command 365.It SIG 366signal name 367.It FLAGS 368thread signal delivery status, two symbols 369.Bl -tag -width X -compact 370.It P 371if signal is pending for the thread, - otherwise 372.It B 373if signal is blocked in the thread signal mask, - if not blocked 374.El 375.El 376.Pp 377The 378.Fl n 379switch has the same effect as for the 380.Fl i 381switch: the signal numbers are shown instead of signal names. 382.Ss Kernel Thread Stacks 383Display kernel thread stacks for a process, allowing further interpretation 384of thread wait channels. 385If the 386.Fl k 387flag is repeated, function offsets, not just function names, are printed. 388.Pp 389This feature requires 390.Cd "options STACK" 391or 392.Cd "options DDB" 393to be compiled into the kernel. 394.Pp 395.Bl -tag -width indent -compact 396.It PID 397process ID 398.It TID 399thread ID 400.It COMM 401command 402.It TDNAME 403thread name 404.It KSTACK 405kernel thread call stack 406.El 407.Ss Resource Limits 408Display resource limits for a process: 409.Pp 410.Bl -tag -width indent -compact 411.It PID 412process ID 413.It COMM 414command 415.It RLIMIT 416resource limit name 417.It SOFT 418soft limit 419.It HARD 420hard limit 421.El 422.Ss Resource Usage 423Display resource usage for a process. 424If the 425.Fl H 426flag is specified, 427resource usage for individual threads is displayed instead. 428.Pp 429.Bl -tag -width "RESOURCE" -compact 430.It PID 431process ID 432.It TID 433thread ID 434.Po 435if 436.Fl H 437is specified 438.Pc 439.It COMM 440command 441.It RESOURCE 442resource name 443.It VALUE 444current usage 445.El 446.Ss Security Credentials 447Display process credential information: 448.Pp 449.Bl -tag -width indent -compact 450.It PID 451process ID 452.It COMM 453command 454.It EUID 455effective user ID 456.It RUID 457real user ID 458.It SVUID 459saved user ID 460.It EGID 461effective group ID 462.It RGID 463real group ID 464.It SVGID 465saved group ID 466.It UMASK 467file creation mode mask 468.It FLAGS 469credential flags 470.It GROUPS 471group set 472.El 473.Pp 474The following credential flags may be displayed: 475.Pp 476.Bl -tag -width X -compact 477.It C 478capability mode 479.El 480.Ss Thread Information 481Display per-thread information, including process ID, per-thread ID, name, 482CPU, and execution state: 483.Pp 484.Bl -tag -width indent -compact 485.It PID 486process ID 487.It TID 488thread ID 489.It COMM 490command 491.It TDNAME 492thread name 493.It CPU 494current or most recent CPU run on 495.It PRI 496thread priority 497.It STATE 498thread state 499.It WCHAN 500thread wait channel 501.El 502.Ss Virtual Memory Mappings 503Display process virtual memory mappings, including addresses, mapping 504meta-data, and mapped object information: 505.Pp 506.Bl -tag -width indent -compact 507.It PID 508process ID 509.It START 510starting address of mapping 511.It END 512ending address of mapping 513.It PRT 514protection flags 515.It RES 516resident pages 517.It PRES 518private resident pages 519.It REF 520reference count 521.It SHD 522shadow page count 523.It FLAG 524mapping flags 525.It TP 526VM object type 527.El 528.Pp 529The following protection flags may be displayed: 530.Pp 531.Bl -tag -width X -compact 532.It r 533read 534.It w 535write 536.It x 537execute 538.El 539.Pp 540The following VM object types may be displayed: 541.Pp 542.Bl -tag -width XX -compact 543.It -- 544none 545.It dd 546dead 547.It df 548default 549.It dv 550device 551.It md 552device with managed pages 553.Pq GEM/TTM 554.It ph 555physical 556.It sg 557scatter/gather 558.It sw 559swap 560.It vn 561vnode 562.El 563.Pp 564The following mapping flags may be displayed: 565.Pp 566.Bl -tag -width X -compact 567.It C 568copy-on-write 569.It N 570needs copy 571.It S 572one or more superpage mappings are used 573.It D 574grows down (top-down stack) 575.It U 576grows up (bottom-up stack) 577.El 578.Ss ELF Auxiliary Vector 579Display ELF auxiliary vector values: 580.Pp 581.Bl -tag -width indent -compact 582.It PID 583process ID 584.It COMM 585command 586.It AUXV 587auxiliary vector name 588.It VALUE 589auxiliary vector value 590.El 591.Sh EXIT STATUS 592.Ex -std 593.Sh SEE ALSO 594.Xr fstat 1 , 595.Xr ps 1 , 596.Xr sockstat 1 , 597.Xr cap_enter 2 , 598.Xr cap_rights_limit 2 , 599.Xr libprocstat 3 , 600.Xr libxo 3 , 601.Xr signal 3 , 602.Xr xo_parse_args 3 , 603.Xr ddb 4 , 604.Xr divert 4 , 605.Xr icmp 4 , 606.Xr ip 4 , 607.Xr sctp 4 , 608.Xr tcp 4 , 609.Xr udp 4 , 610.Xr stack 9 611.Sh AUTHORS 612.An Robert N M Watson Aq Mt rwatson@FreeBSD.org . 613.br 614.Xr libxo 3 615support was added by 616.An -nosplit 617Allan Jude 618.Aq Mt allanjude@FreeBSD.org . 619.Sh BUGS 620The display of open file or memory mapping pathnames is implemented using the 621kernel's name cache. 622If a file system does not use the name cache, or the path to a file is not in 623the cache, a path will not be displayed. 624.Pp 625.Nm 626currently supports extracting data only from a live kernel, and not from 627kernel crash dumps. 628