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 April 19, 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 k
 147 kqueue
 148 .It m
 149 message queue
 150 .It p
 151 pipe
 152 .It s
 153 socket
 154 .It v
 155 vnode
 156 .El
 157 .Pp
 158 The following vnode types may be displayed:
 159 .Pp
 160 .Bl -tag -width X -compact
 161 .It -
 162 not a vnode
 163 .It b
 164 block device
 165 .It c
 166 character device
 167 .It f
 168 fifo
 169 .It l
 170 symbolic link
 171 .It s
 172 socket
 173 .It x
 174 revoked device
 175 .El
 176 .Pp
 177 The following file descriptor flags may be displayed:
 178 .Pp
 179 .Bl -tag -width X -compact
 180 .It r
 181 read
 182 .It w
 183 write
 184 .It a
 185 append
 186 .It s
 187 async
 188 .It f
 189 fsync
 190 .It n
 191 non-blocking
 192 .It d
 193 direct I/O
 194 .It l
 195 lock held
 196 .El
 197 .Ss Kernel Thread Stacks
 198 Display kernel thread stacks for a process, allowing further interpretation
 199 of thread wait channels.
 200 If the
 201 .Fl k
 202 flag is reeated, function offsets, not just function names, are printed.
 203 .Pp
 204 This feature requires
 205 .Cd "options STACK"
 206 or
 207 .Cd "options DDB"
 208 to be compiled into the kernel.
 209 .Pp
 210 .Bl -tag -width indent -compact
 211 .It PID
 212 process ID
 213 .It TID
 214 thread ID
 215 .It COMM
 216 command
 217 .It TDNAME
 218 thread name
 219 .It KSTACK
 220 kernel thread call stack
 221 .El
 222 .Ss Security Credentials
 223 Display process credential information:
 224 .Pp
 225 .Bl -tag -width indent -compact
 226 .It PID
 227 process ID
 228 .It COMM
 229 command
 230 .It EUID
 231 effective user ID
 232 .It RUID
 233 real user ID
 234 .It SVUID
 235 saved user ID
 236 .It EGID
 237 effective group ID
 238 .It RGID
 239 real group ID
 240 .It SVGID
 241 saved group ID
 242 .It GROUPS
 243 group set
 244 .El
 245 .Ss Thread Information
 246 Display per-thread information, including process ID, per-thread ID, name,
 247 CPU, and execution state:
 248 .Pp
 249 .Bl -tag -width indent -compact
 250 .It PID
 251 process ID
 252 .It TID
 253 thread ID
 254 .It COMM
 255 command
 256 .It TDNAME
 257 thread name
 258 .It CPU
 259 current or most recent CPU run on
 260 .It PRI
 261 thread priority
 262 .It STATE
 263 thread state
 264 .It WCHAN
 265 thread wait channel
 266 .El
 267 .Ss Virtual Memory Mappings
 268 Display process virtual memory mappings, including addresses, mapping
 269 meta-data, and mapped object information:
 270 .Pp
 271 .Bl -tag -width indent -compact
 272 .It PID
 273 process ID
 274 .It START
 275 starting address of mapping
 276 .It END
 277 ending address of mapping
 278 .It PRT
 279 protection flags
 280 .It RES
 281 resident pages
 282 .It PRES
 283 private resident pages
 284 .It REF
 285 reference count
 286 .It SHD
 287 shadow page count
 288 .It FL
 289 mapping flags
 290 .It TP
 291 VM object type
 292 .El
 293 .Pp
 294 The following protection flags may be displayed:
 295 .Pp
 296 .Bl -tag -width X -compact
 297 .It r
 298 read
 299 .It w
 300 write
 301 .It x
 302 execute
 303 .El
 304 .Pp
 305 The following VM object types may be displayed:
 306 .Pp
 307 .Bl -tag -width XX -compact
 308 .It --
 309 none
 310 .It dd
 311 dead
 312 .It df
 313 default
 314 .It dv
 315 device
 316 .It ph
 317 physical
 318 .It sw
 319 swap
 320 .It vn
 321 vnode
 322 .El
 323 .Pp
 324 The following mapping flags may be displayed:
 325 .Pp
 326 .Bl -tag -width X -compact
 327 .It C
 328 copy-on-write
 329 .It N
 330 needs copy
 331 .El
 332 .Sh EXIT STATUS
 333 .Ex -std
 334 .Sh SEE ALSO
 335 .Xr fstat 1 ,
 336 .Xr ps 1 ,
 337 .Xr sockstat 1 ,
 338 .Xr ddb 4 ,
 339 .Xr stack 9
 340 .Sh AUTHORS
 341 .An Robert N M Watson
 342 .Sh BUGS
 343 Some field values may include spaces, which limits the extent to which the
 344 output of
 345 .Nm
 346 may be mechanically parsed.
 347 .Pp
 348 The display of open file or memory mapping pathnames is implemented using the
 349 kernel's name cache.
 350 It therefore does not work for file systems
 351 that do not use the name cache, such as
 352 .Xr devfs 4 ,
 353 or if the name is not present in the cache due to removal.
 354 .Pp
 355 .Nm
 356 currently supports extracting data only from a live kernel, and not from
 357 kernel crash dumps.