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