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 March 4, 2019
  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 .Sh DESCRIPTION
 106 .Nm
 107 utility displays detailed information about the processes identified by the
 108 .Ar pid
 109 arguments, or if the
 110 .Fl a
 111 flag is used, all processes.
 112 It can also display information extracted from a process core file, if
 113 the core file is specified as the argument.
 114 .Pp
 115 If the
 116 .Fl -libxo
 117 flag is specified the output is generated via
 118 .Xr libxo 3
 119 in a selection of different human and machine readable formats.
 120 See
 121 .Xr xo_parse_args 3
 122 for details on command line arguments.
 123 .Pp
 124 The following commands are available:
 125 .Bl -tag -width indent
 126 .It Ar basic
 127 Print basic process statistics (this is the default).
 128 .It Ar binary | Fl b
 129 Display binary information for the process.
 130 .Pp
 131 Substring commands are accepted.
 132 .It Ar argument(s) | Fl c
 133 Display command line arguments for the process.
 134 .Pp
 135 Substring commands are accepted.
 136 .It Ar environment | Fl e
 137 Display environment variables for the process.
 138 .Pp
 139 Substring commands are accepted.
 140 .It Ar file(s) | Ar fd(s) | Fl f
 141 Display file descriptor information for the process.
 142 .Pp
 143 If the
 144 .Fl C
 145 subcommand flag is used then additional capability information is printed.
 146 .It Ar signal(s) | Fl i
 147 Display signal pending and disposition information for the process.
 148 .Pp
 149 If the
 150 .Fl n
 151 subcommand option is used, the signal numbers are shown instead of signal
 152 names.
 153 .Pp
 154 Substring commands are accepted.
 155 .It Ar tsignal(s) | Fl j
 156 Display signal pending and blocked information for the process's threads.
 157 .Pp
 158 If the
 159 .Fl n
 160 subcommand option is used, the signal numbers are shown instead of signal
 161 names.
 162 .Pp
 163 Substring commands are accepted.
 164 .It Ar kstack | Fl k
 165 Display the stacks of kernel threads in the process, excluding stacks of
 166 threads currently running on a CPU and threads with stacks swapped to disk.
 167 .Pp
 168 If the
 169 .Fl v
 170 subcommand option is used (or the command flag is repeated), function
 171 offsets as well as function names are printed.
 172 .It Ar rlimit | Fl l
 173 Display resource limits for the process.
 174 .It Ar ptlwpinfo | Fl L
 175 Display LWP info for the process pertaining to its signal driven exit.
 176 .It Ar rusage | Fl r
 177 Display resource usage information for the process.
 178 .Pp
 179 If the
 180 .Fl v
 181 .Pq or Fl H
 182 subcommand flag
 183 is used then per-thread statistics are printed, rather than per-process
 184 statistics.
 185 The second field in the table will list the thread ID to which the row of
 186 information corresponds.
 187 .It Ar credential(s) | Fl s
 188 Display security credential information for the process.
 189 .Pp
 190 Substring commands are accepted.
 191 .It Ar cpuset | Ar cs | Fl S
 192 Display the cpuset information for the thread.
 193 .It Ar thread(s) | Fl t
 194 Display thread information for the process.
 195 .It Ar vm | Fl v
 196 Display virtual memory mappings for the process.
 197 .It Ar auxv | Fl x
 198 Display ELF auxiliary vector for the process.
 199 .El
 200 .Pp
 201 All options generate output in the format of a table, the first field of
 202 which is the process ID to which the row of information corresponds.
 203 The
 204 .Fl h
 205 flag may be used to suppress table headers.
 206 .Pp
 207 The
 208 .Fl w
 209 flag may be used to specify a wait interval at which to repeat the printing
 210 of the requested process information.
 211 If the
 212 .Fl w
 213 flag is not specified, the output will not repeat.
 214 .Pp
 215 Information for VM, file descriptor, and cpuset options is available
 216 only to the owner of a process or the superuser.
 217 A cpuset value displayed as -1 means that the information is either invalid
 218 or not available.
 219 .Ss Binary Information
 220 Display the process ID, command, and path to the process binary:
 221 .Pp
 222 .Bl -tag -width indent -compact
 223 .It PID
 224 process ID
 225 .It COMM
 226 command
 227 .It OSREL
 228 osreldate for process binary
 229 .It PATH
 230 path to process binary (if available)
 231 .El
 232 .Ss Command Line Arguments
 233 Display the process ID, command, and command line arguments:
 234 .Pp
 235 .Bl -tag -width indent -compact
 236 .It PID
 237 process ID
 238 .It COMM
 239 command
 240 .It ARGS
 241 command line arguments (if available)
 242 .El
 243 .Ss Environment Variables
 244 Display the process ID, command, and environment variables:
 245 .Pp
 246 .Bl -tag -width "ENVIRONMENT" -compact
 247 .It PID
 248 process ID
 249 .It COMM
 250 command
 251 .It ENVIRONMENT
 252 environment variables (if available)
 253 .El
 254 .Ss File Descriptors
 255 Display detailed information about each file descriptor referenced by a
 256 process, including the process ID, command, file descriptor number, and
 257 per-file descriptor object information, such as object type and file system
 258 path.
 259 By default, the following information will be printed:
 260 .Pp
 261 .Bl -tag -width indent -compact
 262 .It PID
 263 process ID
 264 .It COMM
 265 command
 266 .It FD
 267 file descriptor number or cwd/root/jail
 268 .It T
 269 file descriptor type
 270 .It V
 271 vnode type
 272 .It FLAGS
 273 file descriptor flags
 274 .It REF
 275 file descriptor reference count
 276 .It OFFSET
 277 file descriptor offset
 278 .It PRO
 279 network protocol
 280 .It NAME
 281 file path or socket addresses (if available)
 282 .El
 283 .Pp
 284 The following file descriptor types may be displayed:
 285 .Pp
 286 .Bl -tag -width X -compact
 287 .It c
 288 crypto
 289 .It e
 290 POSIX semaphore
 291 .It f
 292 fifo
 293 .It h
 294 shared memory
 295 .It k
 296 kqueue
 297 .It m
 298 message queue
 299 .It P
 300 process descriptor
 301 .It p
 302 pipe
 303 .It s
 304 socket
 305 .It t
 306 pseudo-terminal master
 307 .It v
 308 vnode
 309 .El
 310 .Pp
 311 The following vnode types may be displayed:
 312 .Pp
 313 .Bl -tag -width X -compact
 314 .It -
 315 not a vnode
 316 .It b
 317 block device
 318 .It c
 319 character device
 320 .It d
 321 directory
 322 .It f
 323 fifo
 324 .It l
 325 symbolic link
 326 .It r
 327 regular file
 328 .It s
 329 socket
 330 .It x
 331 revoked device
 332 .El
 333 .Pp
 334 The following file descriptor flags may be displayed:
 335 .Pp
 336 .Bl -tag -width X -compact
 337 .It r
 338 read
 339 .It w
 340 write
 341 .It a
 342 append
 343 .It s
 344 async
 345 .It f
 346 fsync
 347 .It n
 348 non-blocking
 349 .It d
 350 direct I/O
 351 .It l
 352 lock held
 353 .El
 354 .Pp
 355 If the
 356 .Fl C
 357 flag is specified, the vnode type, reference count, and offset fields will be
 358 omitted, and a new capabilities field will be included listing capabilities,
 359 as described in
 360 .Xr cap_rights_limit 2 ,
 361 present for each capability descriptor.
 362 .Pp
 363 The following network protocols may be displayed (grouped by address family):
 364 .Pp
 365 .Dv AF_INET ,
 366 .Dv AF_INET6
 367 .Pp
 368 .Bl -tag -width indent -compact
 369 .It ICM
 370 .Dv IPPROTO_ICMP ;
 371 see
 372 .Xr icmp 4 .
 373 .It IPD
 374 .Dv IPPROTO_DIVERT ;
 375 see
 376 .Xr divert 4 .
 377 .It IP?
 378 unknown protocol.
 379 .It RAW
 380 .Dv IPPROTO_RAW ;
 381 see
 382 .Xr ip 4 .
 383 .It SCT
 384 .Dv IPPROTO_SCTP ;
 385 see
 386 .Xr sctp 4 .
 387 .It TCP
 388 .Dv IPPROTO_TCP ;
 389 see
 390 .Xr tcp 4 .
 391 .It UDP
 392 .Dv IPPROTO_UDP ;
 393 see
 394 .Xr udp 4 .
 395 .El
 396 .Pp
 397 .Dv AF_LOCAL
 398 .Pp
 399 .Bl -tag -width indent -compact
 400 .It UDD
 401 .Dv IPPROTO_UDP ;
 402 see
 403 .Xr udp 4 .
 404 .It UDS
 405 .Dv IPPROTO_TCP ;
 406 see
 407 .Xr tcp 4 .
 408 .It UD?
 409 unknown protocol.
 410 .El
 411 .Pp
 412 .Bl -tag -width indent -compact
 413 .It ?
 414 unknown address family.
 415 .El
 416 .Ss Signal Disposition Information
 417 Display signal pending and disposition for a process:
 418 .Pp
 419 .Bl -tag -width indent -compact
 420 .It PID
 421 process ID
 422 .It COMM
 423 command
 424 .It SIG
 425 signal name
 426 .It FLAGS
 427 process signal disposition details, three symbols
 428 .Bl -tag -width X -compact
 429 .It P
 430 if signal is pending in the global process queue; - otherwise.
 431 .It I
 432 if signal delivery disposition is
 433 .Dv SIG_IGN;
 434 - otherwise.
 435 .It C
 436 if the signal will be caught; - otherwise.
 437 .El
 438 .El
 439 .Pp
 440 If
 441 .Fl n
 442 switch is given, the signal numbers are shown instead of signal names.
 443 .Ss Thread Signal Information
 444 Display signal pending and blocked for a process's threads:
 445 .Pp
 446 .Bl -tag -width indent -compact
 447 .It PID
 448 process ID
 449 .It TID
 450 thread ID
 451 .It COMM
 452 command
 453 .It SIG
 454 signal name
 455 .It FLAGS
 456 thread signal delivery status, two symbols
 457 .Bl -tag -width X -compact
 458 .It P
 459 if signal is pending for the thread, - otherwise
 460 .It B
 461 if signal is blocked in the thread signal mask, - if not blocked
 462 .El
 463 .El
 464 .Pp
 465 The
 466 .Fl n
 467 switch has the same effect as for the
 468 .Fl i
 469 switch: the signal numbers are shown instead of signal names.
 470 .Ss Kernel Thread Stacks
 471 Display kernel thread stacks for a process, allowing further interpretation
 472 of thread wait channels.
 473 If the
 474 .Fl k
 475 flag is repeated, function offsets, not just function names, are printed.
 476 .Pp
 477 This feature requires
 478 .Cd "options STACK"
 479 or
 480 .Cd "options DDB"
 481 to be compiled into the kernel.
 482 .Pp
 483 .Bl -tag -width indent -compact
 484 .It PID
 485 process ID
 486 .It TID
 487 thread ID
 488 .It COMM
 489 command
 490 .It TDNAME
 491 thread name
 492 .It KSTACK
 493 kernel thread call stack
 494 .El
 495 .Ss Resource Limits
 496 Display resource limits for a process:
 497 .Pp
 498 .Bl -tag -width indent -compact
 499 .It PID
 500 process ID
 501 .It COMM
 502 command
 503 .It RLIMIT
 504 resource limit name
 505 .It SOFT
 506 soft limit
 507 .It HARD
 508 hard limit
 509 .El
 510 .Ss Resource Usage
 511 Display resource usage for a process.
 512 If the
 513 .Fl H
 514 flag is specified,
 515 resource usage for individual threads is displayed instead.
 516 .Pp
 517 .Bl -tag -width "RESOURCE" -compact
 518 .It PID
 519 process ID
 520 .It TID
 521 thread ID
 522 .Po
 523 if
 524 .Fl H
 525 is specified
 526 .Pc
 527 .It COMM
 528 command
 529 .It RESOURCE
 530 resource name
 531 .It VALUE
 532 current usage
 533 .El
 534 .Ss Security Credentials
 535 Display process credential information:
 536 .Pp
 537 .Bl -tag -width indent -compact
 538 .It PID
 539 process ID
 540 .It COMM
 541 command
 542 .It EUID
 543 effective user ID
 544 .It RUID
 545 real user ID
 546 .It SVUID
 547 saved user ID
 548 .It EGID
 549 effective group ID
 550 .It RGID
 551 real group ID
 552 .It SVGID
 553 saved group ID
 554 .It UMASK
 555 file creation mode mask
 556 .It FLAGS
 557 credential flags
 558 .It GROUPS
 559 group set
 560 .El
 561 .Pp
 562 The following credential flags may be displayed:
 563 .Pp
 564 .Bl -tag -width X -compact
 565 .It C
 566 capability mode
 567 .El
 568 .Ss Thread Information
 569 Display per-thread information, including process ID, per-thread ID, name,
 570 CPU, and execution state:
 571 .Pp
 572 .Bl -tag -width indent -compact
 573 .It PID
 574 process ID
 575 .It TID
 576 thread ID
 577 .It COMM
 578 command
 579 .It TDNAME
 580 thread name
 581 .It CPU
 582 current or most recent CPU run on
 583 .It PRI
 584 thread priority
 585 .It STATE
 586 thread state
 587 .It WCHAN
 588 thread wait channel
 589 .El
 590 .Ss Virtual Memory Mappings
 591 Display process virtual memory mappings, including addresses, mapping
 592 meta-data, and mapped object information:
 593 .Pp
 594 .Bl -tag -width indent -compact
 595 .It PID
 596 process ID
 597 .It START
 598 starting address of mapping
 599 .It END
 600 ending address of mapping
 601 .It PRT
 602 protection flags
 603 .It RES
 604 resident pages
 605 .It PRES
 606 private resident pages
 607 .It REF
 608 reference count
 609 .It SHD
 610 shadow page count
 611 .It FLAG
 612 mapping flags
 613 .It TP
 614 VM object type
 615 .El
 616 .Pp
 617 The following protection flags may be displayed:
 618 .Pp
 619 .Bl -tag -width X -compact
 620 .It r
 621 read
 622 .It w
 623 write
 624 .It x
 625 execute
 626 .El
 627 .Pp
 628 The following VM object types may be displayed:
 629 .Pp
 630 .Bl -tag -width XX -compact
 631 .It --
 632 none
 633 .It dd
 634 dead
 635 .It df
 636 default
 637 .It dv
 638 device
 639 .It md
 640 device with managed pages
 641 .Pq GEM/TTM
 642 .It ph
 643 physical
 644 .It sg
 645 scatter/gather
 646 .It sw
 647 swap
 648 .It vn
 649 vnode
 650 .El
 651 .Pp
 652 The following mapping flags may be displayed:
 653 .Pp
 654 .Bl -tag -width X -compact
 655 .It C
 656 copy-on-write
 657 .It N
 658 needs copy
 659 .It S
 660 one or more superpage mappings are used
 661 .It D
 662 grows down (top-down stack)
 663 .It U
 664 grows up (bottom-up stack)
 665 .It W
 666 pages in this range are locked by
 667 .Xr mlock 2
 668 or
 669 .Xr mlockall 2
 670 .El
 671 .Ss ELF Auxiliary Vector
 672 Display ELF auxiliary vector values:
 673 .Pp
 674 .Bl -tag -width indent -compact
 675 .It PID
 676 process ID
 677 .It COMM
 678 command
 679 .It AUXV
 680 auxiliary vector name
 681 .It VALUE
 682 auxiliary vector value
 683 .El
 684 .Sh EXIT STATUS
 685 .Ex -std
 686 .Sh SEE ALSO
 687 .Xr fstat 1 ,
 688 .Xr ps 1 ,
 689 .Xr sockstat 1 ,
 690 .Xr cap_enter 2 ,
 691 .Xr cap_rights_limit 2 ,
 692 .Xr mlock 2 ,
 693 .Xr mlockall 2 ,
 694 .Xr libprocstat 3 ,
 695 .Xr libxo 3 ,
 696 .Xr signal 3 ,
 697 .Xr xo_parse_args 3 ,
 698 .Xr ddb 4 ,
 699 .Xr divert 4 ,
 700 .Xr icmp 4 ,
 701 .Xr ip 4 ,
 702 .Xr sctp 4 ,
 703 .Xr tcp 4 ,
 704 .Xr udp 4 ,
 705 .Xr stack 9
 706 .Sh AUTHORS
 707 .An Robert N M Watson Aq Mt rwatson@FreeBSD.org .
 708 .br
 709 .Xr libxo 3
 710 support was added by
 711 .An -nosplit
 712 Allan Jude
 713 .Aq Mt allanjude@FreeBSD.org .
 714 .Sh BUGS
 715 The display of open file or memory mapping pathnames is implemented using the
 716 kernel's name cache.
 717 If a file system does not use the name cache, or the path to a file is not in
 718 the cache, a path will not be displayed.
 719 .Pp
 720 .Nm
 721 currently supports extracting data only from a live kernel, and not from
 722 kernel crash dumps.