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 5, 2015
  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 it's 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 .Ss Signal Disposition Information
 275 Display signal pending and disposition for a process:
 276 .Pp
 277 .Bl -tag -width indent -compact
 278 .It PID
 279 process ID
 280 .It COMM
 281 command
 282 .It SIG
 283 signal name
 284 .It FLAGS
 285 process signal disposition details, three symbols
 286 .Bl -tag -width X -compact
 287 .It P
 288 if signal is pending in the global process queue, - otherwise
 289 .It I
 290 if signal delivery disposition is SIGIGN, - otherwise
 291 .It C
 292 if signal delivery is to catch it, - otherwise
 293 .El
 294 .El
 295 .Pp
 296 If
 297 .Fl n
 298 switch is given, the signal numbers are shown instead of signal names.
 299 .Ss Thread Signal Information
 300 Display signal pending and blocked for a process's threads:
 301 .Pp
 302 .Bl -tag -width indent -compact
 303 .It PID
 304 process ID
 305 .It TID
 306 thread ID
 307 .It COMM
 308 command
 309 .It SIG
 310 signal name
 311 .It FLAGS
 312 thread signal delivery status, two symbols
 313 .Bl -tag -width X -compact
 314 .It P
 315 if signal is pending for the thread, - otherwise
 316 .It B
 317 if signal is blocked in the thread signal mask, - if not blocked
 318 .El
 319 .El
 320 .Pp
 321 The
 322 .Fl n
 323 switch has the same effect as for the
 324 .Fl i
 325 switch: the signal numbers are shown instead of signal names.
 326 .Ss Kernel Thread Stacks
 327 Display kernel thread stacks for a process, allowing further interpretation
 328 of thread wait channels.
 329 If the
 330 .Fl k
 331 flag is repeated, function offsets, not just function names, are printed.
 332 .Pp
 333 This feature requires
 334 .Cd "options STACK"
 335 or
 336 .Cd "options DDB"
 337 to be compiled into the kernel.
 338 .Pp
 339 .Bl -tag -width indent -compact
 340 .It PID
 341 process ID
 342 .It TID
 343 thread ID
 344 .It COMM
 345 command
 346 .It TDNAME
 347 thread name
 348 .It KSTACK
 349 kernel thread call stack
 350 .El
 351 .Ss Resource Limits
 352 Display resource limits for a process:
 353 .Pp
 354 .Bl -tag -width indent -compact
 355 .It PID
 356 process ID
 357 .It COMM
 358 command
 359 .It RLIMIT
 360 resource limit name
 361 .It SOFT
 362 soft limit
 363 .It HARD
 364 hard limit
 365 .El
 366 .Ss Resource Usage
 367 Display resource usage for a process.
 368 If the
 369 .Fl H
 370 flag is specified,
 371 resource usage for individual threads is displayed instead.
 372 .Pp
 373 .Bl -tag -width "RESOURCE" -compact
 374 .It PID
 375 process ID
 376 .It TID
 377 thread ID
 378 .Po
 379 if
 380 .Fl H
 381 is specified
 382 .Pc
 383 .It COMM
 384 command
 385 .It RESOURCE
 386 resource name
 387 .It VALUE
 388 current usage
 389 .El
 390 .Ss Security Credentials
 391 Display process credential information:
 392 .Pp
 393 .Bl -tag -width indent -compact
 394 .It PID
 395 process ID
 396 .It COMM
 397 command
 398 .It EUID
 399 effective user ID
 400 .It RUID
 401 real user ID
 402 .It SVUID
 403 saved user ID
 404 .It EGID
 405 effective group ID
 406 .It RGID
 407 real group ID
 408 .It SVGID
 409 saved group ID
 410 .It UMASK
 411 file creation mode mask
 412 .It FLAGS
 413 credential flags
 414 .It GROUPS
 415 group set
 416 .El
 417 .Pp
 418 The following credential flags may be displayed:
 419 .Pp
 420 .Bl -tag -width X -compact
 421 .It C
 422 capability mode
 423 .El
 424 .Ss Thread Information
 425 Display per-thread information, including process ID, per-thread ID, name,
 426 CPU, and execution state:
 427 .Pp
 428 .Bl -tag -width indent -compact
 429 .It PID
 430 process ID
 431 .It TID
 432 thread ID
 433 .It COMM
 434 command
 435 .It TDNAME
 436 thread name
 437 .It CPU
 438 current or most recent CPU run on
 439 .It PRI
 440 thread priority
 441 .It STATE
 442 thread state
 443 .It WCHAN
 444 thread wait channel
 445 .El
 446 .Ss Virtual Memory Mappings
 447 Display process virtual memory mappings, including addresses, mapping
 448 meta-data, and mapped object information:
 449 .Pp
 450 .Bl -tag -width indent -compact
 451 .It PID
 452 process ID
 453 .It START
 454 starting address of mapping
 455 .It END
 456 ending address of mapping
 457 .It PRT
 458 protection flags
 459 .It RES
 460 resident pages
 461 .It PRES
 462 private resident pages
 463 .It REF
 464 reference count
 465 .It SHD
 466 shadow page count
 467 .It FLAG
 468 mapping flags
 469 .It TP
 470 VM object type
 471 .El
 472 .Pp
 473 The following protection flags may be displayed:
 474 .Pp
 475 .Bl -tag -width X -compact
 476 .It r
 477 read
 478 .It w
 479 write
 480 .It x
 481 execute
 482 .El
 483 .Pp
 484 The following VM object types may be displayed:
 485 .Pp
 486 .Bl -tag -width XX -compact
 487 .It --
 488 none
 489 .It dd
 490 dead
 491 .It df
 492 default
 493 .It dv
 494 device
 495 .It md
 496 device with managed pages
 497 .Pq GEM/TTM
 498 .It ph
 499 physical
 500 .It sg
 501 scatter/gather
 502 .It sw
 503 swap
 504 .It vn
 505 vnode
 506 .El
 507 .Pp
 508 The following mapping flags may be displayed:
 509 .Pp
 510 .Bl -tag -width X -compact
 511 .It C
 512 copy-on-write
 513 .It N
 514 needs copy
 515 .It S
 516 one or more superpage mappings are used
 517 .It D
 518 grows down (top-down stack)
 519 .It U
 520 grows up (bottom-up stack)
 521 .El
 522 .Ss ELF Auxiliary Vector
 523 Display ELF auxiliary vector values:
 524 .Pp
 525 .Bl -tag -width indent -compact
 526 .It PID
 527 process ID
 528 .It COMM
 529 command
 530 .It AUXV
 531 auxiliary vector name
 532 .It VALUE
 533 auxiliary vector value
 534 .El
 535 .Sh EXIT STATUS
 536 .Ex -std
 537 .Sh SEE ALSO
 538 .Xr fstat 1 ,
 539 .Xr ps 1 ,
 540 .Xr sockstat 1 ,
 541 .Xr cap_enter 2 ,
 542 .Xr cap_rights_limit 2 ,
 543 .Xr libprocstat 3 ,
 544 .Xr libxo 3 ,
 545 .Xr xo_parse_args 3 ,
 546 .Xr ddb 4 ,
 547 .Xr stack 9
 548 .Sh AUTHORS
 549 .An Robert N M Watson Aq Mt rwatson@FreeBSD.org .
 550 .br
 551 .Xr libxo 3
 552 support was added by
 553 .An -nosplit
 554 Allan Jude
 555 .Aq Mt allanjude@FreeBSD.org .
 556 .Sh BUGS
 557 The display of open file or memory mapping pathnames is implemented using the
 558 kernel's name cache.
 559 If a file system does not use the name cache, or the path to a file is not in
 560 the cache, a path will not be displayed.
 561 .Pp
 562 .Nm
 563 currently supports extracting data only from a live kernel, and not from
 564 kernel crash dumps.