usr.bin/procstat/procstat.1

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