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