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 IPD 418.Dv IPPROTO_DIVERT ; 419see 420.Xr divert 4 . 421.It IP? 422unknown protocol. 423.It RAW 424.Dv IPPROTO_RAW ; 425see 426.Xr ip 4 . 427.It SCT 428.Dv IPPROTO_SCTP ; 429see 430.Xr sctp 4 . 431.It TCP 432.Dv IPPROTO_TCP ; 433see 434.Xr tcp 4 . 435.It UDP 436.Dv IPPROTO_UDP ; 437see 438.Xr udp 4 . 439.El 440.Pp 441.Dv AF_LOCAL 442.Pp 443.Bl -tag -width indent -compact 444.It UDD 445.Dv IPPROTO_UDP ; 446see 447.Xr udp 4 . 448.It UDS 449.Dv IPPROTO_TCP ; 450see 451.Xr tcp 4 . 452.It UD? 453unknown protocol. 454.El 455.Pp 456.Bl -tag -width indent -compact 457.It ? 458unknown address family. 459.El 460.Ss Signal Disposition Information 461Display signal pending and disposition for a process: 462.Pp 463.Bl -tag -width indent -compact 464.It PID 465process ID 466.It COMM 467command 468.It SIG 469signal name 470.It FLAGS 471process signal disposition details, three symbols 472.Bl -tag -width X -compact 473.It P 474if signal is pending in the global process queue; - otherwise. 475.It I 476if signal delivery disposition is 477.Dv SIG_IGN ; 478- otherwise. 479.It C 480if the signal will be caught; - otherwise. 481.El 482.El 483.Pp 484If 485.Fl n 486switch is given, the signal numbers are shown instead of signal names. 487.Ss Thread Signal Information 488Display signal pending and blocked for a process's threads: 489.Pp 490.Bl -tag -width indent -compact 491.It PID 492process ID 493.It TID 494thread ID 495.It COMM 496command 497.It SIG 498signal name 499.It FLAGS 500thread signal delivery status, two symbols 501.Bl -tag -width X -compact 502.It P 503if signal is pending for the thread, - otherwise 504.It B 505if signal is blocked in the thread signal mask, - if not blocked 506.El 507.El 508.Pp 509The 510.Fl n 511switch has the same effect as for the 512.Fl i 513switch: the signal numbers are shown instead of signal names. 514.Ss Kernel Thread Stacks 515Display kernel thread stacks for a process, allowing further interpretation 516of thread wait channels. 517If the 518.Fl k 519flag is repeated, function offsets, not just function names, are printed. 520.Pp 521This feature requires 522.Cd "options STACK" 523or 524.Cd "options DDB" 525to be compiled into the kernel. 526.Pp 527.Bl -tag -width indent -compact 528.It PID 529process ID 530.It TID 531thread ID 532.It COMM 533command 534.It TDNAME 535thread name 536.It KSTACK 537kernel thread call stack 538.El 539.Ss Resource Limits 540Display resource limits for a process: 541.Pp 542.Bl -tag -width indent -compact 543.It PID 544process ID 545.It COMM 546command 547.It RLIMIT 548resource limit name 549.It SOFT 550soft limit 551.It HARD 552hard limit 553.El 554.Ss Resource Usage 555Display resource usage for a process. 556If the 557.Fl H 558flag is specified, 559resource usage for individual threads is displayed instead. 560.Pp 561.Bl -tag -width "RESOURCE" -compact 562.It PID 563process ID 564.It TID 565thread ID 566.Po 567if 568.Fl H 569is specified 570.Pc 571.It COMM 572command 573.It RESOURCE 574resource name 575.It VALUE 576current usage 577.El 578.Ss Security Credentials 579Display process credential information: 580.Pp 581.Bl -tag -width indent -compact 582.It PID 583process ID 584.It COMM 585command 586.It EUID 587effective user ID 588.It RUID 589real user ID 590.It SVUID 591saved user ID 592.It EGID 593effective group ID 594.It RGID 595real group ID 596.It SVGID 597saved group ID 598.It UMASK 599file creation mode mask 600.It FLAGS 601credential flags 602.It GROUPS 603group set 604.El 605.Pp 606The following credential flags may be displayed: 607.Pp 608.Bl -tag -width X -compact 609.It C 610capability mode 611.El 612.Ss Thread Information 613Display per-thread information, including process ID, per-thread ID, name, 614CPU, and execution state: 615.Pp 616.Bl -tag -width indent -compact 617.It PID 618process ID 619.It TID 620thread ID 621.It COMM 622command 623.It TDNAME 624thread name 625.It CPU 626current or most recent CPU run on 627.It PRI 628thread priority 629.It STATE 630thread state 631.It WCHAN 632thread wait channel 633.El 634.Ss Virtual Memory Mappings 635Display process virtual memory mappings, including addresses, mapping 636meta-data, and mapped object information: 637.Pp 638.Bl -tag -width indent -compact 639.It PID 640process ID 641.It START 642starting address of mapping 643.It END 644ending address of mapping 645.It PRT 646protection flags 647.It RES 648resident pages 649.It PRES 650private resident pages 651.It REF 652reference count 653.It SHD 654shadow page count 655.It FLAG 656mapping flags 657.It TP 658VM object type 659.El 660.Pp 661The following protection flags may be displayed: 662.Pp 663.Bl -tag -width X -compact 664.It r 665read 666.It w 667write 668.It x 669execute 670.El 671.Pp 672The following VM object types may be displayed: 673.Pp 674.Bl -tag -width XX -compact 675.It -- 676none 677.It dd 678dead 679.It df 680default 681.It dv 682device 683.It md 684device with managed pages 685.Pq GEM/TTM 686.It ph 687physical 688.It sg 689scatter/gather 690.It sw 691swap 692.It vn 693vnode 694.It gd 695guard (pseudo-type) 696.El 697.Pp 698The following mapping flags may be displayed: 699.Pp 700.Bl -tag -width X -compact 701.It C 702copy-on-write 703.It N 704needs copy 705.It S 706one or more superpage mappings are used 707.It D 708grows down (top-down stack) 709.It U 710grows up (bottom-up stack) 711.It W 712pages in this range are locked by 713.Xr mlock 2 714or 715.Xr mlockall 2 716.El 717.Ss ELF Auxiliary Vector 718Display ELF auxiliary vector values: 719.Pp 720.Bl -tag -width indent -compact 721.It PID 722process ID 723.It COMM 724command 725.It AUXV 726auxiliary vector name 727.It VALUE 728auxiliary vector value 729.El 730.Ss Advisory Lock Information 731.Bl -tag -width indent -compact 732.It RW 733Read/Write type, 734.Va RO 735for read, 736.Va RW 737for write lock 738.It TYPE 739Type of the lock, one of 740.Va FLOCK 741for 742.Xr flock 2 , 743.Va FCNTL 744for 745.Xr fcntl 2 , 746.Va LOCKD 747for remote 748.It PID 749Process id of the owner, for 750.Va FCNTL 751and remote types 752.It SYSID 753Remote system id if applicable 754.It FSID 755File system id where the locked file resize 756.It RDEV 757rdev for the file system 758.It INO 759Unique file identifier (inode number) of the locked file 760on the file system 761.It START 762Start offset of the locked range 763.It LEN 764Length of the locked range. 765Zero means till EOF 766.It PATH 767If available, the path of the locked file 768.El 769.Sh EXIT STATUS 770.Ex -std 771.Sh EXAMPLES 772Show binary information about the current shell: 773.Bd -literal -offset indent 774$ procstat binary $$ 775 PID COMM OSREL PATH 77646620 bash 1201000 /usr/local/bin/bash 777.Ed 778.Pp 779Same as above but showing information about open file descriptors: 780.Bd -literal -offset indent 781$ procstat files $$ 782 PID COMM FD T V FLAGS REF OFFSET PRO NAME 78346620 bash text v r r------- - - - /usr/local/bin/bash 78446620 bash ctty v c rw------ - - - /dev/pts/12 78546620 bash cwd v d r------- - - - /tmp 78646620 bash root v d r------- - - - / 78746620 bash 0 v c rw------ 7 372071 - /dev/pts/12 78846620 bash 1 v c rw------ 7 372071 - /dev/pts/12 78946620 bash 2 v c rw------ 7 372071 - /dev/pts/12 79046620 bash 255 v c rw------ 7 372071 - /dev/pts/12 791.Ed 792.Pp 793Show the arguments used to launch 794.Xr init 8 : 795.Bd -literal -offset indent 796$ procstat arguments 1 797 PID COMM ARGS 798 1 init /sbin/init -- 799.Ed 800.Pp 801Extract binary information from a core dump: 802.Bd -literal -offset indent 803$ procstat binary core.36642 804 PID COMM OSREL PATH 80536642 top 1201000 /usr/bin/top 806.Ed 807.Pp 808Trying to extract information from a core file generated in a different major 809.Fx 810version might show an error like this: 811.Bd -literal -offset indent 812$ procstat mplayer.core 813procstat: kinfo_proc structure size mismatch 814procstat: procstat_getprocs() 815.Ed 816.Sh SEE ALSO 817.Xr fstat 1 , 818.Xr ps 1 , 819.Xr sockstat 1 , 820.Xr cap_enter 2 , 821.Xr cap_rights_limit 2 , 822.Xr mlock 2 , 823.Xr mlockall 2 , 824.Xr libprocstat 3 , 825.Xr libxo 3 , 826.Xr signal 3 , 827.Xr xo_parse_args 3 , 828.Xr ddb 4 , 829.Xr divert 4 , 830.Xr icmp 4 , 831.Xr ip 4 , 832.Xr sctp 4 , 833.Xr tcp 4 , 834.Xr udp 4 , 835.Xr stack 9 836.Sh AUTHORS 837.An Robert N M Watson Aq Mt rwatson@FreeBSD.org . 838.br 839.Xr libxo 3 840support was added by 841.An -nosplit 842Allan Jude 843.Aq Mt allanjude@FreeBSD.org . 844.br 845.An Juraj Lutter 846.Aq Mt juraj@lutter.sk 847added the pargs, penv and pwdx functionality. 848.Sh BUGS 849The display of open file or memory mapping pathnames is implemented using the 850kernel's name cache. 851If a file system does not use the name cache, or the path to a file is not in 852the cache, a path will not be displayed. 853.Pp 854.Nm 855currently supports extracting data only from a live kernel, and not from 856kernel crash dumps. 857