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