xref: /freebsd/bin/ps/ps.1 (revision bb15ca603fa442c72dde3f3cb8b46db6970e3950)
1.\"-
2.\" Copyright (c) 1980, 1990, 1991, 1993, 1994
3.\"	The Regents of the University of California.  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.\" 4. Neither the name of the University nor the names of its contributors
14.\"    may be used to endorse or promote products derived from this software
15.\"    without specific prior written permission.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
29.\"     @(#)ps.1	8.3 (Berkeley) 4/18/94
30.\" $FreeBSD$
31.\"
32.Dd November 22, 2011
33.Dt PS 1
34.Os
35.Sh NAME
36.Nm ps
37.Nd process status
38.Sh SYNOPSIS
39.Nm
40.Op Fl aCcdefHhjlmrSTuvwXxZ
41.Op Fl O Ar fmt | Fl o Ar fmt
42.Op Fl G Ar gid Ns Op , Ns Ar gid Ns Ar ...
43.Op Fl M Ar core
44.Op Fl N Ar system
45.Op Fl p Ar pid Ns Op , Ns Ar pid Ns Ar ...
46.Op Fl t Ar tty Ns Op , Ns Ar tty Ns Ar ...
47.Op Fl U Ar user Ns Op , Ns Ar user Ns Ar ...
48.Nm
49.Op Fl L
50.Sh DESCRIPTION
51The
52.Nm
53utility
54displays a header line, followed by lines containing information about
55all of your
56processes that have controlling terminals.
57If the
58.Fl x
59options is specified,
60.Nm
61will also display processes that do not have controlling terminals.
62.Pp
63A different set of processes can be selected for display by using any
64combination of the
65.Fl a , G , p , T , t ,
66and
67.Fl U
68options.
69If more than one of these options are given, then
70.Nm
71will select all processes which are matched by at least one of the
72given options.
73.Pp
74For the processes which have been selected for display,
75.Nm
76will usually display one line per process.
77The
78.Fl H
79option may result in multiple output lines (one line per thread) for
80some processes.
81By default all of these output lines are sorted first by controlling
82terminal, then by process ID.
83The
84.Fl m , r , u ,
85and
86.Fl v
87options will change the sort order.
88If more than one sorting option was given, then the selected processes
89will be sorted by the last sorting option which was specified.
90.Pp
91For the processes which have been selected for display, the information
92to display is selected based on a set of keywords (see the
93.Fl L , O ,
94and
95.Fl o
96options).
97The default output format includes, for each process, the process' ID,
98controlling terminal, state, CPU time (including both user and system time)
99and associated command.
100.Pp
101The options are as follows:
102.Bl -tag -width indent
103.It Fl a
104Display information about other users' processes as well as your own.
105If the
106.Va security.bsd.see_other_uids
107sysctl is set to zero, this option is honored only if the UID of the user is 0.
108.It Fl c
109Change the
110.Dq command
111column output to just contain the executable name,
112rather than the full command line.
113.It Fl C
114Change the way the CPU percentage is calculated by using a
115.Dq raw
116CPU calculation that ignores
117.Dq resident
118time (this normally has
119no effect).
120.It Fl d
121Arrange processes into descendancy order and prefix each command with
122indentation text showing sibling and parent/child relationships.
123If either of the
124.Fl m
125and
126.Fl r
127options are also used, they control how sibling processes are sorted
128relative to each other.
129Note that this option has no effect if the
130.Dq command
131column is not the last column displayed.
132.It Fl e
133Display the environment as well.
134.It Fl f
135Show commandline and environment information about swapped out processes.
136This option is honored only if the UID of the user is 0.
137.It Fl G
138Display information about processes which are running with the specified
139real group IDs.
140.It Fl H
141Show all of the
142.Em kernel visible
143threads associated with each process.
144Depending on the threading package that
145is in use, this may show only the process, only the kernel scheduled entities,
146or all of the process threads.
147.It Fl h
148Repeat the information header as often as necessary to guarantee one
149header per page of information.
150.It Fl j
151Print information associated with the following keywords:
152.Cm user , pid , ppid , pgid , sid , jobc , state , tt , time ,
153and
154.Cm command .
155.It Fl L
156List the set of keywords available for the
157.Fl O
158and
159.Fl o
160options.
161.It Fl l
162Display information associated with the following keywords:
163.Cm uid , pid , ppid , cpu , pri , nice , vsz , rss , mwchan , state ,
164.Cm tt , time ,
165and
166.Cm command .
167.It Fl M
168Extract values associated with the name list from the specified core
169instead of the currently running system.
170.It Fl m
171Sort by memory usage, instead of the combination of controlling
172terminal and process ID.
173.It Fl N
174Extract the name list from the specified system instead of the default,
175which is the kernel image the system has booted from.
176.It Fl O
177Add the information associated with the space or comma separated list
178of keywords specified, after the process ID,
179in the default information
180display.
181Keywords may be appended with an equals
182.Pq Ql =
183sign and a string.
184This causes the printed header to use the specified string instead of
185the standard header.
186.It Fl o
187Display information associated with the space or comma separated
188list of keywords specified.
189The last keyword in the list may be appended with an equals
190.Pq Ql =
191sign and a string that spans the rest of the argument, and can contain
192space and comma characters.
193This causes the printed header to use the specified string instead of
194the standard header.
195Multiple keywords may also be given in the form of more than one
196.Fl o
197option.
198So the header texts for multiple keywords can be changed.
199If all keywords have empty header texts, no header line is written.
200.It Fl p
201Display information about processes which match the specified process IDs.
202.It Fl r
203Sort by current CPU usage, instead of the combination of controlling
204terminal and process ID.
205.It Fl S
206Change the way the process times, namely cputime, systime, and usertime,
207are calculated by summing all exited children to their parent process.
208.It Fl T
209Display information about processes attached to the device associated
210with the standard input.
211.It Fl t
212Display information about processes attached to the specified terminal
213devices.
214Full pathnames, as well as abbreviations (see explanation of the
215.Cm tt
216keyword) can be specified.
217.It Fl U
218Display the processes belonging to the specified usernames.
219.It Fl u
220Display information associated with the following keywords:
221.Cm user , pid , %cpu , %mem , vsz , rss , tt , state , start , time ,
222and
223.Cm command .
224The
225.Fl u
226option implies the
227.Fl r
228option.
229.It Fl v
230Display information associated with the following keywords:
231.Cm pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz ,
232.Cm %cpu , %mem ,
233and
234.Cm command .
235The
236.Fl v
237option implies the
238.Fl m
239option.
240.It Fl w
241Use 132 columns to display information, instead of the default which
242is your window size.
243If the
244.Fl w
245option is specified more than once,
246.Nm
247will use as many columns as necessary without regard for your window size.
248Note that this option has no effect if the
249.Dq command
250column is not the last column displayed.
251.It Fl X
252When displaying processes matched by other options, skip any processes
253which do not have a controlling terminal.
254This is the default behaviour.
255.It Fl x
256When displaying processes matched by other options, include processes
257which do not have a controlling terminal.
258This is the opposite of the
259.Fl X
260option.
261If both
262.Fl X
263and
264.Fl x
265are specified in the same command, then
266.Nm
267will use the one which was specified last.
268.It Fl Z
269Add
270.Xr mac 4
271label to the list of keywords for which
272.Nm
273will display information.
274.El
275.Pp
276A complete list of the available keywords are listed below.
277Some of these keywords are further specified as follows:
278.Bl -tag -width lockname
279.It Cm %cpu
280The CPU utilization of the process; this is a decaying average over up to
281a minute of previous (real) time.
282Since the time base over which this is computed varies (since processes may
283be very young) it is possible for the sum of all
284.Cm %cpu
285fields to exceed 100%.
286.It Cm %mem
287The percentage of real memory used by this process.
288.It Cm class
289Login class associated with the process.
290.It Cm flags
291The flags associated with the process as in
292the include file
293.In sys/proc.h :
294.Bl -column P_SINGLE_BOUNDARY 0x40000000
295.It Dv "P_ADVLOCK" Ta No "0x00001	Process may hold a POSIX advisory lock"
296.It Dv "P_CONTROLT" Ta No "0x00002	Has a controlling terminal"
297.It Dv "P_KTHREAD" Ta No "0x00004	Kernel thread"
298.It Dv "P_FOLLOWFORK" Ta No "0x00008	Attach debugger to new children"
299.It Dv "P_PPWAIT" Ta No "0x00010	Parent is waiting for child to exec/exit"
300.It Dv "P_PROFIL" Ta No "0x00020	Has started profiling"
301.It Dv "P_STOPPROF" Ta No "0x00040	Has thread in requesting to stop prof"
302.It Dv "P_HADTHREADS" Ta No "0x00080	Has had threads (no cleanup shortcuts)"
303.It Dv "P_SUGID" Ta No "0x00100		Had set id privileges since last exec"
304.It Dv "P_SYSTEM" Ta No "0x00200	System proc: no sigs, stats or swapping"
305.It Dv "P_SINGLE_EXIT" Ta No "0x00400	Threads suspending should exit, not wait"
306.It Dv "P_TRACED" Ta No "0x00800	Debugged process being traced"
307.It Dv "P_WAITED" Ta No "0x01000	Someone is waiting for us"
308.It Dv "P_WEXIT" Ta No "0x02000		Working on exiting"
309.It Dv "P_EXEC" Ta No "0x04000		Process called exec"
310.It Dv "P_WKILLED" Ta No "0x08000	Killed, shall go to kernel/user boundary ASAP"
311.It Dv "P_CONTINUED" Ta No "0x10000	Proc has continued from a stopped state"
312.It Dv "P_STOPPED_SIG" Ta No "0x20000	Stopped due to SIGSTOP/SIGTSTP"
313.It Dv "P_STOPPED_TRACE" Ta No "0x40000	Stopped because of tracing"
314.It Dv "P_STOPPED_SINGLE" Ta No "0x80000	Only one thread can continue"
315.It Dv "P_PROTECTED" Ta No "0x100000	Do not kill on memory overcommit"
316.It Dv "P_SIGEVENT" Ta No "0x200000	Process pending signals changed"
317.It Dv "P_SINGLE_BOUNDARY" Ta No "0x400000	Threads should suspend at user boundary"
318.It Dv "P_HWPMC" Ta No "0x800000	Process is using HWPMCs"
319.It Dv "P_JAILED" Ta No "0x1000000	Process is in jail"
320.It Dv "P_INEXEC" Ta No "0x4000000	Process is in execve()"
321.It Dv "P_STATCHILD" Ta No "0x8000000	Child process stopped or exited"
322.It Dv "P_INMEM" Ta No "0x10000000	Loaded into memory"
323.It Dv "P_SWAPPINGOUT" Ta No "0x20000000	Process is being swapped out"
324.It Dv "P_SWAPPINGIN" Ta No "0x40000000	Process is being swapped in"
325.El
326.It Cm label
327The MAC label of the process.
328.It Cm lim
329The soft limit on memory used, specified via a call to
330.Xr setrlimit 2 .
331.It Cm lstart
332The exact time the command started, using the
333.Ql %c
334format described in
335.Xr strftime 3 .
336.It Cm lockname
337The name of the lock that the process is currently blocked on.
338If the name is invalid or unknown, then
339.Dq ???\&
340is displayed.
341.It Cm logname
342The login name associated with the session the process is in (see
343.Xr getlogin 2 ) .
344.It Cm mwchan
345The event name if the process is blocked normally, or the lock name if
346the process is blocked on a lock.
347See the wchan and lockname keywords
348for details.
349.It Cm nice
350The process scheduling increment (see
351.Xr setpriority 2 ) .
352.It Cm rss
353the real memory (resident set) size of the process (in 1024 byte units).
354.It Cm start
355The time the command started.
356If the command started less than 24 hours ago, the start time is
357displayed using the
358.Dq Li %l:ps.1p
359format described in
360.Xr strftime 3 .
361If the command started less than 7 days ago, the start time is
362displayed using the
363.Dq Li %a6.15p
364format.
365Otherwise, the start time is displayed using the
366.Dq Li %e%b%y
367format.
368.It Cm state
369The state is given by a sequence of characters, for example,
370.Dq Li RWNA .
371The first character indicates the run state of the process:
372.Pp
373.Bl -tag -width indent -compact
374.It Li D
375Marks a process in disk (or other short term, uninterruptible) wait.
376.It Li I
377Marks a process that is idle (sleeping for longer than about 20 seconds).
378.It Li L
379Marks a process that is waiting to acquire a lock.
380.It Li R
381Marks a runnable process.
382.It Li S
383Marks a process that is sleeping for less than about 20 seconds.
384.It Li T
385Marks a stopped process.
386.It Li W
387Marks an idle interrupt thread.
388.It Li Z
389Marks a dead process (a
390.Dq zombie ) .
391.El
392.Pp
393Additional characters after these, if any, indicate additional state
394information:
395.Pp
396.Bl -tag -width indent -compact
397.It Li +
398The process is in the foreground process group of its control terminal.
399.It Li <
400The process has raised CPU scheduling priority.
401.It Li E
402The process is trying to exit.
403.It Li J
404Marks a process which is in
405.Xr jail 2 .
406The hostname of the prison can be found in
407.Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status .
408.It Li L
409The process has pages locked in core (for example, for raw
410.Tn I/O ) .
411.It Li N
412The process has reduced CPU scheduling priority (see
413.Xr setpriority 2 ) .
414.It Li s
415The process is a session leader.
416.It Li V
417The process is suspended during a
418.Xr vfork 2 .
419.It Li W
420The process is swapped out.
421.It Li X
422The process is being traced or debugged.
423.El
424.It Cm tt
425An abbreviation for the pathname of the controlling terminal, if any.
426The abbreviation consists of the three letters following
427.Pa /dev/tty ,
428or, for pseudo-terminals, the corresponding entry in
429.Pa /dev/pts .
430This is followed by a
431.Ql -
432if the process can no longer reach that
433controlling terminal (i.e., it has been revoked).
434A
435.Ql -
436without a preceding two letter abbreviation or pseudo-terminal device number
437indicates a process which never had a controlling terminal.
438The full pathname of the controlling terminal is available via the
439.Cm tty
440keyword.
441.It Cm wchan
442The event (an address in the system) on which a process waits.
443When printed numerically, the initial part of the address is
444trimmed off and the result is printed in hex, for example, 0x80324000 prints
445as 324000.
446.El
447.Pp
448When printing using the command keyword, a process that has exited and
449has a parent that has not yet waited for the process (in other words, a zombie)
450is listed as
451.Dq Li <defunct> ,
452and a process which is blocked while trying
453to exit is listed as
454.Dq Li <exiting> .
455If the arguments cannot be located (usually because it has not been set, as is
456the case of system processes and/or kernel threads) the command name is printed
457within square brackets.
458The
459.Nm
460utility first tries to obtain the arguments cached by the kernel (if they were
461shorter than the value of the
462.Va kern.ps_arg_cache_limit
463sysctl).
464The process can change the arguments shown with
465.Xr setproctitle 3 .
466Otherwise,
467.Nm
468makes an educated guess as to the file name and arguments given when the
469process was created by examining memory or the swap area.
470The method is inherently somewhat unreliable and in any event a process
471is entitled to destroy this information.
472The ucomm (accounting) keyword can, however, be depended on.
473If the arguments are unavailable or do not agree with the ucomm keyword,
474the value for the ucomm keyword is appended to the arguments in parentheses.
475.Sh KEYWORDS
476The following is a complete list of the available keywords and their
477meanings.
478Several of them have aliases (keywords which are synonyms).
479.Pp
480.Bl -tag -width ".Cm sigignore" -compact
481.It Cm %cpu
482percentage CPU usage (alias
483.Cm pcpu )
484.It Cm %mem
485percentage memory usage (alias
486.Cm pmem )
487.It Cm acflag
488accounting flag (alias
489.Cm acflg )
490.It Cm args
491command and arguments
492.It Cm class
493login class
494.It Cm comm
495command
496.It Cm command
497command and arguments
498.It Cm cpu
499short-term CPU usage factor (for scheduling)
500.It Cm emul
501system-call emulation environment
502.It Cm etime
503elapsed running time, format
504.Op days- Ns
505.Op hours: Ns
506minutes:seconds.
507.It Cm etimes
508elapsed running time, in decimal integer seconds
509.It Cm flags
510the process flags, in hexadecimal (alias
511.Cm f )
512.It Cm gid
513effective group ID (alias
514.Cm egid )
515.It Cm group
516group name (from egid) (alias
517.Cm egroup )
518.It Cm inblk
519total blocks read (alias
520.Cm inblock )
521.It Cm jid
522jail ID
523.It Cm jobc
524job control count
525.It Cm ktrace
526tracing flags
527.It Cm label
528MAC label
529.It Cm lim
530memoryuse limit
531.It Cm lockname
532lock currently blocked on (as a symbolic name)
533.It Cm logname
534login name of user who started the session
535.It Cm lstart
536time started
537.It Cm lwp
538process thread-id
539.It Cm majflt
540total page faults
541.It Cm minflt
542total page reclaims
543.It Cm msgrcv
544total messages received (reads from pipes/sockets)
545.It Cm msgsnd
546total messages sent (writes on pipes/sockets)
547.It Cm mwchan
548wait channel or lock currently blocked on
549.It Cm nice
550nice value (alias
551.Cm ni )
552.It Cm nivcsw
553total involuntary context switches
554.It Cm nlwp
555number of threads tied to a process
556.It Cm nsigs
557total signals taken (alias
558.Cm nsignals )
559.It Cm nswap
560total swaps in/out
561.It Cm nvcsw
562total voluntary context switches
563.It Cm nwchan
564wait channel (as an address)
565.It Cm oublk
566total blocks written (alias
567.Cm oublock )
568.It Cm paddr
569process pointer
570.It Cm pagein
571pageins (same as majflt)
572.It Cm pgid
573process group number
574.It Cm pid
575process ID
576.It Cm ppid
577parent process ID
578.It Cm pri
579scheduling priority
580.It Cm re
581core residency time (in seconds; 127 = infinity)
582.It Cm rgid
583real group ID
584.It Cm rgroup
585group name (from rgid)
586.It Cm rss
587resident set size
588.It Cm rtprio
589realtime priority (101 = not a realtime process)
590.It Cm ruid
591real user ID
592.It Cm ruser
593user name (from ruid)
594.It Cm sid
595session ID
596.It Cm sig
597pending signals (alias
598.Cm pending )
599.It Cm sigcatch
600caught signals (alias
601.Cm caught )
602.It Cm sigignore
603ignored signals (alias
604.Cm ignored )
605.It Cm sigmask
606blocked signals (alias
607.Cm blocked )
608.It Cm sl
609sleep time (in seconds; 127 = infinity)
610.It Cm start
611time started
612.It Cm state
613symbolic process state (alias
614.Cm stat )
615.It Cm svgid
616saved gid from a setgid executable
617.It Cm svuid
618saved UID from a setuid executable
619.It Cm systime
620accumulated system CPU time
621.It Cm tdaddr
622thread address
623.It Cm tdev
624control terminal device number
625.It Cm time
626accumulated CPU time, user + system (alias
627.Cm cputime )
628.It Cm tpgid
629control terminal process group ID
630.\".It Cm trss
631.\"text resident set size (in Kbytes)
632.It Cm tsid
633control terminal session ID
634.It Cm tsiz
635text size (in Kbytes)
636.It Cm tt
637control terminal name (two letter abbreviation)
638.It Cm tty
639full name of control terminal
640.It Cm ucomm
641name to be used for accounting
642.It Cm uid
643effective user ID (alias
644.Cm euid )
645.It Cm upr
646scheduling priority on return from system call (alias
647.Cm usrpri )
648.It Cm uprocp
649process pointer
650.It Cm user
651user name (from UID)
652.It Cm usertime
653accumulated user CPU time
654.It Cm vsz
655virtual size in Kbytes (alias
656.Cm vsize )
657.It Cm wchan
658wait channel (as a symbolic name)
659.It Cm xstat
660exit or stop status (valid only for stopped or zombie process)
661.El
662.Pp
663Note that the
664.Cm pending
665column displays bitmask of signals pending in the process queue when
666.Fl H
667option is not specified, otherwise the per-thread queue of pending signals
668is shown.
669.Sh ENVIRONMENT
670The following environment variables affect the execution of
671.Nm :
672.Bl -tag -width ".Ev COLUMNS"
673.It Ev COLUMNS
674If set, specifies the user's preferred output width in column positions.
675By default,
676.Nm
677attempts to automatically determine the terminal width.
678.El
679.Sh FILES
680.Bl -tag -width ".Pa /boot/kernel/kernel" -compact
681.It Pa /boot/kernel/kernel
682default system namelist
683.El
684.Sh SEE ALSO
685.Xr kill 1 ,
686.Xr pgrep 1 ,
687.Xr pkill 1 ,
688.Xr procstat 1 ,
689.Xr w 1 ,
690.Xr kvm 3 ,
691.Xr strftime 3 ,
692.Xr mac 4 ,
693.Xr procfs 5 ,
694.Xr pstat 8 ,
695.Xr sysctl 8 ,
696.Xr mutex 9
697.Sh STANDARDS
698For historical reasons, the
699.Nm
700utility under
701.Fx
702supports a different set of options from what is described by
703.St -p1003.2 ,
704and what is supported on
705.No non- Ns Bx
706operating systems.
707.Sh HISTORY
708The
709.Nm
710command appeared in
711.At v4 .
712.Sh BUGS
713Since
714.Nm
715cannot run faster than the system and is run as any other scheduled
716process, the information it displays can never be exact.
717.Pp
718The
719.Nm
720utility does not correctly display argument lists containing multibyte
721characters.
722