usr.bin/procstat/procstat.1

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