| 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 aCcefHhjlmrRSTuvwx |
| 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 R |
| 150 | Subsort by parent/child chain. This very useful option makes |
| 151 | the parent/child associations clear and understandable. |
| 152 | .It Fl S |
| 153 | Change the way the process time is calculated by summing all exited |
| 154 | children to their parent process. |
| 155 | .It Fl T |
| 156 | Display information about processes attached to the device associated |
| 157 | with the standard input. |
| 158 | .It Fl t |
| 159 | Display information about processes attached to the specified terminal |
| 160 | device. |
| 161 | .It Fl U |
| 162 | Display the processes belonging to the specified |
| 163 | .Ar username . |
| 164 | .It Fl u |
| 165 | Display information associated with the following keywords: |
| 166 | .Cm user , pid, %cpu , %mem , vsz , rss , tt , state , start , time , |
| 167 | and |
| 168 | .Cm command . |
| 169 | The |
| 170 | .Fl u |
| 171 | option implies the |
| 172 | .Fl r |
| 173 | option. |
| 174 | .It Fl v |
| 175 | Display information associated with the following keywords: |
| 176 | .Cm pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz , |
| 177 | .Cm %cpu , %mem |
| 178 | and |
| 179 | .Cm command . |
| 180 | The |
| 181 | .Fl v |
| 182 | option implies the |
| 183 | .Fl m |
| 184 | option. |
| 185 | .It Fl w |
| 186 | Use 132 columns to display information, instead of the default which |
| 187 | is your window size. |
| 188 | If the |
| 189 | .Fl w |
| 190 | option is specified more than once, |
| 191 | .Nm |
| 192 | will use as many columns as necessary without regard for your window size. |
| 193 | .It Fl x |
| 194 | Display information about processes without controlling terminals. |
| 195 | .El |
| 196 | .Pp |
| 197 | A complete list of the available keywords are listed below. |
| 198 | Some of these keywords are further specified as follows: |
| 199 | .Bl -tag -width ".Cm lstart" |
| 200 | .It Cm %cpu |
| 201 | The CPU utilization of the process; this is a decaying average over up to |
| 202 | a minute of previous (real) time. |
| 203 | Since the time base over which this is computed varies (since processes may |
| 204 | be very young) it is possible for the sum of all |
| 205 | .Cm %cpu |
| 206 | fields to exceed 100%. |
| 207 | .It Cm %mem |
| 208 | The percentage of real memory used by this process. |
| 209 | .It Cm flags |
| 210 | The flags associated with the process as in |
| 211 | the include file |
| 212 | .In sys/proc.h . |
| 213 | .It Cm lim |
| 214 | The soft limit on memory used, specified via a call to |
| 215 | .Xr setrlimit 2 . |
| 216 | .It Cm lstart |
| 217 | The exact time the command started, using the ``%c'' format described in |
| 218 | .Xr strftime 3 . |
| 219 | .It Cm nice |
| 220 | The process scheduling increment (see |
| 221 | .Xr setpriority 2 ) . |
| 222 | .It Cm rss |
| 223 | the real memory (resident set) size of the process (in 1024 byte units). |
| 224 | .It Cm start |
| 225 | The time the command started. |
| 226 | If the command started less than 24 hours ago, the start time is |
| 227 | displayed using the ``%l:ps.1p'' format described in |
| 228 | .Xr strftime 3 . |
| 229 | If the command started less than 7 days ago, the start time is |
| 230 | displayed using the ``%a6.15p'' format. |
| 231 | Otherwise, the start time is displayed using the ``%e%b%y'' format. |
| 232 | .It Cm state |
| 233 | The state is given by a sequence of letters, for example, |
| 234 | .Dq Li RWNA . |
| 235 | The first letter indicates the run state of the process: |
| 236 | .Pp |
| 237 | .Bl -tag -width indent -compact |
| 238 | .It Li B |
| 239 | Marks a blocked kernel thread. |
| 240 | .It Li D |
| 241 | Marks a process in disk (or other short term, uninterruptible) wait. |
| 242 | .It Li I |
| 243 | Marks a process that is idle (sleeping for longer than about 20 seconds). |
| 244 | .It Li J |
| 245 | Marks a process which is in |
| 246 | .Xr jail 2 . |
| 247 | The hostname of the prison can be found in |
| 248 | .Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status . |
| 249 | .It Li R |
| 250 | Marks a runnable process and is followed by the CPU number. |
| 251 | .It Li S |
| 252 | Marks a process that is sleeping for less than about 20 seconds. |
| 253 | .It Li T |
| 254 | Marks a stopped process. |
| 255 | .It Li Z |
| 256 | Marks a dead process (a |
| 257 | .Dq zombie ) . |
| 258 | .El |
| 259 | .Pp |
| 260 | Additional characters after these, if any, indicate additional state |
| 261 | information: |
| 262 | .Pp |
| 263 | .Bl -tag -width indent -compact |
| 264 | .It Li + |
| 265 | The process is in the foreground process group of its control terminal. |
| 266 | .It Li < |
| 267 | The process has raised CPU scheduling priority. |
| 268 | .It Li > |
| 269 | The process has specified a soft limit on memory requirements and is |
| 270 | currently exceeding that limit; such a process is (necessarily) not |
| 271 | swapped. |
| 272 | .It Li A |
| 273 | the process has asked for random page replacement |
| 274 | .Pf ( Dv MADV_RANDOM , |
| 275 | from |
| 276 | .Xr madvise 2 , |
| 277 | for example, |
| 278 | .Xr lisp 1 |
| 279 | in a garbage collect). |
| 280 | .It Li E |
| 281 | The process is trying to exit. |
| 282 | .It Li L |
| 283 | The process has pages locked in core (for example, for raw |
| 284 | .Tn I/O ) . |
| 285 | .It Li M |
| 286 | On SMP systems indicates a process or thread which is |
| 287 | .Em not |
| 288 | holding the MP lock (the Big Giant Lock). |
| 289 | .It Li N |
| 290 | The process has reduced CPU scheduling priority (see |
| 291 | .Xr setpriority 2 ) . |
| 292 | .It Li S |
| 293 | The process has asked for FIFO page replacement |
| 294 | .Pf ( Dv MADV_SEQUENTIAL , |
| 295 | from |
| 296 | .Xr madvise 2 , |
| 297 | for example, a large image processing program using virtual memory to |
| 298 | sequentially address voluminous data). |
| 299 | .It Li s |
| 300 | The process is a session leader. |
| 301 | .It Li V |
| 302 | The process is suspended during a |
| 303 | .Xr vfork 2 . |
| 304 | .It Li W |
| 305 | The process is swapped out. |
| 306 | .It Li X |
| 307 | The process is being traced or debugged. |
| 308 | .El |
| 309 | .It Cm tt |
| 310 | An abbreviation for the pathname of the controlling terminal, if any. |
| 311 | The abbreviation consists of the three letters following |
| 312 | .Pa /dev/tty , |
| 313 | or, for the console, ``con''. |
| 314 | This is followed by a ``-'' if the process can no longer reach that |
| 315 | controlling terminal (i.e., it has been revoked). |
| 316 | .It Cm wchan |
| 317 | The event (an address in the system) on which a process waits. |
| 318 | When printed numerically, the initial part of the address is |
| 319 | trimmed off and the result is printed in hex, for example, 0x80324000 prints |
| 320 | as 324000. Note that blocked threads often only have ascii wchan's. |
| 321 | .El |
| 322 | .Pp |
| 323 | When printing using the |
| 324 | .Cm command |
| 325 | keyword, a process that has exited and |
| 326 | has a parent that has not yet waited for the process (in other words, a zombie) |
| 327 | is listed as ``<defunct>'', and a process which is blocked while trying |
| 328 | to exit is listed as ``<exiting>''. |
| 329 | The |
| 330 | .Nm |
| 331 | utility |
| 332 | makes an educated guess as to the file name and arguments given when the |
| 333 | process was created by examining memory or the swap area. |
| 334 | The method is inherently somewhat unreliable and in any event a process |
| 335 | is entitled to destroy this information, so the names cannot be depended |
| 336 | on too much. |
| 337 | The |
| 338 | .Cm ucomm |
| 339 | (accounting) keyword can, however, be depended on. |
| 340 | .Sh KEYWORDS |
| 341 | The following is a complete list of the available keywords and their |
| 342 | meanings. |
| 343 | Several of them have aliases (keywords which are synonyms). |
| 344 | .Pp |
| 345 | .Bl -tag -width ".Cm sigignore" -compact |
| 346 | .It Cm %cpu |
| 347 | percentage CPU usage (alias |
| 348 | .Cm pcpu ) |
| 349 | .It Cm %mem |
| 350 | percentage memory usage (alias |
| 351 | .Cm pmem ) |
| 352 | .It Cm acflag |
| 353 | accounting flag (alias |
| 354 | .Cm acflg ) |
| 355 | .It Cm batch |
| 356 | batchness of the process (higher numbers mean less interactivity) |
| 357 | .It Cm command |
| 358 | command and arguments |
| 359 | .It Cm cpu |
| 360 | short-term CPU usage factor (for scheduling) |
| 361 | .It Cm f |
| 362 | the process flags, in hexadecimal (alias |
| 363 | .Cm flags ) |
| 364 | .It Cm inblk |
| 365 | total blocks read (alias |
| 366 | .Cm inblock ) |
| 367 | .It Cm jail |
| 368 | jail ID |
| 369 | .It Cm jobc |
| 370 | job control count |
| 371 | .It Cm ktrace |
| 372 | tracing flags |
| 373 | .\" .It Cm ktracep |
| 374 | .\" tracing vnode |
| 375 | .It Cm lastcpu |
| 376 | CPU ID the process was last scheduled on |
| 377 | .It Cm lim |
| 378 | memoryuse limit |
| 379 | .It Cm login |
| 380 | login name of user who started the process (alias |
| 381 | .Cm logname ) |
| 382 | .It Cm lstart |
| 383 | time started |
| 384 | .It Cm majflt |
| 385 | total page faults |
| 386 | .It Cm minflt |
| 387 | total page reclaims |
| 388 | .It Cm msgrcv |
| 389 | total messages received (reads from pipes/sockets) |
| 390 | .It Cm msgsnd |
| 391 | total messages sent (writes on pipes/sockets) |
| 392 | .It Cm nice |
| 393 | nice value (alias |
| 394 | .Cm ni ) |
| 395 | .It Cm nivcsw |
| 396 | total involuntary context switches |
| 397 | .It Cm nlwp |
| 398 | number of lightweight processes |
| 399 | .It Cm nsigs |
| 400 | total signals taken (alias |
| 401 | .Cm nsignals ) |
| 402 | .It Cm nswap |
| 403 | total swaps in/out |
| 404 | .It Cm nvcsw |
| 405 | total voluntary context switches |
| 406 | .It Cm nwchan |
| 407 | wait channel (as an address) |
| 408 | .It Cm oublk |
| 409 | total blocks written (alias |
| 410 | .Cm oublock ) |
| 411 | .It Cm p_ru |
| 412 | resource usage (valid only for zombie) |
| 413 | .It Cm paddr |
| 414 | swap address |
| 415 | .It Cm pagein |
| 416 | pageins (same as |
| 417 | .Cm majflt ) |
| 418 | .It Cm pgid |
| 419 | process group number |
| 420 | .It Cm pid |
| 421 | process ID |
| 422 | .It Cm ppid |
| 423 | parent process ID |
| 424 | .It Cm pri |
| 425 | scheduling priority (lower == better) |
| 426 | .It Cm re |
| 427 | core residency time (in seconds; 127 = infinity) |
| 428 | .It Cm rgid |
| 429 | real group ID |
| 430 | .\" .It Cm rlink |
| 431 | .\" reverse link on run queue, or 0 |
| 432 | .It Cm rss |
| 433 | resident set size |
| 434 | .It Cm rsz |
| 435 | resident set size + (text size / text use count) (alias |
| 436 | .Cm rssize ) |
| 437 | .It Cm rtprio |
| 438 | realtime priority (101 = not a realtime process) |
| 439 | .It Cm ruid |
| 440 | real user ID |
| 441 | .It Cm ruser |
| 442 | user name (from ruid) |
| 443 | .It Cm sess |
| 444 | session pointer |
| 445 | .It Cm sig |
| 446 | pending signals (alias |
| 447 | .Cm pending ) |
| 448 | .It Cm sigcatch |
| 449 | caught signals (alias |
| 450 | .Cm caught ) |
| 451 | .It Cm sigignore |
| 452 | ignored signals (alias |
| 453 | .Cm ignored ) |
| 454 | .It Cm sigmask |
| 455 | blocked signals (alias |
| 456 | .Cm blocked ) |
| 457 | .It Cm sl |
| 458 | sleep time (in seconds; 127 = infinity) |
| 459 | .It Cm start |
| 460 | time started |
| 461 | .It Cm state |
| 462 | symbolic process state (alias |
| 463 | .Cm stat ) |
| 464 | .It Cm svgid |
| 465 | saved gid from a setgid executable |
| 466 | .It Cm svuid |
| 467 | saved uid from a setuid executable |
| 468 | .It Cm tdev |
| 469 | control terminal device number |
| 470 | .It Cm tdpri |
| 471 | LWKT thread priority (0-31, 31 highest), and critical section count |
| 472 | .It Cm tid |
| 473 | thread ID (aka lightweight process ID) |
| 474 | .It Cm time |
| 475 | accumulated CPU time, user + system (alias |
| 476 | .Cm cputime ) |
| 477 | .It Cm tpgid |
| 478 | control terminal process group ID |
| 479 | .\".It Cm trss |
| 480 | .\"text resident set size (in Kbytes) |
| 481 | .It Cm tsess |
| 482 | control terminal session pointer |
| 483 | .It Cm tsig |
| 484 | pending thread signals |
| 485 | .It Cm tsiz |
| 486 | text size (in Kbytes) |
| 487 | .It Cm tt |
| 488 | control terminal name (two letter abbreviation) |
| 489 | .It Cm tty |
| 490 | full name of control terminal |
| 491 | .It Cm ucomm |
| 492 | name to be used for accounting (alias |
| 493 | .Cm comm ) |
| 494 | .It Cm uid |
| 495 | effective user ID |
| 496 | .It Cm user |
| 497 | user name (from uid) |
| 498 | .It Cm vsz |
| 499 | virtual size in Kbytes (alias |
| 500 | .Cm vsize ) |
| 501 | .It Cm wchan |
| 502 | wait channel (as a symbolic name) |
| 503 | .It Cm xstat |
| 504 | exit or stop status (valid only for stopped or zombie process) |
| 505 | .El |
| 506 | .Sh FILES |
| 507 | .Bl -tag -width /var/db/kvm_kernel.db -compact |
| 508 | .It Pa /dev/kmem |
| 509 | default kernel memory |
| 510 | .It Pa /var/run/dev.db |
| 511 | /dev name database |
| 512 | .It Pa /var/db/kvm_kernel.db |
| 513 | system namelist database |
| 514 | .It Pa /boot/kernel |
| 515 | default system namelist |
| 516 | .It Pa /proc |
| 517 | the mount point of |
| 518 | .Xr procfs 5 |
| 519 | .El |
| 520 | .Sh SEE ALSO |
| 521 | .Xr kill 1 , |
| 522 | .Xr w 1 , |
| 523 | .Xr kvm 3 , |
| 524 | .Xr strftime 3 , |
| 525 | .Xr procfs 5 , |
| 526 | .Xr pstat 8 , |
| 527 | .Xr sysctl 8 |
| 528 | .Sh HISTORY |
| 529 | The |
| 530 | .Nm |
| 531 | command appeared in |
| 532 | .At v4 . |
| 533 | .Sh BUGS |
| 534 | Since |
| 535 | .Nm |
| 536 | cannot run faster than the system and is run as any other scheduled |
| 537 | process, the information it displays can never be exact. |