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