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 September 5, 2015 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 CHhn 38.Op Fl w Ar interval 39.Op Fl b | c | e | f | i | j | k | l | r | s | S | t | v | x 40.Op Fl a | Ar pid | Ar core ... 41.Sh DESCRIPTION 42The 43.Nm 44utility displays detailed information about the processes identified by the 45.Ar pid 46arguments, or if the 47.Fl a 48flag is used, all processes. 49It can also display information extracted from a process core file, if 50the core file is specified as the argument. 51.Pp 52By default, basic process statistics are printed; one of the following 53options may be specified in order to select more detailed process information 54for printing: 55.Bl -tag -width indent 56.It Fl -libxo 57Generate output via 58.Xr libxo 3 59in a selection of different human and machine readable formats. 60See 61.Xr xo_parse_args 3 62for details on command line arguments. 63.It Fl b 64Display binary information for the process. 65.It Fl c 66Display command line arguments for the process. 67.It Fl e 68Display environment variables for the process. 69.It Fl f 70Display file descriptor information for the process. 71.It Fl i 72Display signal pending and disposition information for the process. 73.It Fl j 74Display signal pending and blocked information for the process's threads. 75.It Fl k 76Display the stacks of kernel threads in the process, excluding stacks of 77threads currently running on a CPU and threads with stacks swapped to disk. 78If the flag is repeated, function offsets as well as function names are 79printed. 80.It Fl l 81Display resource limits for the process. 82.It Fl r 83Display resource usage information for the process. 84.It Fl s 85Display security credential information for the process. 86.It Fl S 87Display the cpuset information for the thread. 88.It Fl t 89Display thread information for the process. 90.It Fl v 91Display virtual memory mappings for the process. 92.It Fl x 93Display ELF auxiliary vector for the process. 94.El 95.Pp 96All options generate output in the format of a table, the first field of 97which is the process ID to which the row of information corresponds. 98The 99.Fl h 100flag may be used to suppress table headers. 101.Pp 102The 103.Fl w 104flag may be used to specify a wait interval at which to repeat the printing 105of the requested process information. 106If the 107.Fl w 108flag is not specified, the output will not repeat. 109.Pp 110The 111.Fl C 112flag requests the printing of additional capability information in the file 113descriptor view. 114.Pp 115The 116.Fl H 117flag may be used to request per-thread statistics rather than per-process 118statistics for some options. 119For those options, the second field in the table will list the thread ID 120to which the row of information corresponds. 121The 122.Fl H 123flag is implied for the 124.Fl S 125mode. 126.Pp 127Information for VM, file descriptor, and cpuset options is available 128only to the owner of a process or the superuser. 129A cpuset value displayed as -1 means that the information is either invalid 130or not available. 131.Ss Binary Information 132Display the process ID, command, and path to the process binary: 133.Pp 134.Bl -tag -width indent -compact 135.It PID 136process ID 137.It COMM 138command 139.It OSREL 140osreldate for process binary 141.It PATH 142path to process binary (if available) 143.El 144.Ss Command Line Arguments 145Display the process ID, command, and command line arguments: 146.Pp 147.Bl -tag -width indent -compact 148.It PID 149process ID 150.It COMM 151command 152.It ARGS 153command line arguments (if available) 154.El 155.Ss Environment Variables 156Display the process ID, command, and environment variables: 157.Pp 158.Bl -tag -width "ENVIRONMENT" -compact 159.It PID 160process ID 161.It COMM 162command 163.It ENVIRONMENT 164environment variables (if available) 165.El 166.Ss File Descriptors 167Display detailed information about each file descriptor referenced by a 168process, including the process ID, command, file descriptor number, and 169per-file descriptor object information, such as object type and file system 170path. 171By default, the following information will be printed: 172.Pp 173.Bl -tag -width indent -compact 174.It PID 175process ID 176.It COMM 177command 178.It FD 179file descriptor number or cwd/root/jail 180.It T 181file descriptor type 182.It V 183vnode type 184.It FLAGS 185file descriptor flags 186.It REF 187file descriptor reference count 188.It OFFSET 189file descriptor offset 190.It PRO 191network protocol 192.It NAME 193file path or socket addresses (if available) 194.El 195.Pp 196The following file descriptor types may be displayed: 197.Pp 198.Bl -tag -width X -compact 199.It c 200crypto 201.It e 202POSIX semaphore 203.It f 204fifo 205.It h 206shared memory 207.It k 208kqueue 209.It m 210message queue 211.It p 212pipe 213.It s 214socket 215.It t 216pseudo-terminal master 217.It v 218vnode 219.El 220.Pp 221The following vnode types may be displayed: 222.Pp 223.Bl -tag -width X -compact 224.It - 225not a vnode 226.It b 227block device 228.It c 229character device 230.It d 231directory 232.It f 233fifo 234.It l 235symbolic link 236.It r 237regular file 238.It s 239socket 240.It x 241revoked device 242.El 243.Pp 244The following file descriptor flags may be displayed: 245.Pp 246.Bl -tag -width X -compact 247.It r 248read 249.It w 250write 251.It a 252append 253.It s 254async 255.It f 256fsync 257.It n 258non-blocking 259.It d 260direct I/O 261.It l 262lock held 263.El 264.Pp 265If the 266.Fl C 267flag is specified, the vnode type, reference count, and offset fields will be 268omitted, and a new capabilities field will be included listing capabilities, 269as described in 270.Xr cap_rights_limit 2 , 271present for each capability descriptor. 272.Ss Signal Disposition Information 273Display signal pending and disposition for a process: 274.Pp 275.Bl -tag -width indent -compact 276.It PID 277process ID 278.It COMM 279command 280.It SIG 281signal name 282.It FLAGS 283process signal disposition details, three symbols 284.Bl -tag -width X -compact 285.It P 286if signal is pending in the global process queue, - otherwise 287.It I 288if signal delivery disposition is SIGIGN, - otherwise 289.It C 290if signal delivery is to catch it, - otherwise 291.El 292.El 293.Pp 294If 295.Fl n 296switch is given, the signal numbers are shown instead of signal names. 297.Ss Thread Signal Information 298Display signal pending and blocked for a process's threads: 299.Pp 300.Bl -tag -width indent -compact 301.It PID 302process ID 303.It TID 304thread ID 305.It COMM 306command 307.It SIG 308signal name 309.It FLAGS 310thread signal delivery status, two symbols 311.Bl -tag -width X -compact 312.It P 313if signal is pending for the thread, - otherwise 314.It B 315if signal is blocked in the thread signal mask, - if not blocked 316.El 317.El 318.Pp 319The 320.Fl n 321switch has the same effect as for the 322.Fl i 323switch: the signal numbers are shown instead of signal names. 324.Ss Kernel Thread Stacks 325Display kernel thread stacks for a process, allowing further interpretation 326of thread wait channels. 327If the 328.Fl k 329flag is repeated, function offsets, not just function names, are printed. 330.Pp 331This feature requires 332.Cd "options STACK" 333or 334.Cd "options DDB" 335to be compiled into the kernel. 336.Pp 337.Bl -tag -width indent -compact 338.It PID 339process ID 340.It TID 341thread ID 342.It COMM 343command 344.It TDNAME 345thread name 346.It KSTACK 347kernel thread call stack 348.El 349.Ss Resource Limits 350Display resource limits for a process: 351.Pp 352.Bl -tag -width indent -compact 353.It PID 354process ID 355.It COMM 356command 357.It RLIMIT 358resource limit name 359.It SOFT 360soft limit 361.It HARD 362hard limit 363.El 364.Ss Resource Usage 365Display resource usage for a process. 366If the 367.Fl H 368flag is specified, 369resource usage for individual threads is displayed instead. 370.Pp 371.Bl -tag -width "RESOURCE" -compact 372.It PID 373process ID 374.It TID 375thread ID 376.Po 377if 378.Fl H 379is specified 380.Pc 381.It COMM 382command 383.It RESOURCE 384resource name 385.It VALUE 386current usage 387.El 388.Ss Security Credentials 389Display process credential information: 390.Pp 391.Bl -tag -width indent -compact 392.It PID 393process ID 394.It COMM 395command 396.It EUID 397effective user ID 398.It RUID 399real user ID 400.It SVUID 401saved user ID 402.It EGID 403effective group ID 404.It RGID 405real group ID 406.It SVGID 407saved group ID 408.It UMASK 409file creation mode mask 410.It FLAGS 411credential flags 412.It GROUPS 413group set 414.El 415.Pp 416The following credential flags may be displayed: 417.Pp 418.Bl -tag -width X -compact 419.It C 420capability mode 421.El 422.Ss Thread Information 423Display per-thread information, including process ID, per-thread ID, name, 424CPU, and execution state: 425.Pp 426.Bl -tag -width indent -compact 427.It PID 428process ID 429.It TID 430thread ID 431.It COMM 432command 433.It TDNAME 434thread name 435.It CPU 436current or most recent CPU run on 437.It PRI 438thread priority 439.It STATE 440thread state 441.It WCHAN 442thread wait channel 443.El 444.Ss Virtual Memory Mappings 445Display process virtual memory mappings, including addresses, mapping 446meta-data, and mapped object information: 447.Pp 448.Bl -tag -width indent -compact 449.It PID 450process ID 451.It START 452starting address of mapping 453.It END 454ending address of mapping 455.It PRT 456protection flags 457.It RES 458resident pages 459.It PRES 460private resident pages 461.It REF 462reference count 463.It SHD 464shadow page count 465.It FLAG 466mapping flags 467.It TP 468VM object type 469.El 470.Pp 471The following protection flags may be displayed: 472.Pp 473.Bl -tag -width X -compact 474.It r 475read 476.It w 477write 478.It x 479execute 480.El 481.Pp 482The following VM object types may be displayed: 483.Pp 484.Bl -tag -width XX -compact 485.It -- 486none 487.It dd 488dead 489.It df 490default 491.It dv 492device 493.It md 494device with managed pages 495.Pq GEM/TTM 496.It ph 497physical 498.It sg 499scatter/gather 500.It sw 501swap 502.It vn 503vnode 504.El 505.Pp 506The following mapping flags may be displayed: 507.Pp 508.Bl -tag -width X -compact 509.It C 510copy-on-write 511.It N 512needs copy 513.It S 514one or more superpage mappings are used 515.It D 516grows down (top-down stack) 517.It U 518grows up (bottom-up stack) 519.El 520.Ss ELF Auxiliary Vector 521Display ELF auxiliary vector values: 522.Pp 523.Bl -tag -width indent -compact 524.It PID 525process ID 526.It COMM 527command 528.It AUXV 529auxiliary vector name 530.It VALUE 531auxiliary vector value 532.El 533.Sh EXIT STATUS 534.Ex -std 535.Sh SEE ALSO 536.Xr fstat 1 , 537.Xr ps 1 , 538.Xr sockstat 1 , 539.Xr cap_enter 2 , 540.Xr cap_rights_limit 2 , 541.Xr libprocstat 3 , 542.Xr libxo 3 , 543.Xr xo_parse_args 3 , 544.Xr ddb 4 , 545.Xr stack 9 546.Sh AUTHORS 547.An Robert N M Watson Aq Mt rwatson@FreeBSD.org . 548.br 549.Xr libxo 3 550support was added by 551.An -nosplit 552Allan Jude 553.Aq Mt allanjude@FreeBSD.org . 554.Sh BUGS 555The display of open file or memory mapping pathnames is implemented using the 556kernel's name cache. 557If a file system does not use the name cache, or the path to a file is not in 558the cache, a path will not be displayed. 559.Pp 560.Nm 561currently supports extracting data only from a live kernel, and not from 562kernel crash dumps. 563