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 September 14, 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 c
 315 crypto
 316 .It e
 317 POSIX semaphore
 318 .It f
 319 fifo
 320 .It h
 321 shared memory
 322 .It k
 323 kqueue
 324 .It m
 325 message queue
 326 .It P
 327 process descriptor
 328 .It p
 329 pipe
 330 .It s
 331 socket
 332 .It t
 333 pseudo-terminal master
 334 .It v
 335 vnode
 336 .El
 337 .Pp
 338 The following vnode types may be displayed:
 339 .Pp
 340 .Bl -tag -width X -compact
 341 .It -
 342 not a vnode
 343 .It b
 344 block device
 345 .It c
 346 character device
 347 .It d
 348 directory
 349 .It f
 350 fifo
 351 .It l
 352 symbolic link
 353 .It r
 354 regular file
 355 .It s
 356 socket
 357 .It x
 358 revoked device
 359 .El
 360 .Pp
 361 The following file descriptor flags may be displayed:
 362 .Pp
 363 .Bl -tag -width X -compact
 364 .It r
 365 read
 366 .It w
 367 write
 368 .It a
 369 append
 370 .It s
 371 async
 372 .It f
 373 fsync
 374 .It n
 375 non-blocking
 376 .It d
 377 direct I/O
 378 .It l
 379 lock held
 380 .El
 381 .Pp
 382 If the
 383 .Fl C
 384 flag is specified, the vnode type, reference count, and offset fields will be
 385 omitted, and a new capabilities field will be included listing capabilities,
 386 as described in
 387 .Xr cap_rights_limit 2 ,
 388 present for each capability descriptor.
 389 .Pp
 390 The following network protocols may be displayed (grouped by address family):
 391 .Pp
 392 .Dv AF_INET ,
 393 .Dv AF_INET6
 394 .Pp
 395 .Bl -tag -width indent -compact
 396 .It ICM
 397 .Dv IPPROTO_ICMP ;
 398 see
 399 .Xr icmp 4 .
 400 .It IPD
 401 .Dv IPPROTO_DIVERT ;
 402 see
 403 .Xr divert 4 .
 404 .It IP?
 405 unknown protocol.
 406 .It RAW
 407 .Dv IPPROTO_RAW ;
 408 see
 409 .Xr ip 4 .
 410 .It SCT
 411 .Dv IPPROTO_SCTP ;
 412 see
 413 .Xr sctp 4 .
 414 .It TCP
 415 .Dv IPPROTO_TCP ;
 416 see
 417 .Xr tcp 4 .
 418 .It UDP
 419 .Dv IPPROTO_UDP ;
 420 see
 421 .Xr udp 4 .
 422 .El
 423 .Pp
 424 .Dv AF_LOCAL
 425 .Pp
 426 .Bl -tag -width indent -compact
 427 .It UDD
 428 .Dv IPPROTO_UDP ;
 429 see
 430 .Xr udp 4 .
 431 .It UDS
 432 .Dv IPPROTO_TCP ;
 433 see
 434 .Xr tcp 4 .
 435 .It UD?
 436 unknown protocol.
 437 .El
 438 .Pp
 439 .Bl -tag -width indent -compact
 440 .It ?
 441 unknown address family.
 442 .El
 443 .Ss Signal Disposition Information
 444 Display signal pending and disposition for a process:
 445 .Pp
 446 .Bl -tag -width indent -compact
 447 .It PID
 448 process ID
 449 .It COMM
 450 command
 451 .It SIG
 452 signal name
 453 .It FLAGS
 454 process signal disposition details, three symbols
 455 .Bl -tag -width X -compact
 456 .It P
 457 if signal is pending in the global process queue; - otherwise.
 458 .It I
 459 if signal delivery disposition is
 460 .Dv SIG_IGN ;
 461 - otherwise.
 462 .It C
 463 if the signal will be caught; - otherwise.
 464 .El
 465 .El
 466 .Pp
 467 If
 468 .Fl n
 469 switch is given, the signal numbers are shown instead of signal names.
 470 .Ss Thread Signal Information
 471 Display signal pending and blocked for a process's threads:
 472 .Pp
 473 .Bl -tag -width indent -compact
 474 .It PID
 475 process ID
 476 .It TID
 477 thread ID
 478 .It COMM
 479 command
 480 .It SIG
 481 signal name
 482 .It FLAGS
 483 thread signal delivery status, two symbols
 484 .Bl -tag -width X -compact
 485 .It P
 486 if signal is pending for the thread, - otherwise
 487 .It B
 488 if signal is blocked in the thread signal mask, - if not blocked
 489 .El
 490 .El
 491 .Pp
 492 The
 493 .Fl n
 494 switch has the same effect as for the
 495 .Fl i
 496 switch: the signal numbers are shown instead of signal names.
 497 .Ss Kernel Thread Stacks
 498 Display kernel thread stacks for a process, allowing further interpretation
 499 of thread wait channels.
 500 If the
 501 .Fl k
 502 flag is repeated, function offsets, not just function names, are printed.
 503 .Pp
 504 This feature requires
 505 .Cd "options STACK"
 506 or
 507 .Cd "options DDB"
 508 to be compiled into the kernel.
 509 .Pp
 510 .Bl -tag -width indent -compact
 511 .It PID
 512 process ID
 513 .It TID
 514 thread ID
 515 .It COMM
 516 command
 517 .It TDNAME
 518 thread name
 519 .It KSTACK
 520 kernel thread call stack
 521 .El
 522 .Ss Resource Limits
 523 Display resource limits for a process:
 524 .Pp
 525 .Bl -tag -width indent -compact
 526 .It PID
 527 process ID
 528 .It COMM
 529 command
 530 .It RLIMIT
 531 resource limit name
 532 .It SOFT
 533 soft limit
 534 .It HARD
 535 hard limit
 536 .El
 537 .Ss Resource Usage
 538 Display resource usage for a process.
 539 If the
 540 .Fl H
 541 flag is specified,
 542 resource usage for individual threads is displayed instead.
 543 .Pp
 544 .Bl -tag -width "RESOURCE" -compact
 545 .It PID
 546 process ID
 547 .It TID
 548 thread ID
 549 .Po
 550 if
 551 .Fl H
 552 is specified
 553 .Pc
 554 .It COMM
 555 command
 556 .It RESOURCE
 557 resource name
 558 .It VALUE
 559 current usage
 560 .El
 561 .Ss Security Credentials
 562 Display process credential information:
 563 .Pp
 564 .Bl -tag -width indent -compact
 565 .It PID
 566 process ID
 567 .It COMM
 568 command
 569 .It EUID
 570 effective user ID
 571 .It RUID
 572 real user ID
 573 .It SVUID
 574 saved user ID
 575 .It EGID
 576 effective group ID
 577 .It RGID
 578 real group ID
 579 .It SVGID
 580 saved group ID
 581 .It UMASK
 582 file creation mode mask
 583 .It FLAGS
 584 credential flags
 585 .It GROUPS
 586 group set
 587 .El
 588 .Pp
 589 The following credential flags may be displayed:
 590 .Pp
 591 .Bl -tag -width X -compact
 592 .It C
 593 capability mode
 594 .El
 595 .Ss Thread Information
 596 Display per-thread information, including process ID, per-thread ID, name,
 597 CPU, and execution state:
 598 .Pp
 599 .Bl -tag -width indent -compact
 600 .It PID
 601 process ID
 602 .It TID
 603 thread ID
 604 .It COMM
 605 command
 606 .It TDNAME
 607 thread name
 608 .It CPU
 609 current or most recent CPU run on
 610 .It PRI
 611 thread priority
 612 .It STATE
 613 thread state
 614 .It WCHAN
 615 thread wait channel
 616 .El
 617 .Ss Virtual Memory Mappings
 618 Display process virtual memory mappings, including addresses, mapping
 619 meta-data, and mapped object information:
 620 .Pp
 621 .Bl -tag -width indent -compact
 622 .It PID
 623 process ID
 624 .It START
 625 starting address of mapping
 626 .It END
 627 ending address of mapping
 628 .It PRT
 629 protection flags
 630 .It RES
 631 resident pages
 632 .It PRES
 633 private resident pages
 634 .It REF
 635 reference count
 636 .It SHD
 637 shadow page count
 638 .It FLAG
 639 mapping flags
 640 .It TP
 641 VM object type
 642 .El
 643 .Pp
 644 The following protection flags may be displayed:
 645 .Pp
 646 .Bl -tag -width X -compact
 647 .It r
 648 read
 649 .It w
 650 write
 651 .It x
 652 execute
 653 .El
 654 .Pp
 655 The following VM object types may be displayed:
 656 .Pp
 657 .Bl -tag -width XX -compact
 658 .It --
 659 none
 660 .It dd
 661 dead
 662 .It df
 663 default
 664 .It dv
 665 device
 666 .It md
 667 device with managed pages
 668 .Pq GEM/TTM
 669 .It ph
 670 physical
 671 .It sg
 672 scatter/gather
 673 .It sw
 674 swap
 675 .It vn
 676 vnode
 677 .El
 678 .Pp
 679 The following mapping flags may be displayed:
 680 .Pp
 681 .Bl -tag -width X -compact
 682 .It C
 683 copy-on-write
 684 .It N
 685 needs copy
 686 .It S
 687 one or more superpage mappings are used
 688 .It D
 689 grows down (top-down stack)
 690 .It U
 691 grows up (bottom-up stack)
 692 .It W
 693 pages in this range are locked by
 694 .Xr mlock 2
 695 or
 696 .Xr mlockall 2
 697 .El
 698 .Ss ELF Auxiliary Vector
 699 Display ELF auxiliary vector values:
 700 .Pp
 701 .Bl -tag -width indent -compact
 702 .It PID
 703 process ID
 704 .It COMM
 705 command
 706 .It AUXV
 707 auxiliary vector name
 708 .It VALUE
 709 auxiliary vector value
 710 .El
 711 .Sh EXIT STATUS
 712 .Ex -std
 713 .Sh SEE ALSO
 714 .Xr fstat 1 ,
 715 .Xr ps 1 ,
 716 .Xr sockstat 1 ,
 717 .Xr cap_enter 2 ,
 718 .Xr cap_rights_limit 2 ,
 719 .Xr mlock 2 ,
 720 .Xr mlockall 2 ,
 721 .Xr libprocstat 3 ,
 722 .Xr libxo 3 ,
 723 .Xr signal 3 ,
 724 .Xr xo_parse_args 3 ,
 725 .Xr ddb 4 ,
 726 .Xr divert 4 ,
 727 .Xr icmp 4 ,
 728 .Xr ip 4 ,
 729 .Xr sctp 4 ,
 730 .Xr tcp 4 ,
 731 .Xr udp 4 ,
 732 .Xr stack 9
 733 .Sh AUTHORS
 734 .An Robert N M Watson Aq Mt rwatson@FreeBSD.org .
 735 .br
 736 .Xr libxo 3
 737 support was added by
 738 .An -nosplit
 739 Allan Jude
 740 .Aq Mt allanjude@FreeBSD.org .
 741 .br
 742 .An Juraj Lutter
 743 .Aq Mt juraj@lutter.sk
 744 added the pargs, penv and pwdx functionality.
 745 .Sh BUGS
 746 The display of open file or memory mapping pathnames is implemented using the
 747 kernel's name cache.
 748 If a file system does not use the name cache, or the path to a file is not in
 749 the cache, a path will not be displayed.
 750 .Pp
 751 .Nm
 752 currently supports extracting data only from a live kernel, and not from
 753 kernel crash dumps.