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