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