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