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