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 e
 150 POSIX semaphore
 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 d
 179 directory
 180 .It f
 181 fifo
 182 .It l
 183 symbolic link
 184 .It r
 185 regular file
 186 .It s
 187 socket
 188 .It x
 189 revoked device
 190 .El
 191 .Pp
 192 The following file descriptor flags may be displayed:
 193 .Pp
 194 .Bl -tag -width X -compact
 195 .It r
 196 read
 197 .It w
 198 write
 199 .It a
 200 append
 201 .It s
 202 async
 203 .It f
 204 fsync
 205 .It n
 206 non-blocking
 207 .It d
 208 direct I/O
 209 .It l
 210 lock held
 211 .El
 212 .Ss Signal Disposition Information
 213 Display signal pending and disposition for a process:
 214 .Pp
 215 .Bl -tag -width ident -compact
 216 .It PID
 217 process ID
 218 .It COMM
 219 command
 220 .It SIG
 221 signal name
 222 .It FLAGS
 223 process signal disposition details, three symbols
 224 .Bl -tag -width X -compact
 225 .It P
 226 if signal is pending in the global process queue, - otherwise
 227 .It I
 228 if signal delivery disposition is SIGIGN, - otherwise
 229 .It C
 230 if signal delivery is to catch it, - otherwise
 231 .El
 232 .El
 233 .Pp
 234 If
 235 .Fl n
 236 switch is given, the signal numbers are shown instead of signal names.
 237 .Ss Thread Signal Information
 238 Display signal pending and blocked for a process threads:
 239 .Pp
 240 .Bl -tag -width ident -compact
 241 .It PID
 242 process ID
 243 .It COMM
 244 command
 245 .It TID
 246 thread ID
 247 .It SIG
 248 signal name
 249 .It FLAGS
 250 thread signal delivery status, two symbols
 251 .Bl -tag -width X -compact
 252 .It P
 253 if signal is pending for the thread, - otherwise
 254 .It B
 255 if signal is blocked in the thread signal mask, - if not blocked
 256 .El
 257 .El
 258 .Pp
 259 The
 260 .Fl n
 261 switch has the same effect as for the
 262 .Fl i
 263 switch, the signals numbers are shown instead of signal names.
 264 .Ss Kernel Thread Stacks
 265 Display kernel thread stacks for a process, allowing further interpretation
 266 of thread wait channels.
 267 If the
 268 .Fl k
 269 flag is repeated, function offsets, not just function names, are printed.
 270 .Pp
 271 This feature requires
 272 .Cd "options STACK"
 273 or
 274 .Cd "options DDB"
 275 to be compiled into the kernel.
 276 .Pp
 277 .Bl -tag -width indent -compact
 278 .It PID
 279 process ID
 280 .It TID
 281 thread ID
 282 .It COMM
 283 command
 284 .It TDNAME
 285 thread name
 286 .It KSTACK
 287 kernel thread call stack
 288 .El
 289 .Ss Security Credentials
 290 Display process credential information:
 291 .Pp
 292 .Bl -tag -width indent -compact
 293 .It PID
 294 process ID
 295 .It COMM
 296 command
 297 .It EUID
 298 effective user ID
 299 .It RUID
 300 real user ID
 301 .It SVUID
 302 saved user ID
 303 .It EGID
 304 effective group ID
 305 .It RGID
 306 real group ID
 307 .It SVGID
 308 saved group ID
 309 .It GROUPS
 310 group set
 311 .El
 312 .Ss Thread Information
 313 Display per-thread information, including process ID, per-thread ID, name,
 314 CPU, and execution state:
 315 .Pp
 316 .Bl -tag -width indent -compact
 317 .It PID
 318 process ID
 319 .It TID
 320 thread ID
 321 .It COMM
 322 command
 323 .It TDNAME
 324 thread name
 325 .It CPU
 326 current or most recent CPU run on
 327 .It PRI
 328 thread priority
 329 .It STATE
 330 thread state
 331 .It WCHAN
 332 thread wait channel
 333 .El
 334 .Ss Virtual Memory Mappings
 335 Display process virtual memory mappings, including addresses, mapping
 336 meta-data, and mapped object information:
 337 .Pp
 338 .Bl -tag -width indent -compact
 339 .It PID
 340 process ID
 341 .It START
 342 starting address of mapping
 343 .It END
 344 ending address of mapping
 345 .It PRT
 346 protection flags
 347 .It RES
 348 resident pages
 349 .It PRES
 350 private resident pages
 351 .It REF
 352 reference count
 353 .It SHD
 354 shadow page count
 355 .It FL
 356 mapping flags
 357 .It TP
 358 VM object type
 359 .El
 360 .Pp
 361 The following protection flags may be displayed:
 362 .Pp
 363 .Bl -tag -width X -compact
 364 .It r
 365 read
 366 .It w
 367 write
 368 .It x
 369 execute
 370 .El
 371 .Pp
 372 The following VM object types may be displayed:
 373 .Pp
 374 .Bl -tag -width XX -compact
 375 .It --
 376 none
 377 .It dd
 378 dead
 379 .It df
 380 default
 381 .It dv
 382 device
 383 .It ph
 384 physical
 385 .It sw
 386 swap
 387 .It vn
 388 vnode
 389 .El
 390 .Pp
 391 The following mapping flags may be displayed:
 392 .Pp
 393 .Bl -tag -width X -compact
 394 .It C
 395 copy-on-write
 396 .It N
 397 needs copy
 398 .El
 399 .Sh EXIT STATUS
 400 .Ex -std
 401 .Sh SEE ALSO
 402 .Xr fstat 1 ,
 403 .Xr ps 1 ,
 404 .Xr sockstat 1 ,
 405 .Xr ddb 4 ,
 406 .Xr stack 9
 407 .Sh AUTHORS
 408 .An Robert N M Watson
 409 .Sh BUGS
 410 Some field values may include spaces, which limits the extent to which the
 411 output of
 412 .Nm
 413 may be mechanically parsed.
 414 .Pp
 415 The display of open file or memory mapping pathnames is implemented using the
 416 kernel's name cache.
 417 If a file system does not use the name cache, or the path to a file is not in
 418 the cache, a path will not be displayed.
 419 .Pp
 420 .Nm
 421 currently supports extracting data only from a live kernel, and not from
 422 kernel crash dumps.