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 November 24, 2020 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 f 317fifo 318.It h 319shared memory 320.It k 321kqueue 322.It m 323message queue 324.It P 325process descriptor 326.It p 327pipe 328.It s 329socket 330.It t 331pseudo-terminal master 332.It v 333vnode 334.El 335.Pp 336The following vnode types may be displayed: 337.Pp 338.Bl -tag -width X -compact 339.It - 340not a vnode 341.It b 342block device 343.It c 344character device 345.It d 346directory 347.It f 348fifo 349.It l 350symbolic link 351.It r 352regular file 353.It s 354socket 355.It x 356revoked device 357.El 358.Pp 359The following file descriptor flags may be displayed: 360.Pp 361.Bl -tag -width X -compact 362.It r 363read 364.It w 365write 366.It a 367append 368.It s 369async 370.It f 371fsync 372.It n 373non-blocking 374.It d 375direct I/O 376.It l 377lock held 378.El 379.Pp 380If the 381.Fl C 382flag is specified, the vnode type, reference count, and offset fields will be 383omitted, and a new capabilities field will be included listing capabilities, 384as described in 385.Xr cap_rights_limit 2 , 386present for each capability descriptor. 387.Pp 388The following network protocols may be displayed (grouped by address family): 389.Pp 390.Dv AF_INET , 391.Dv AF_INET6 392.Pp 393.Bl -tag -width indent -compact 394.It ICM 395.Dv IPPROTO_ICMP ; 396see 397.Xr icmp 4 . 398.It IPD 399.Dv IPPROTO_DIVERT ; 400see 401.Xr divert 4 . 402.It IP? 403unknown protocol. 404.It RAW 405.Dv IPPROTO_RAW ; 406see 407.Xr ip 4 . 408.It SCT 409.Dv IPPROTO_SCTP ; 410see 411.Xr sctp 4 . 412.It TCP 413.Dv IPPROTO_TCP ; 414see 415.Xr tcp 4 . 416.It UDP 417.Dv IPPROTO_UDP ; 418see 419.Xr udp 4 . 420.El 421.Pp 422.Dv AF_LOCAL 423.Pp 424.Bl -tag -width indent -compact 425.It UDD 426.Dv IPPROTO_UDP ; 427see 428.Xr udp 4 . 429.It UDS 430.Dv IPPROTO_TCP ; 431see 432.Xr tcp 4 . 433.It UD? 434unknown protocol. 435.El 436.Pp 437.Bl -tag -width indent -compact 438.It ? 439unknown address family. 440.El 441.Ss Signal Disposition Information 442Display signal pending and disposition for a process: 443.Pp 444.Bl -tag -width indent -compact 445.It PID 446process ID 447.It COMM 448command 449.It SIG 450signal name 451.It FLAGS 452process signal disposition details, three symbols 453.Bl -tag -width X -compact 454.It P 455if signal is pending in the global process queue; - otherwise. 456.It I 457if signal delivery disposition is 458.Dv SIG_IGN ; 459- otherwise. 460.It C 461if the signal will be caught; - otherwise. 462.El 463.El 464.Pp 465If 466.Fl n 467switch is given, the signal numbers are shown instead of signal names. 468.Ss Thread Signal Information 469Display signal pending and blocked for a process's threads: 470.Pp 471.Bl -tag -width indent -compact 472.It PID 473process ID 474.It TID 475thread ID 476.It COMM 477command 478.It SIG 479signal name 480.It FLAGS 481thread signal delivery status, two symbols 482.Bl -tag -width X -compact 483.It P 484if signal is pending for the thread, - otherwise 485.It B 486if signal is blocked in the thread signal mask, - if not blocked 487.El 488.El 489.Pp 490The 491.Fl n 492switch has the same effect as for the 493.Fl i 494switch: the signal numbers are shown instead of signal names. 495.Ss Kernel Thread Stacks 496Display kernel thread stacks for a process, allowing further interpretation 497of thread wait channels. 498If the 499.Fl k 500flag is repeated, function offsets, not just function names, are printed. 501.Pp 502This feature requires 503.Cd "options STACK" 504or 505.Cd "options DDB" 506to be compiled into the kernel. 507.Pp 508.Bl -tag -width indent -compact 509.It PID 510process ID 511.It TID 512thread ID 513.It COMM 514command 515.It TDNAME 516thread name 517.It KSTACK 518kernel thread call stack 519.El 520.Ss Resource Limits 521Display resource limits for a process: 522.Pp 523.Bl -tag -width indent -compact 524.It PID 525process ID 526.It COMM 527command 528.It RLIMIT 529resource limit name 530.It SOFT 531soft limit 532.It HARD 533hard limit 534.El 535.Ss Resource Usage 536Display resource usage for a process. 537If the 538.Fl H 539flag is specified, 540resource usage for individual threads is displayed instead. 541.Pp 542.Bl -tag -width "RESOURCE" -compact 543.It PID 544process ID 545.It TID 546thread ID 547.Po 548if 549.Fl H 550is specified 551.Pc 552.It COMM 553command 554.It RESOURCE 555resource name 556.It VALUE 557current usage 558.El 559.Ss Security Credentials 560Display process credential information: 561.Pp 562.Bl -tag -width indent -compact 563.It PID 564process ID 565.It COMM 566command 567.It EUID 568effective user ID 569.It RUID 570real user ID 571.It SVUID 572saved user ID 573.It EGID 574effective group ID 575.It RGID 576real group ID 577.It SVGID 578saved group ID 579.It UMASK 580file creation mode mask 581.It FLAGS 582credential flags 583.It GROUPS 584group set 585.El 586.Pp 587The following credential flags may be displayed: 588.Pp 589.Bl -tag -width X -compact 590.It C 591capability mode 592.El 593.Ss Thread Information 594Display per-thread information, including process ID, per-thread ID, name, 595CPU, and execution state: 596.Pp 597.Bl -tag -width indent -compact 598.It PID 599process ID 600.It TID 601thread ID 602.It COMM 603command 604.It TDNAME 605thread name 606.It CPU 607current or most recent CPU run on 608.It PRI 609thread priority 610.It STATE 611thread state 612.It WCHAN 613thread wait channel 614.El 615.Ss Virtual Memory Mappings 616Display process virtual memory mappings, including addresses, mapping 617meta-data, and mapped object information: 618.Pp 619.Bl -tag -width indent -compact 620.It PID 621process ID 622.It START 623starting address of mapping 624.It END 625ending address of mapping 626.It PRT 627protection flags 628.It RES 629resident pages 630.It PRES 631private resident pages 632.It REF 633reference count 634.It SHD 635shadow page count 636.It FLAG 637mapping flags 638.It TP 639VM object type 640.El 641.Pp 642The following protection flags may be displayed: 643.Pp 644.Bl -tag -width X -compact 645.It r 646read 647.It w 648write 649.It x 650execute 651.El 652.Pp 653The following VM object types may be displayed: 654.Pp 655.Bl -tag -width XX -compact 656.It -- 657none 658.It dd 659dead 660.It df 661default 662.It dv 663device 664.It md 665device with managed pages 666.Pq GEM/TTM 667.It ph 668physical 669.It sg 670scatter/gather 671.It sw 672swap 673.It vn 674vnode 675.El 676.Pp 677The following mapping flags may be displayed: 678.Pp 679.Bl -tag -width X -compact 680.It C 681copy-on-write 682.It N 683needs copy 684.It S 685one or more superpage mappings are used 686.It D 687grows down (top-down stack) 688.It U 689grows up (bottom-up stack) 690.It W 691pages in this range are locked by 692.Xr mlock 2 693or 694.Xr mlockall 2 695.El 696.Ss ELF Auxiliary Vector 697Display ELF auxiliary vector values: 698.Pp 699.Bl -tag -width indent -compact 700.It PID 701process ID 702.It COMM 703command 704.It AUXV 705auxiliary vector name 706.It VALUE 707auxiliary vector value 708.El 709.Sh EXIT STATUS 710.Ex -std 711.Sh EXAMPLES 712Show binary information about the current shell: 713.Bd -literal -offset indent 714$ procstat binary $$ 715 PID COMM OSREL PATH 71646620 bash 1201000 /usr/local/bin/bash 717.Ed 718.Pp 719Same as above but showing information about open file descriptors: 720.Bd -literal -offset indent 721$ procstat files $$ 722 PID COMM FD T V FLAGS REF OFFSET PRO NAME 72346620 bash text v r r------- - - - /usr/local/bin/bash 72446620 bash ctty v c rw------ - - - /dev/pts/12 72546620 bash cwd v d r------- - - - /tmp 72646620 bash root v d r------- - - - / 72746620 bash 0 v c rw------ 7 372071 - /dev/pts/12 72846620 bash 1 v c rw------ 7 372071 - /dev/pts/12 72946620 bash 2 v c rw------ 7 372071 - /dev/pts/12 73046620 bash 255 v c rw------ 7 372071 - /dev/pts/12 731.Ed 732.Pp 733Show the arguments used to launch 734.Xr init 8 : 735.Bd -literal -offset indent 736$ procstat arguments 1 737 PID COMM ARGS 738 1 init /sbin/init -- 739.Ed 740.Pp 741Extract binary information from a core dump: 742.Bd -literal -offset indent 743$ procstat binary core.36642 744 PID COMM OSREL PATH 74536642 top 1201000 /usr/bin/top 746.Ed 747.Pp 748Trying to extract information from a core file generated in a different major 749.Fx 750version might show an error like this: 751.Bd -literal -offset indent 752$ procstat mplayer.core 753procstat: kinfo_proc structure size mismatch 754procstat: procstat_getprocs() 755.Ed 756.Sh SEE ALSO 757.Xr fstat 1 , 758.Xr ps 1 , 759.Xr sockstat 1 , 760.Xr cap_enter 2 , 761.Xr cap_rights_limit 2 , 762.Xr mlock 2 , 763.Xr mlockall 2 , 764.Xr libprocstat 3 , 765.Xr libxo 3 , 766.Xr signal 3 , 767.Xr xo_parse_args 3 , 768.Xr ddb 4 , 769.Xr divert 4 , 770.Xr icmp 4 , 771.Xr ip 4 , 772.Xr sctp 4 , 773.Xr tcp 4 , 774.Xr udp 4 , 775.Xr stack 9 776.Sh AUTHORS 777.An Robert N M Watson Aq Mt rwatson@FreeBSD.org . 778.br 779.Xr libxo 3 780support was added by 781.An -nosplit 782Allan Jude 783.Aq Mt allanjude@FreeBSD.org . 784.br 785.An Juraj Lutter 786.Aq Mt juraj@lutter.sk 787added the pargs, penv and pwdx functionality. 788.Sh BUGS 789The display of open file or memory mapping pathnames is implemented using the 790kernel's name cache. 791If a file system does not use the name cache, or the path to a file is not in 792the cache, a path will not be displayed. 793.Pp 794.Nm 795currently supports extracting data only from a live kernel, and not from 796kernel crash dumps. 797