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