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