| blob | 46a6dbfede8c7db30f250cfbee378547674a0dc2 |
1 .\" $NetBSD: ps.1,v 1.103 2014/01/15 09:24:31 wiz Exp $
2 .\"
3 .\" Copyright (c) 1980, 1990, 1991, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)ps.1 8.3 (Berkeley) 4/18/94
31 .\"
32 .Dd January 15, 2014
33 .Dt PS 1
34 .Os
35 .Sh NAME
36 .Nm ps
37 .Nd process status
38 .Sh SYNOPSIS
39 .Nm
40 .Op Fl AaCcehjlmrSsTuvwx
41 .Op Fl k Ar key
42 .Op Fl M Ar core
43 .Op Fl N Ar system
44 .Op Fl O Ar fmt
45 .Op Fl o Ar fmt
46 .Op Fl p Ar pid
47 .Op Fl t Ar tty
48 .Op Fl U Ar user
49 .Op Fl W Ar swap
50 .Nm
51 .Fl L
52 .Sh DESCRIPTION
53 .Nm
54 displays a header line followed by lines containing information about
55 running processes.
56 By default, the display includes only processes that have
57 controlling terminals and are owned by your uid.
58 The default sort order of controlling terminal and
59 (among processes with the same controlling terminal) process
60 .Tn ID
61 may be changed using the
62 .Fl k , Fl m ,
63 or
64 .Fl r
65 options.
66 .Pp
67 The information displayed for each process
68 is selected based on a set of keywords (see the
69 .Fl L ,
70 .Fl O ,
71 and
72 .Fl o
73 options).
74 The default output format includes, for each process, the process'
75 .Tn ID ,
76 controlling terminal, CPU time (including both user and system time),
77 state, and associated command.
78 .Pp
79 The options are as follows:
80 .Bl -tag -width XNXsystemXX
81 .It Fl A
82 Display information about all processes.
83 This is equivalent to
84 .Fl a Fl x .
85 .It Fl a
86 Display information about other users' processes as well as your own.
87 Note that this does not display information about processes
88 without controlling terminals.
89 .It Fl C
90 Change the way the CPU percentage is calculated by using a
91 .Dq raw
92 CPU calculation that ignores
93 .Dq resident
94 time (this normally has no effect).
95 .It Fl c
96 Do not display full command with arguments, but only the
97 executable name.
98 This may be somewhat confusing; for example, all
99 .Xr sh 1
100 scripts will show as
101 .Dq sh .
102 .It Fl e
103 Display the environment as well.
104 The environment for other
105 users' processes can only be displayed by the super-user.
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 .Ar user , pid , ppid , pgid , sess , jobc , state , tt , time ,
112 and
113 .Ar command .
114 .It Fl k Ar key
115 Sort the output using the space or comma separated list of keywords.
116 Multiple sort keys may be specified, using any of the
117 .Fl k , Fl m ,
118 or
119 .Fl r
120 options.
121 The default sort order is equivalent to
122 .Fl k Ar tdev,pid .
123 .It Fl L
124 List the set of available keywords.
125 .It Fl l
126 Display information associated with the following keywords:
127 .Ar uid , pid , ppid , cpu , pri , nice , vsz , rss , wchan , state ,
128 .Ar tt , time ,
129 and
130 .Ar command .
131 .It Fl M Ar core
132 Extract values from the specified core file instead of the running system.
133 .It Fl m
134 Sort by memory usage.
135 This is equivalent to
136 .Fl k Ar vsz .
137 .It Fl N Ar system
138 Extract the name list from the specified system instead of the default,
139 .Dq Pa /netbsd .
140 Ignored unless
141 .Fl M
142 is specified.
143 .It Fl O Ar fmt
144 Display information associated with the space or comma separated list
145 of keywords specified.
146 The
147 .Fl O
148 option does not suppress the default display;
149 it inserts additional keywords just after the
150 .Ar pid
151 keyword in the default display, or after the
152 .Ar pid
153 keyword (if any) in a non-default display specified before the
154 first use of the
155 .Fl O
156 flag.
157 Keywords inserted by multiple
158 .Fl O
159 options will be adjacent.
160 .Pp
161 An equals sign
162 .Pq Dq \&=
163 followed by a customised header string may be appended to a keyword,
164 as described in more detail under the
165 .Fl o
166 option.
167 .It Fl o Ar fmt
168 Display information associated with the space or comma separated list
169 of keywords specified.
170 Use of the
171 .Fl o
172 option suppresses the set of keywords that would be displayed by default,
173 or appends to the set of keywords specified by other options.
174 .Pp
175 An equals sign
176 .Pq Dq \&=
177 followed by a customised header string may be appended to a keyword.
178 This causes the printed header to use the specified string instead of
179 the default header associated with the keyword.
180 .Pp
181 Everything after the first equals sign is part of the customised
182 header text, and this may include embedded spaces
183 .Pq Dq " " ,
184 commas
185 .Pq Dq \&, ,
186 or equals signs
187 .Pq Dq \&= .
188 To specify multiple keywords with customised headers, use multiple
189 .Fl o
190 or
191 .Fl O
192 options.
193 .Pp
194 If all the keywords to be displayed have customised headers,
195 and all the customised headers are entirely empty,
196 then the header line is not printed at all.
197 .It Fl p Ar pid
198 Display information associated with the specified process
199 .Tn ID .
200 .It Fl r
201 Sort by current CPU usage.
202 This is equivalent to
203 .Fl k Ar %cpu .
204 .It Fl S
205 Change the way the process time is calculated by summing all exited
206 children to their parent process.
207 .It Fl s
208 Display one line for each LWP, rather than one line for each process,
209 and display information associated with the following keywords:
210 .Ar uid , pid , ppid , cpu , lid , nlwp , pri , nice , vsz , rss ,
211 .Ar wchan , lstate , tt , time ,
212 and
213 .Ar command .
214 .It Fl T
215 Display information about processes attached to the device associated
216 with the standard input.
217 .It Fl t Ar tty
218 Display information about processes attached to the specified terminal
219 device.
220 Use a question mark
221 .Pq Dq \&?
222 for processes not attached to a
223 terminal device and a minus sign
224 .Pq Dq -
225 for processes that have
226 been revoked from their terminal device.
227 .It Fl U Ar user
228 Display processes belonging to the specified user,
229 given either as a user name or a uid.
230 .It Fl u
231 Display information associated with the following keywords:
232 .Ar user , pid , %cpu , %mem , vsz , rss , tt , state , start , time ,
233 and
234 .Ar command .
235 The
236 .Fl u
237 option implies the
238 .Fl r
239 option.
240 .It Fl v
241 Display information associated with the following keywords:
242 .Ar pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz ,
243 .Ar %cpu , %mem ,
244 and
245 .Ar command .
246 The
247 .Fl v
248 option implies the
249 .Fl m
250 option.
251 .It Fl W Ar swap
252 Extract swap information from the specified file instead of the default,
253 .Dq Pa /dev/drum .
254 Ignored unless
255 .Fl M
256 is specified.
257 .It Fl w
258 Use 132 columns to display information instead of the default, which
259 is your window size.
260 If the
261 .Fl w
262 option is specified more than once,
263 .Nm
264 will use as many columns as necessary without regard to your window size.
265 .It Fl x
266 Also display information about processes without controlling terminals.
267 .El
268 .Pp
269 A complete list of the available keywords are listed below.
270 Some of these keywords are further specified as follows:
271 .Bl -tag -width indent
272 .It Ar %cpu
273 The CPU utilization of the process; this is a decaying average over up to
274 a minute of previous (real) time.
275 Since the time base over which this is computed varies (since processes may
276 be very young) it is possible for the sum of all
277 .Tn %CPU
278 fields to exceed 100%.
279 .It Ar %mem
280 The percentage of real memory used by this process.
281 .It Ar flags
282 The flags (in hexadecimal) associated with the process as in
283 the include file
284 .In sys/proc.h :
285 .Bl -column P_NOCLDSTOP P_NOCLDSTOP compact
286 .It Dv "P_ADVLOCK" Ta No "0x00000001 process may hold a POSIX advisory lock"
287 .It Dv "P_CONTROLT" Ta No "0x00000002 process has a controlling terminal"
288 .It Dv "P_NOCLDSTOP" Ta No "0x00000008 no" Dv SIGCHLD No when children stop
289 .It Dv "P_PPWAIT" Ta No "0x00000010 parent is waiting for child to exec/exit"
290 .It Dv "P_PROFIL" Ta No "0x00000020 process has started profiling"
291 .It Dv "P_SELECT" Ta No "0x00000040 selecting; wakeup/waiting danger"
292 .It Dv "P_SINTR" Ta No "0x00000080 sleep is interruptible"
293 .It Dv "P_SUGID" Ta No "0x00000100 process had set id privileges since last exec"
294 .It Dv "P_SYSTEM" Ta No "0x00000200 system process: no sigs or stats"
295 .It Dv "P_TIMEOUT" Ta No "0x00000400 timing out during sleep"
296 .It Dv "P_TRACED" Ta No "0x00000800 process is being traced"
297 .It Dv "P_WAITED" Ta No "0x00001000 debugging process has waited for child"
298 .It Dv "P_WEXIT" Ta No "0x00002000 working on exiting"
299 .It Dv "P_EXEC" Ta No "0x00004000 process called" Xr execve 2
300 .It Dv "P_OWEUPC" Ta No "0x00008000 owe process an addupc() call at next ast"
301 .\" the routine addupc is not documented in the man pages
302 .It Dv "P_FSTRACE" Ta No "0x00010000 tracing via file system"
303 .It Dv "P_NOCLDWAIT" Ta No "0x00020000 no zombies when children die"
304 .It Dv "P_32" Ta No "0x00040000 32-bit process (used on 64-bit kernels)"
305 .It Dv "P_BIGLOCK" Ta No "0x00080000 process needs kernel ``big lock'' to run"
306 .It Dv "P_INEXEC" Ta No "0x00100000 process is exec'ing and cannot be traced"
307 .El
308 .It Ar lim
309 The soft limit on memory used, specified via a call to
310 .Xr setrlimit 2 .
311 .It Ar lstart
312 The exact time the command started, using the
313 .Dq \&%c
314 format described in
315 .Xr strftime 3 .
316 .It Ar nice
317 The process scheduling increment (see
318 .Xr setpriority 2 ) .
319 .It Ar rss
320 the real memory (resident set) size of the process (in 1024 byte units).
321 .It Ar start
322 The time the command started.
323 If the command started less than 24 hours ago, the start time is
324 displayed using the
325 .Dq %l:%M%p
326 format described in
327 .Xr strftime 3 .
328 If the command started less than 7 days ago, the start time is
329 displayed using the
330 .Dq %a%p
331 format.
332 Otherwise, the start time is displayed using the
333 .Dq %e%b%y
334 format.
335 .It Ar state
336 The state is given by a sequence of letters, for example,
337 .Dq Tn RNs .
338 The first letter indicates the run state of the process:
339 .Pp
340 .Bl -tag -width indent -compact
341 .It D
342 Marks a process in device or other short term, uninterruptible wait.
343 .It I
344 Marks a process that is idle (sleeping interruptibly for longer than about
345 .Dv MAXSLP
346 (default 20) seconds).
347 .It O
348 Marks a process running on a processor.
349 .It R
350 Marks a runnable process, or one that is in the process of creation.
351 .It S
352 Marks a process that is sleeping interruptibly for less than about
353 .Dv MAXSLP
354 (default 20) seconds.
355 .It T
356 Marks a stopped process.
357 .It U
358 Marks a suspended process.
359 .It Z
360 Marks a dead process that has exited, but not been waited for (a
361 .Dq zombie ) .
362 .El
363 .Pp
364 Additional characters after these, if any, indicate additional state
365 information:
366 .Pp
367 .Bl -tag -width indent -compact
368 .It +
369 The process is in the foreground process group of its control terminal.
370 .It -
371 The LWP is detached (can't be waited for).
372 .It \*[Lt]
373 The process has raised
374 .Tn CPU
375 scheduling priority.
376 .It a
377 The process is using scheduler activations (deprecated).
378 .It E
379 The process is in the process of exiting.
380 .It K
381 The process is a kernel thread or system process.
382 .It l
383 The process has multiple LWPs.
384 .It N
385 The process is niced (has reduced
386 .Tn CPU
387 scheduling priority) (see
388 .Xr setpriority 2 ) .
389 .It s
390 The process is a session leader.
391 .It V
392 The process is suspended during a
393 .Xr vfork 2 .
394 .It X
395 The process is being traced or debugged.
396 .El
397 .It Ar tt
398 An abbreviation for the pathname of the controlling terminal, if any.
399 The abbreviation consists of the two letters following
400 .Dq Pa /dev/tty
401 or, for the console,
402 .Dq co .
403 This is followed by a
404 .Dq \&-
405 if the process can no longer reach that
406 controlling terminal (i.e., it has been revoked).
407 .It Ar wchan
408 The event (an address in the system) on which a process waits.
409 When printed numerically, the initial part of the address is
410 trimmed off and the result is printed in hex, for example, 0x80324000 prints
411 as 324000.
412 .El
413 .Pp
414 When printing using the
415 .Ar command
416 keyword, a process that has exited and has a parent that has not yet
417 waited for the process (in other words, a zombie) is listed as
418 .Dq Aq defunct ,
419 and a process which is blocked while trying to exit is listed as
420 .Dq Aq exiting .
421 .Pp
422 .Nm
423 will try to locate the processes' argument vector from the user
424 area in order to print the command name and arguments.
425 This method is not reliable because a process is allowed to destroy this
426 information.
427 The
428 .Ar ucomm
429 (accounting) keyword will always contain the real command name as
430 contained in the process structure's
431 .Va p_comm
432 field.
433 .Pp
434 If the command vector cannot be located (usually because it has not
435 been set, as is the case of system processes and/or kernel threads)
436 the command name is printed within square brackets.
437 .Pp
438 To indicate that the argument vector has been tampered with,
439 .Nm
440 will append the real command name to the output within parentheses
441 if the basename of the first argument in the argument vector
442 does not match the contents of the real command name.
443 .Pp
444 In addition,
445 .Nm
446 checks for the following two situations and does not append the
447 real command name parenthesized:
448 .Bl -tag -width indent
449 .It -shellname
450 The login process traditionally adds a
451 .Sq -
452 in front of the shell name to indicate a login shell.
453 .Nm
454 will not append parenthesized the command name if it matches with
455 the name in the first argument of the argument vector, skipping
456 the leading
457 .Sq - .
458 .It daemonname: current-activity
459 Daemon processes frequently report their current activity by setting
460 their name to be like
461 .Dq daemonname: current-activity .
462 .Nm
463 will not append parenthesized the command name, if the string preceding the
464 .Sq \&:
465 in the first argument of the argument vector matches the command name.
466 .El
467 .Sh KEYWORDS
468 The following is a complete list of the available keywords and their
469 meanings.
470 Several of them have aliases (keywords which are synonyms).
471 .Pp
472 .Bl -tag -width groupnames -compact
473 .It Ar %cpu
474 percentage CPU usage (alias
475 .Ar pcpu )
476 .It Ar %mem
477 percentage memory usage (alias
478 .Ar pmem )
479 .It Ar acflag
480 accounting flag (alias
481 .Ar acflg )
482 .It Ar comm
483 command (the argv[0] value)
484 .It Ar command
485 command and arguments (alias
486 .Ar args )
487 .It Ar cpu
488 short-term CPU usage factor (for scheduling)
489 .It Ar cpuid
490 CPU number the current process or lwp is running on.
491 .It Ar ctime
492 accumulated CPU time of all children that have exited
493 .It Ar egid
494 effective group id
495 .It Ar egroup
496 group name (from egid)
497 .It Ar emul
498 emulation name
499 .It Ar etime
500 elapsed time since the process was started, in the form
501 .Li [[dd-]hh:]mm:ss
502 .It Ar euid
503 effective user id
504 .It Ar euser
505 user name (from euid)
506 .It Ar flags
507 the process flags, in hexadecimal (alias
508 .Ar f )
509 .It Ar gid
510 effective group id
511 .It Ar group
512 group name (from gid)
513 .It Ar groupnames
514 group names (from group access list)
515 .It Ar groups
516 group access list
517 .It Ar inblk
518 total blocks read (alias
519 .Ar inblock )
520 .It Ar jobc
521 job control count
522 .It Ar ktrace
523 tracing flags
524 .It Ar ktracep
525 tracing vnode
526 .It Ar laddr
527 kernel virtual address of the
528 .Tn "struct lwp"
529 belonging to the LWP.
530 .It Ar lid
531 ID of the LWP
532 .It Ar lim
533 memory use limit
534 .It Ar lname
535 descriptive name of the LWP
536 .It Ar logname
537 login name of user who started the process (alias
538 .Ar login )
539 .It Ar lstart
540 time started
541 .It Ar lstate
542 symbolic LWP state
543 .It Ar ltime
544 CPU time of the LWP
545 .It Ar majflt
546 total page faults
547 .It Ar minflt
548 total page reclaims
549 .It Ar msgrcv
550 total messages received (reads from pipes/sockets)
551 .It Ar msgsnd
552 total messages sent (writes on pipes/sockets)
553 .It Ar nice
554 nice value (alias
555 .Ar ni )
556 .It Ar nivcsw
557 total involuntary context switches
558 .It Ar nlwp
559 number of LWPs in the process
560 .It Ar nsigs
561 total signals taken (alias
562 .Ar nsignals )
563 .It Ar nvcsw
564 total voluntary context switches
565 .It Ar nwchan
566 wait channel (as an address)
567 .It Ar oublk
568 total blocks written (alias
569 .Ar oublock )
570 .It Ar p_ru
571 resource usage pointer (valid only for zombie)
572 .It Ar paddr
573 kernel virtual address of the
574 .Tn "struct proc"
575 belonging to the process.
576 .It Ar pagein
577 pageins (same as majflt)
578 .It Ar pgid
579 process group number
580 .It Ar pid
581 process
582 .Tn ID
583 .It Ar ppid
584 parent process
585 .Tn ID
586 .It Ar pri
587 scheduling priority
588 .It Ar re
589 core residency time (in seconds; 127 = infinity)
590 .It Ar rgid
591 real group
592 .Tn ID
593 .It Ar rlink
594 reverse link on run queue, or 0
595 .It Ar rlwp
596 number of LWPs on a processor or run queue
597 .It Ar rss
598 resident set size
599 .It Ar rsz
600 resident set size + (text size / text use count) (alias
601 .Ar rssize )
602 .It Ar ruid
603 real user
604 .Tn ID
605 .It Ar ruser
606 user name (from ruid)
607 .It Ar sess
608 session pointer
609 .It Ar sid
610 session
611 .Tn ID
612 .It Ar sig
613 pending signals (alias
614 .Ar pending )
615 .It Ar sigcatch
616 caught signals (alias
617 .Ar caught )
618 .It Ar sigignore
619 ignored signals (alias
620 .Ar ignored )
621 .It Ar sigmask
622 blocked signals (alias
623 .Ar blocked )
624 .It Ar sl
625 sleep time (in seconds; 127 = infinity)
626 .It Ar start
627 time started
628 .It Ar state
629 symbolic process state (alias
630 .Ar stat )
631 .It Ar stime
632 accumulated system CPU time
633 .It Ar svgid
634 saved gid from a setgid executable
635 .It Ar svgroup
636 group name (from svgid)
637 .It Ar svuid
638 saved uid from a setuid executable
639 .It Ar svuser
640 user name (from svuid)
641 .It Ar tdev
642 control terminal device number
643 .It Ar time
644 accumulated CPU time, user + system (alias
645 .Ar cputime )
646 .It Ar tpgid
647 control terminal process group
648 .Tn ID
649 .It Ar tsess
650 control terminal session pointer
651 .It Ar tsiz
652 text size (in Kbytes)
653 .It Ar tt
654 control terminal name (two letter abbreviation)
655 .It Ar tty
656 full name of control terminal
657 .It Ar uaddr
658 kernel virtual address of the
659 .Tn "struct user"
660 belonging to the LWP.
661 .It Ar ucomm
662 name to be used for accounting
663 .It Ar uid
664 effective user
665 .Tn ID
666 .It Ar upr
667 scheduling priority on return from system call (alias
668 .Ar usrpri )
669 .It Ar user
670 user name (from uid)
671 .It Ar utime
672 accumulated user CPU time
673 .It Ar vsz
674 virtual size in Kbytes (alias
675 .Ar vsize )
676 .It Ar wchan
677 wait channel (as a symbolic name)
678 .It Ar xstat
679 exit or stop status (valid only for stopped or zombie process)
680 .El
681 .Sh FILES
682 .Bl -tag -width /var/run/kvm.db -compact
683 .It Pa /dev
684 special files and device names
685 .It Pa /dev/drum
686 default swap device
687 .It Pa /var/run/dev.cdb
688 /dev name database
689 .It Pa /var/db/kvm.db
690 system name list database
691 .It Pa /netbsd
692 default system name list
693 .El
694 .Sh SEE ALSO
695 .Xr kill 1 ,
696 .Xr pgrep 1 ,
697 .Xr pkill 1 ,
698 .Xr sh 1 ,
699 .Xr w 1 ,
700 .Xr kvm 3 ,
701 .Xr strftime 3 ,
702 .Xr dev_mkdb 8 ,
703 .Xr pstat 8
704 .Sh BUGS
705 Since
706 .Nm
707 cannot run faster than the system and is run as any other scheduled
708 process, the information it displays can never be exact.