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