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