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