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