bin/ps/ps.1

   1 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)ps.1        8.3 (Berkeley) 4/18/94
  33 .\" $FreeBSD: src/bin/ps/ps.1,v 1.24.2.7 2002/06/20 22:43:33 charnier Exp $
  34 .\" $DragonFly: src/bin/ps/ps.1,v 1.20 2008/09/02 11:50:45 matthias Exp $
  35 .\"
  36 .Dd September 2, 2008
  37 .Dt PS 1
  38 .Os
  39 .Sh NAME
  40 .Nm ps
  41 .Nd process status
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl aCcefHhjlmrSTuvwx
  45 .Op Fl M Ar core
  46 .Op Fl N Ar system
  47 .Op Fl O Ar fmt
  48 .Op Fl o Ar fmt
  49 .Op Fl p Ar pid
  50 .Op Fl t Ar tty
  51 .Op Fl U Ar username
  52 .Nm
  53 .Op Fl L
  54 .Sh DESCRIPTION
  55 The
  56 .Nm
  57 utility
  58 displays a header line followed by lines containing information about your
  59 processes that have controlling terminals.
  60 This information is sorted by controlling terminal, then by process ID.
  61 .Pp
  62 The information displayed is selected based on a set of keywords (see the
  63 .Fl L
  64 .Fl O
  65 and
  66 .Fl o
  67 options).
  68 The default output format includes, for each process, the process' ID,
  69 controlling terminal, CPU time (including both user and system time),
  70 state, and associated command.
  71 .Pp
  72 The process file system (see
  73 .Xr procfs 5 )
  74 should be mounted when
  75 .Nm
  76 is executed, otherwise not all information will be available.
  77 .Pp
  78 The options are as follows:
  79 .Bl -tag -width indent
  80 .It Fl a
  81 Display information about other users' processes as well as your own.
  82 This can be disabled by setting the
  83 .Va security.ps_showallprocs
  84 sysctl to zero.
  85 .It Fl c
  86 Change the ``command'' column output to just contain the executable name,
  87 rather than the full command line.
  88 .It Fl C
  89 Change the way the CPU percentage is calculated by using a ``raw''
  90 CPU calculation that ignores ``resident'' time (this normally has
  91 no effect).
  92 .It Fl e
  93 Display the environment as well.
  94 .It Fl f
  95 Show commandline and environment information about swapped out processes.
  96 This option is honored only if the uid of the user is 0.
  97 .It Fl H
  98 Print one line per lightweight process (LWP) instead of one line per process.
  99 When this option is set and the
 100 .Fl o
 101 option is not set, the
 102 .Cm tid
 103 column is inserted in the output format after the
 104 .Cm pid
 105 one.
 106 .It Fl h
 107 Repeat the information header as often as necessary to guarantee one
 108 header per page of information.
 109 .It Fl j
 110 Print information associated with the following keywords:
 111 .Cm user , pid , ppid , pgid , sess , jobc , state , tt , time ,
 112 and
 113 .Cm command .
 114 .It Fl L
 115 List the set of available keywords.
 116 .It Fl l
 117 Display information associated with the following keywords:
 118 .Cm uid , pid , ppid , cpu , pri , nice , vsz , rss , wchan , state ,
 119 .Cm tt , time ,
 120 and
 121 .Cm command .
 122 .It Fl M
 123 Extract values associated with the name list from the specified core
 124 instead of the default
 125 .Pa /dev/kmem .
 126 .It Fl m
 127 Sort by memory usage, instead of by process ID.
 128 .It Fl N
 129 Extract the name list from the specified system instead of the default
 130 .Pa /boot/kernel .
 131 .It Fl O
 132 Add the information associated with the space or comma separated list
 133 of keywords specified, after the process ID,
 134 in the default information
 135 display.
 136 Keywords may be appended with an equals (``='') sign and a string.
 137 This causes the printed header to use the specified string instead of
 138 the standard header.
 139 .It Fl o
 140 Display information associated with the space or comma separated list
 141 of keywords specified.
 142 Keywords may be appended with an equals (``='') sign and a string.
 143 This causes the printed header to use the specified string instead of
 144 the standard header.
 145 .It Fl p
 146 Display information associated with the specified process ID.
 147 .It Fl r
 148 Sort by current CPU usage, instead of by process ID.
 149 .It Fl S
 150 Change the way the process time is calculated by summing all exited
 151 children to their parent process.
 152 .It Fl T
 153 Display information about processes attached to the device associated
 154 with the standard input.
 155 .It Fl t
 156 Display information about processes attached to the specified terminal
 157 device.
 158 .It Fl U
 159 Display the processes belonging to the specified
 160 .Ar username .
 161 .It Fl u
 162 Display information associated with the following keywords:
 163 .Cm user , pid, %cpu , %mem , vsz , rss , tt , state , start , time ,
 164 and
 165 .Cm command .
 166 The
 167 .Fl u
 168 option implies the
 169 .Fl r
 170 option.
 171 .It Fl v
 172 Display information associated with the following keywords:
 173 .Cm pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz ,
 174 .Cm %cpu , %mem
 175 and
 176 .Cm command .
 177 The
 178 .Fl v
 179 option implies the
 180 .Fl m
 181 option.
 182 .It Fl w
 183 Use 132 columns to display information, instead of the default which
 184 is your window size.
 185 If the
 186 .Fl w
 187 option is specified more than once,
 188 .Nm
 189 will use as many columns as necessary without regard for your window size.
 190 .It Fl x
 191 Display information about processes without controlling terminals.
 192 .El
 193 .Pp
 194 A complete list of the available keywords are listed below.
 195 Some of these keywords are further specified as follows:
 196 .Bl -tag -width ".Cm lstart"
 197 .It Cm %cpu
 198 The CPU utilization of the process; this is a decaying average over up to
 199 a minute of previous (real) time.
 200 Since the time base over which this is computed varies (since processes may
 201 be very young) it is possible for the sum of all
 202 .Cm %cpu
 203 fields to exceed 100%.
 204 .It Cm %mem
 205 The percentage of real memory used by this process.
 206 .It Cm flags
 207 The flags associated with the process as in
 208 the include file
 209 .In sys/proc.h .
 210 .It Cm lim
 211 The soft limit on memory used, specified via a call to
 212 .Xr setrlimit 2 .
 213 .It Cm lstart
 214 The exact time the command started, using the ``%c'' format described in
 215 .Xr strftime 3 .
 216 .It Cm nice
 217 The process scheduling increment (see
 218 .Xr setpriority 2 ) .
 219 .It Cm rss
 220 the real memory (resident set) size of the process (in 1024 byte units).
 221 .It Cm start
 222 The time the command started.
 223 If the command started less than 24 hours ago, the start time is
 224 displayed using the ``%l:ps.1p'' format described in
 225 .Xr strftime 3 .
 226 If the command started less than 7 days ago, the start time is
 227 displayed using the ``%a6.15p'' format.
 228 Otherwise, the start time is displayed using the ``%e%b%y'' format.
 229 .It Cm state
 230 The state is given by a sequence of letters, for example,
 231 .Dq Li RWNA .
 232 The first letter indicates the run state of the process:
 233 .Pp
 234 .Bl -tag -width indent -compact
 235 .It Li B
 236 Marks a blocked kernel thread.
 237 .It Li D
 238 Marks a process in disk (or other short term, uninterruptible) wait.
 239 .It Li I
 240 Marks a process that is idle (sleeping for longer than about 20 seconds).
 241 .It Li J
 242 Marks a process which is in
 243 .Xr jail 2 .
 244 The hostname of the prison can be found in
 245 .Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status .
 246 .It Li R
 247 Marks a runnable process and is followed by the CPU number.
 248 .It Li S
 249 Marks a process that is sleeping for less than about 20 seconds.
 250 .It Li T
 251 Marks a stopped process.
 252 .It Li Z
 253 Marks a dead process (a
 254 .Dq zombie ) .
 255 .El
 256 .Pp
 257 Additional characters after these, if any, indicate additional state
 258 information:
 259 .Pp
 260 .Bl -tag -width indent -compact
 261 .It Li +
 262 The process is in the foreground process group of its control terminal.
 263 .It Li <
 264 The process has raised CPU scheduling priority.
 265 .It Li >
 266 The process has specified a soft limit on memory requirements and is
 267 currently exceeding that limit; such a process is (necessarily) not
 268 swapped.
 269 .It Li A
 270 the process has asked for random page replacement
 271 .Pf ( Dv MADV_RANDOM ,
 272 from
 273 .Xr madvise 2 ,
 274 for example,
 275 .Xr lisp 1
 276 in a garbage collect).
 277 .It Li E
 278 The process is trying to exit.
 279 .It Li L
 280 The process has pages locked in core (for example, for raw
 281 .Tn I/O ) .
 282 .It Li M
 283 On SMP systems indicates a process or thread which is
 284 .Em not
 285 holding the MP lock (the Big Giant Lock).
 286 .It Li N
 287 The process has reduced CPU scheduling priority (see
 288 .Xr setpriority 2 ) .
 289 .It Li S
 290 The process has asked for FIFO page replacement
 291 .Pf ( Dv MADV_SEQUENTIAL ,
 292 from
 293 .Xr madvise 2 ,
 294 for example, a large image processing program using virtual memory to
 295 sequentially address voluminous data).
 296 .It Li s
 297 The process is a session leader.
 298 .It Li V
 299 The process is suspended during a
 300 .Xr vfork 2 .
 301 .It Li W
 302 The process is swapped out.
 303 .It Li X
 304 The process is being traced or debugged.
 305 .El
 306 .It Cm tt
 307 An abbreviation for the pathname of the controlling terminal, if any.
 308 The abbreviation consists of the three letters following
 309 .Pa /dev/tty ,
 310 or, for the console, ``con''.
 311 This is followed by a ``-'' if the process can no longer reach that
 312 controlling terminal (i.e., it has been revoked).
 313 .It Cm wchan
 314 The event (an address in the system) on which a process waits.
 315 When printed numerically, the initial part of the address is
 316 trimmed off and the result is printed in hex, for example, 0x80324000 prints
 317 as 324000.  Note that blocked threads often only have ascii wchan's.
 318 .El
 319 .Pp
 320 When printing using the
 321 .Cm command
 322 keyword, a process that has exited and
 323 has a parent that has not yet waited for the process (in other words, a zombie)
 324 is listed as ``<defunct>'', and a process which is blocked while trying
 325 to exit is listed as ``<exiting>''.
 326 The
 327 .Nm
 328 utility
 329 makes an educated guess as to the file name and arguments given when the
 330 process was created by examining memory or the swap area.
 331 The method is inherently somewhat unreliable and in any event a process
 332 is entitled to destroy this information, so the names cannot be depended
 333 on too much.
 334 The
 335 .Cm ucomm
 336 (accounting) keyword can, however, be depended on.
 337 .Sh KEYWORDS
 338 The following is a complete list of the available keywords and their
 339 meanings.
 340 Several of them have aliases (keywords which are synonyms).
 341 .Pp
 342 .Bl -tag -width ".Cm sigignore" -compact
 343 .It Cm %cpu
 344 percentage CPU usage (alias
 345 .Cm pcpu )
 346 .It Cm %mem
 347 percentage memory usage (alias
 348 .Cm pmem )
 349 .It Cm acflag
 350 accounting flag (alias
 351 .Cm acflg )
 352 .It Cm batch
 353 batchness of the process (higher numbers mean less interactivity)
 354 .It Cm command
 355 command and arguments
 356 .It Cm cpu
 357 short-term CPU usage factor (for scheduling)
 358 .It Cm f
 359 the process flags, in hexadecimal (alias
 360 .Cm flags )
 361 .It Cm inblk
 362 total blocks read (alias
 363 .Cm inblock )
 364 .It Cm jail
 365 jail ID
 366 .It Cm jobc
 367 job control count
 368 .It Cm ktrace
 369 tracing flags
 370 .\" .It Cm ktracep
 371 .\" tracing vnode
 372 .It Cm lastcpu
 373 CPU ID the process was last scheduled on
 374 .It Cm lim
 375 memoryuse limit
 376 .It Cm login
 377 login name of user who started the process (alias
 378 .Cm logname )
 379 .It Cm lstart
 380 time started
 381 .It Cm majflt
 382 total page faults
 383 .It Cm minflt
 384 total page reclaims
 385 .It Cm msgrcv
 386 total messages received (reads from pipes/sockets)
 387 .It Cm msgsnd
 388 total messages sent (writes on pipes/sockets)
 389 .It Cm nice
 390 nice value (alias
 391 .Cm ni )
 392 .It Cm nivcsw
 393 total involuntary context switches
 394 .It Cm nlwp
 395 number of lightweight processes
 396 .It Cm nsigs
 397 total signals taken (alias
 398 .Cm nsignals )
 399 .It Cm nswap
 400 total swaps in/out
 401 .It Cm nvcsw
 402 total voluntary context switches
 403 .It Cm nwchan
 404 wait channel (as an address)
 405 .It Cm oublk
 406 total blocks written (alias
 407 .Cm oublock )
 408 .It Cm p_ru
 409 resource usage (valid only for zombie)
 410 .It Cm paddr
 411 swap address
 412 .It Cm pagein
 413 pageins (same as
 414 .Cm majflt )
 415 .It Cm pgid
 416 process group number
 417 .It Cm pid
 418 process ID
 419 .It Cm ppid
 420 parent process ID
 421 .It Cm pri
 422 scheduling priority (lower == better)
 423 .It Cm re
 424 core residency time (in seconds; 127 = infinity)
 425 .It Cm rgid
 426 real group ID
 427 .\" .It Cm rlink
 428 .\" reverse link on run queue, or 0
 429 .It Cm rss
 430 resident set size
 431 .It Cm rsz
 432 resident set size + (text size / text use count) (alias
 433 .Cm rssize )
 434 .It Cm rtprio
 435 realtime priority (101 = not a realtime process)
 436 .It Cm ruid
 437 real user ID
 438 .It Cm ruser
 439 user name (from ruid)
 440 .It Cm sess
 441 session pointer
 442 .It Cm sig
 443 pending signals (alias
 444 .Cm pending )
 445 .It Cm sigcatch
 446 caught signals (alias
 447 .Cm caught )
 448 .It Cm sigignore
 449 ignored signals (alias
 450 .Cm ignored )
 451 .It Cm sigmask
 452 blocked signals (alias
 453 .Cm blocked )
 454 .It Cm sl
 455 sleep time (in seconds; 127 = infinity)
 456 .It Cm start
 457 time started
 458 .It Cm state
 459 symbolic process state (alias
 460 .Cm stat )
 461 .It Cm svgid
 462 saved gid from a setgid executable
 463 .It Cm svuid
 464 saved uid from a setuid executable
 465 .It Cm tdev
 466 control terminal device number
 467 .It Cm tdpri
 468 LWKT thread priority (0-31, 31 highest), and critical section count
 469 .It Cm tid
 470 thread ID (aka lightweight process ID)
 471 .It Cm time
 472 accumulated CPU time, user + system (alias
 473 .Cm cputime )
 474 .It Cm tpgid
 475 control terminal process group ID
 476 .\".It Cm trss
 477 .\"text resident set size (in Kbytes)
 478 .It Cm tsess
 479 control terminal session pointer
 480 .It Cm tsig
 481 pending thread signals
 482 .It Cm tsiz
 483 text size (in Kbytes)
 484 .It Cm tt
 485 control terminal name (two letter abbreviation)
 486 .It Cm tty
 487 full name of control terminal
 488 .It Cm ucomm
 489 name to be used for accounting
 490 .It Cm uid
 491 effective user ID
 492 .It Cm user
 493 user name (from uid)
 494 .It Cm vsz
 495 virtual size in Kbytes (alias
 496 .Cm vsize )
 497 .It Cm wchan
 498 wait channel (as a symbolic name)
 499 .It Cm xstat
 500 exit or stop status (valid only for stopped or zombie process)
 501 .El
 502 .Sh FILES
 503 .Bl -tag -width /var/db/kvm_kernel.db -compact
 504 .It Pa /dev/kmem
 505 default kernel memory
 506 .It Pa /var/run/dev.db
 507 /dev name database
 508 .It Pa /var/db/kvm_kernel.db
 509 system namelist database
 510 .It Pa /boot/kernel
 511 default system namelist
 512 .It Pa /proc
 513 the mount point of
 514 .Xr procfs 5
 515 .El
 516 .Sh SEE ALSO
 517 .Xr kill 1 ,
 518 .Xr w 1 ,
 519 .Xr kvm 3 ,
 520 .Xr strftime 3 ,
 521 .Xr procfs 5 ,
 522 .Xr pstat 8 ,
 523 .Xr sysctl 8
 524 .Sh HISTORY
 525 The
 526 .Nm
 527 command appeared in
 528 .At v4 .
 529 .Sh BUGS
 530 Since
 531 .Nm
 532 cannot run faster than the system and is run as any other scheduled
 533 process, the information it displays can never be exact.