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