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