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 26, 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 its 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 pipe
 217 .It s
 218 socket
 219 .It t
 220 pseudo-terminal master
 221 .It v
 222 vnode
 223 .El
 224 .Pp
 225 The following vnode types may be displayed:
 226 .Pp
 227 .Bl -tag -width X -compact
 228 .It -
 229 not a vnode
 230 .It b
 231 block device
 232 .It c
 233 character device
 234 .It d
 235 directory
 236 .It f
 237 fifo
 238 .It l
 239 symbolic link
 240 .It r
 241 regular file
 242 .It s
 243 socket
 244 .It x
 245 revoked device
 246 .El
 247 .Pp
 248 The following file descriptor flags may be displayed:
 249 .Pp
 250 .Bl -tag -width X -compact
 251 .It r
 252 read
 253 .It w
 254 write
 255 .It a
 256 append
 257 .It s
 258 async
 259 .It f
 260 fsync
 261 .It n
 262 non-blocking
 263 .It d
 264 direct I/O
 265 .It l
 266 lock held
 267 .El
 268 .Pp
 269 If the
 270 .Fl C
 271 flag is specified, the vnode type, reference count, and offset fields will be
 272 omitted, and a new capabilities field will be included listing capabilities,
 273 as described in
 274 .Xr cap_rights_limit 2 ,
 275 present for each capability descriptor.
 276 .Pp
 277 The following network protocols may be displayed (grouped by address family):
 278 .Pp
 279 .Dv AF_INET ,
 280 .Dv AF_INET6
 281 .Pp
 282 .Bl -tag -width indent -compact
 283 .It ICM
 284 .Dv IPPROTO_ICMP ;
 285 see
 286 .Xr icmp 4 .
 287 .It IPD
 288 .Dv IPPROTO_DIVERT ;
 289 see
 290 .Xr divert 4 .
 291 .It IP\?
 292 unknown protocol.
 293 .It RAW
 294 .Dv IPPROTO_RAW ;
 295 see
 296 .Xr ip 4 .
 297 .It SCT
 298 .Dv IPPROTO_SCTP ;
 299 see
 300 .Xr sctp 4 .
 301 .It TCP
 302 .Dv IPPROTO_TCP ;
 303 see
 304 .Xr tcp 4 .
 305 .It UDP
 306 .Dv IPPROTO_UDP ;
 307 see
 308 .Xr udp 4 .
 309 .El
 310 .Pp
 311 .Dv AF_LOCAL
 312 .Pp
 313 .Bl -tag -width indent -compact
 314 .It UDD
 315 .Dv IPPROTO_UDP ;
 316 see
 317 .Xr udp 4 .
 318 .It UDS
 319 .Dv IPPROTO_TCP ;
 320 see
 321 .Xr tcp 4 .
 322 .It UD\?
 323 unknown protocol.
 324 .El
 325 .Pp
 326 .Bl -tag -width indent -compact
 327 .It \?
 328 unknown address family.
 329 .El
 330 .Ss Signal Disposition Information
 331 Display signal pending and disposition for a process:
 332 .Pp
 333 .Bl -tag -width indent -compact
 334 .It PID
 335 process ID
 336 .It COMM
 337 command
 338 .It SIG
 339 signal name
 340 .It FLAGS
 341 process signal disposition details, three symbols
 342 .Bl -tag -width X -compact
 343 .It P
 344 if signal is pending in the global process queue; - otherwise.
 345 .It I
 346 if signal delivery disposition is
 347 .Dv SIG_IGN;
 348 - otherwise.
 349 .It C
 350 if the signal will be caught; - otherwise.
 351 .El
 352 .El
 353 .Pp
 354 If
 355 .Fl n
 356 switch is given, the signal numbers are shown instead of signal names.
 357 .Ss Thread Signal Information
 358 Display signal pending and blocked for a process's threads:
 359 .Pp
 360 .Bl -tag -width indent -compact
 361 .It PID
 362 process ID
 363 .It TID
 364 thread ID
 365 .It COMM
 366 command
 367 .It SIG
 368 signal name
 369 .It FLAGS
 370 thread signal delivery status, two symbols
 371 .Bl -tag -width X -compact
 372 .It P
 373 if signal is pending for the thread, - otherwise
 374 .It B
 375 if signal is blocked in the thread signal mask, - if not blocked
 376 .El
 377 .El
 378 .Pp
 379 The
 380 .Fl n
 381 switch has the same effect as for the
 382 .Fl i
 383 switch: the signal numbers are shown instead of signal names.
 384 .Ss Kernel Thread Stacks
 385 Display kernel thread stacks for a process, allowing further interpretation
 386 of thread wait channels.
 387 If the
 388 .Fl k
 389 flag is repeated, function offsets, not just function names, are printed.
 390 .Pp
 391 This feature requires
 392 .Cd "options STACK"
 393 or
 394 .Cd "options DDB"
 395 to be compiled into the kernel.
 396 .Pp
 397 .Bl -tag -width indent -compact
 398 .It PID
 399 process ID
 400 .It TID
 401 thread ID
 402 .It COMM
 403 command
 404 .It TDNAME
 405 thread name
 406 .It KSTACK
 407 kernel thread call stack
 408 .El
 409 .Ss Resource Limits
 410 Display resource limits for a process:
 411 .Pp
 412 .Bl -tag -width indent -compact
 413 .It PID
 414 process ID
 415 .It COMM
 416 command
 417 .It RLIMIT
 418 resource limit name
 419 .It SOFT
 420 soft limit
 421 .It HARD
 422 hard limit
 423 .El
 424 .Ss Resource Usage
 425 Display resource usage for a process.
 426 If the
 427 .Fl H
 428 flag is specified,
 429 resource usage for individual threads is displayed instead.
 430 .Pp
 431 .Bl -tag -width "RESOURCE" -compact
 432 .It PID
 433 process ID
 434 .It TID
 435 thread ID
 436 .Po
 437 if
 438 .Fl H
 439 is specified
 440 .Pc
 441 .It COMM
 442 command
 443 .It RESOURCE
 444 resource name
 445 .It VALUE
 446 current usage
 447 .El
 448 .Ss Security Credentials
 449 Display process credential information:
 450 .Pp
 451 .Bl -tag -width indent -compact
 452 .It PID
 453 process ID
 454 .It COMM
 455 command
 456 .It EUID
 457 effective user ID
 458 .It RUID
 459 real user ID
 460 .It SVUID
 461 saved user ID
 462 .It EGID
 463 effective group ID
 464 .It RGID
 465 real group ID
 466 .It SVGID
 467 saved group ID
 468 .It UMASK
 469 file creation mode mask
 470 .It FLAGS
 471 credential flags
 472 .It GROUPS
 473 group set
 474 .El
 475 .Pp
 476 The following credential flags may be displayed:
 477 .Pp
 478 .Bl -tag -width X -compact
 479 .It C
 480 capability mode
 481 .El
 482 .Ss Thread Information
 483 Display per-thread information, including process ID, per-thread ID, name,
 484 CPU, and execution state:
 485 .Pp
 486 .Bl -tag -width indent -compact
 487 .It PID
 488 process ID
 489 .It TID
 490 thread ID
 491 .It COMM
 492 command
 493 .It TDNAME
 494 thread name
 495 .It CPU
 496 current or most recent CPU run on
 497 .It PRI
 498 thread priority
 499 .It STATE
 500 thread state
 501 .It WCHAN
 502 thread wait channel
 503 .El
 504 .Ss Virtual Memory Mappings
 505 Display process virtual memory mappings, including addresses, mapping
 506 meta-data, and mapped object information:
 507 .Pp
 508 .Bl -tag -width indent -compact
 509 .It PID
 510 process ID
 511 .It START
 512 starting address of mapping
 513 .It END
 514 ending address of mapping
 515 .It PRT
 516 protection flags
 517 .It RES
 518 resident pages
 519 .It PRES
 520 private resident pages
 521 .It REF
 522 reference count
 523 .It SHD
 524 shadow page count
 525 .It FLAG
 526 mapping flags
 527 .It TP
 528 VM object type
 529 .El
 530 .Pp
 531 The following protection flags may be displayed:
 532 .Pp
 533 .Bl -tag -width X -compact
 534 .It r
 535 read
 536 .It w
 537 write
 538 .It x
 539 execute
 540 .El
 541 .Pp
 542 The following VM object types may be displayed:
 543 .Pp
 544 .Bl -tag -width XX -compact
 545 .It --
 546 none
 547 .It dd
 548 dead
 549 .It df
 550 default
 551 .It dv
 552 device
 553 .It md
 554 device with managed pages
 555 .Pq GEM/TTM
 556 .It ph
 557 physical
 558 .It sg
 559 scatter/gather
 560 .It sw
 561 swap
 562 .It vn
 563 vnode
 564 .El
 565 .Pp
 566 The following mapping flags may be displayed:
 567 .Pp
 568 .Bl -tag -width X -compact
 569 .It C
 570 copy-on-write
 571 .It N
 572 needs copy
 573 .It S
 574 one or more superpage mappings are used
 575 .It D
 576 grows down (top-down stack)
 577 .It U
 578 grows up (bottom-up stack)
 579 .El
 580 .Ss ELF Auxiliary Vector
 581 Display ELF auxiliary vector values:
 582 .Pp
 583 .Bl -tag -width indent -compact
 584 .It PID
 585 process ID
 586 .It COMM
 587 command
 588 .It AUXV
 589 auxiliary vector name
 590 .It VALUE
 591 auxiliary vector value
 592 .El
 593 .Sh EXIT STATUS
 594 .Ex -std
 595 .Sh SEE ALSO
 596 .Xr fstat 1 ,
 597 .Xr ps 1 ,
 598 .Xr sockstat 1 ,
 599 .Xr cap_enter 2 ,
 600 .Xr cap_rights_limit 2 ,
 601 .Xr libprocstat 3 ,
 602 .Xr libxo 3 ,
 603 .Xr signal 3 ,
 604 .Xr xo_parse_args 3 ,
 605 .Xr ddb 4 ,
 606 .Xr divert 4 ,
 607 .Xr icmp 4 ,
 608 .Xr ip 4 ,
 609 .Xr sctp 4 ,
 610 .Xr tcp 4 ,
 611 .Xr udp 4 ,
 612 .Xr stack 9
 613 .Sh AUTHORS
 614 .An Robert N M Watson Aq Mt rwatson@FreeBSD.org .
 615 .br
 616 .Xr libxo 3
 617 support was added by
 618 .An -nosplit
 619 Allan Jude
 620 .Aq Mt allanjude@FreeBSD.org .
 621 .Sh BUGS
 622 The display of open file or memory mapping pathnames is implemented using the
 623 kernel's name cache.
 624 If a file system does not use the name cache, or the path to a file is not in
 625 the cache, a path will not be displayed.
 626 .Pp
 627 .Nm
 628 currently supports extracting data only from a live kernel, and not from
 629 kernel crash dumps.