usr.bin/procstat/procstat.1

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