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