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