xref: /freebsd/bin/ps/ps.1 (revision 3b8f08459569bf0faa21473e5cec2491e95c9349)
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 December 27, 2013
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" Ta "Process may hold a POSIX advisory lock"
296.It Dv "P_CONTROLT" Ta No "0x00002" Ta "Has a controlling terminal"
297.It Dv "P_KTHREAD" Ta No "0x00004" Ta "Kernel thread"
298.It Dv "P_FOLLOWFORK" Ta No "0x00008" Ta "Attach debugger to new children"
299.It Dv "P_PPWAIT" Ta No "0x00010" Ta "Parent is waiting for child to exec/exit"
300.It Dv "P_PROFIL" Ta No "0x00020" Ta "Has started profiling"
301.It Dv "P_STOPPROF" Ta No "0x00040" Ta "Has thread in requesting to stop prof"
302.It Dv "P_HADTHREADS" Ta No "0x00080" Ta "Has had threads (no cleanup shortcuts)"
303.It Dv "P_SUGID" Ta No "0x00100" Ta "Had set id privileges since last exec"
304.It Dv "P_SYSTEM" Ta No "0x00200" Ta "System proc: no sigs, stats or swapping"
305.It Dv "P_SINGLE_EXIT" Ta No "0x00400" Ta "Threads suspending should exit, not wait"
306.It Dv "P_TRACED" Ta No "0x00800" Ta "Debugged process being traced"
307.It Dv "P_WAITED" Ta No "0x01000" Ta "Someone is waiting for us"
308.It Dv "P_WEXIT" Ta No "0x02000" Ta "Working on exiting"
309.It Dv "P_EXEC" Ta No "0x04000" Ta "Process called exec"
310.It Dv "P_WKILLED" Ta No "0x08000" Ta "Killed, shall go to kernel/user boundary ASAP"
311.It Dv "P_CONTINUED" Ta No "0x10000" Ta "Proc has continued from a stopped state"
312.It Dv "P_STOPPED_SIG" Ta No "0x20000" Ta "Stopped due to SIGSTOP/SIGTSTP"
313.It Dv "P_STOPPED_TRACE" Ta No "0x40000" Ta "Stopped because of tracing"
314.It Dv "P_STOPPED_SINGLE" Ta No "0x80000" Ta "Only one thread can continue"
315.It Dv "P_PROTECTED" Ta No "0x100000" Ta "Do not kill on memory overcommit"
316.It Dv "P_SIGEVENT" Ta No "0x200000" Ta "Process pending signals changed"
317.It Dv "P_SINGLE_BOUNDARY" Ta No "0x400000" Ta "Threads should suspend at user boundary"
318.It Dv "P_HWPMC" Ta No "0x800000" Ta "Process is using HWPMCs"
319.It Dv "P_JAILED" Ta No "0x1000000" Ta "Process is in jail"
320.It Dv "P_ORPHAN" Ta No "0x2000000" Ta "Orphaned by original parent, reparented to debugger"
321.It Dv "P_INEXEC" Ta No "0x4000000" Ta "Process is in execve()"
322.It Dv "P_STATCHILD" Ta No "0x8000000" Ta "Child process stopped or exited"
323.It Dv "P_INMEM" Ta No "0x10000000" Ta "Loaded into memory"
324.It Dv "P_SWAPPINGOUT" Ta No "0x20000000" Ta "Process is being swapped out"
325.It Dv "P_SWAPPINGIN" Ta No "0x40000000" Ta "Process is being swapped in"
326.It Dv "P_PPTRACE" Ta No "0x80000000" Ta "Vforked child issued ptrace(PT_TRACEME)"
327.El
328.It Cm label
329The MAC label of the process.
330.It Cm lim
331The soft limit on memory used, specified via a call to
332.Xr setrlimit 2 .
333.It Cm lstart
334The exact time the command started, using the
335.Ql %c
336format described in
337.Xr strftime 3 .
338.It Cm lockname
339The name of the lock that the process is currently blocked on.
340If the name is invalid or unknown, then
341.Dq ???\&
342is displayed.
343.It Cm logname
344The login name associated with the session the process is in (see
345.Xr getlogin 2 ) .
346.It Cm mwchan
347The event name if the process is blocked normally, or the lock name if
348the process is blocked on a lock.
349See the wchan and lockname keywords
350for details.
351.It Cm nice
352The process scheduling increment (see
353.Xr setpriority 2 ) .
354.It Cm rss
355the real memory (resident set) size of the process (in 1024 byte units).
356.It Cm start
357The time the command started.
358If the command started less than 24 hours ago, the start time is
359displayed using the
360.Dq Li %l:ps.1p
361format described in
362.Xr strftime 3 .
363If the command started less than 7 days ago, the start time is
364displayed using the
365.Dq Li %a6.15p
366format.
367Otherwise, the start time is displayed using the
368.Dq Li %e%b%y
369format.
370.It Cm state
371The state is given by a sequence of characters, for example,
372.Dq Li RWNA .
373The first character indicates the run state of the process:
374.Pp
375.Bl -tag -width indent -compact
376.It Li D
377Marks a process in disk (or other short term, uninterruptible) wait.
378.It Li I
379Marks a process that is idle (sleeping for longer than about 20 seconds).
380.It Li L
381Marks a process that is waiting to acquire a lock.
382.It Li R
383Marks a runnable process.
384.It Li S
385Marks a process that is sleeping for less than about 20 seconds.
386.It Li T
387Marks a stopped process.
388.It Li W
389Marks an idle interrupt thread.
390.It Li Z
391Marks a dead process (a
392.Dq zombie ) .
393.El
394.Pp
395Additional characters after these, if any, indicate additional state
396information:
397.Pp
398.Bl -tag -width indent -compact
399.It Li +
400The process is in the foreground process group of its control terminal.
401.It Li <
402The process has raised CPU scheduling priority.
403.It Li E
404The process is trying to exit.
405.It Li J
406Marks a process which is in
407.Xr jail 2 .
408The hostname of the prison can be found in
409.Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status .
410.It Li L
411The process has pages locked in core (for example, for raw
412.Tn I/O ) .
413.It Li N
414The process has reduced CPU scheduling priority (see
415.Xr setpriority 2 ) .
416.It Li s
417The process is a session leader.
418.It Li V
419The process' parent is suspended during a
420.Xr vfork 2 ,
421waiting for the process to exec or exit.
422.It Li W
423The process is swapped out.
424.It Li X
425The process is being traced or debugged.
426.El
427.It Cm tt
428An abbreviation for the pathname of the controlling terminal, if any.
429The abbreviation consists of the three letters following
430.Pa /dev/tty ,
431or, for pseudo-terminals, the corresponding entry in
432.Pa /dev/pts .
433This is followed by a
434.Ql -
435if the process can no longer reach that
436controlling terminal (i.e., it has been revoked).
437A
438.Ql -
439without a preceding two letter abbreviation or pseudo-terminal device number
440indicates a process which never had a controlling terminal.
441The full pathname of the controlling terminal is available via the
442.Cm tty
443keyword.
444.It Cm wchan
445The event (an address in the system) on which a process waits.
446When printed numerically, the initial part of the address is
447trimmed off and the result is printed in hex, for example, 0x80324000 prints
448as 324000.
449.El
450.Pp
451When printing using the command keyword, a process that has exited and
452has a parent that has not yet waited for the process (in other words, a zombie)
453is listed as
454.Dq Li <defunct> ,
455and a process which is blocked while trying
456to exit is listed as
457.Dq Li <exiting> .
458If the arguments cannot be located (usually because it has not been set, as is
459the case of system processes and/or kernel threads) the command name is printed
460within square brackets.
461The
462.Nm
463utility first tries to obtain the arguments cached by the kernel (if they were
464shorter than the value of the
465.Va kern.ps_arg_cache_limit
466sysctl).
467The process can change the arguments shown with
468.Xr setproctitle 3 .
469Otherwise,
470.Nm
471makes an educated guess as to the file name and arguments given when the
472process was created by examining memory or the swap area.
473The method is inherently somewhat unreliable and in any event a process
474is entitled to destroy this information.
475The ucomm (accounting) keyword can, however, be depended on.
476If the arguments are unavailable or do not agree with the ucomm keyword,
477the value for the ucomm keyword is appended to the arguments in parentheses.
478.Sh KEYWORDS
479The following is a complete list of the available keywords and their
480meanings.
481Several of them have aliases (keywords which are synonyms).
482.Pp
483.Bl -tag -width ".Cm sigignore" -compact
484.It Cm %cpu
485percentage CPU usage (alias
486.Cm pcpu )
487.It Cm %mem
488percentage memory usage (alias
489.Cm pmem )
490.It Cm acflag
491accounting flag (alias
492.Cm acflg )
493.It Cm args
494command and arguments
495.It Cm class
496login class
497.It Cm comm
498command
499.It Cm command
500command and arguments
501.It Cm cow
502number of copy-on-write faults
503.It Cm cpu
504short-term CPU usage factor (for scheduling)
505.It Cm dsiz
506data size (in Kbytes)
507.It Cm emul
508system-call emulation environment
509.It Cm etime
510elapsed running time, format
511.Op days- Ns
512.Op hours: Ns
513minutes:seconds.
514.It Cm etimes
515elapsed running time, in decimal integer seconds
516.It Cm fib
517default FIB number, see
518.Xr setfib 1
519.It Cm flags
520the process flags, in hexadecimal (alias
521.Cm f )
522.It Cm gid
523effective group ID (alias
524.Cm egid )
525.It Cm group
526group name (from egid) (alias
527.Cm egroup )
528.It Cm inblk
529total blocks read (alias
530.Cm inblock )
531.It Cm jid
532jail ID
533.It Cm jobc
534job control count
535.It Cm ktrace
536tracing flags
537.It Cm label
538MAC label
539.It Cm lim
540memoryuse limit
541.It Cm lockname
542lock currently blocked on (as a symbolic name)
543.It Cm logname
544login name of user who started the session
545.It Cm lstart
546time started
547.It Cm lwp
548process thread-id
549.It Cm majflt
550total page faults
551.It Cm minflt
552total page reclaims
553.It Cm msgrcv
554total messages received (reads from pipes/sockets)
555.It Cm msgsnd
556total messages sent (writes on pipes/sockets)
557.It Cm mwchan
558wait channel or lock currently blocked on
559.It Cm nice
560nice value (alias
561.Cm ni )
562.It Cm nivcsw
563total involuntary context switches
564.It Cm nlwp
565number of threads tied to a process
566.It Cm nsigs
567total signals taken (alias
568.Cm nsignals )
569.It Cm nswap
570total swaps in/out
571.It Cm nvcsw
572total voluntary context switches
573.It Cm nwchan
574wait channel (as an address)
575.It Cm oublk
576total blocks written (alias
577.Cm oublock )
578.It Cm paddr
579process pointer
580.It Cm pagein
581pageins (same as majflt)
582.It Cm pgid
583process group number
584.It Cm pid
585process ID
586.It Cm ppid
587parent process ID
588.It Cm pri
589scheduling priority
590.It Cm re
591core residency time (in seconds; 127 = infinity)
592.It Cm rgid
593real group ID
594.It Cm rgroup
595group name (from rgid)
596.It Cm rss
597resident set size
598.It Cm rtprio
599realtime priority (101 = not a realtime process)
600.It Cm ruid
601real user ID
602.It Cm ruser
603user name (from ruid)
604.It Cm sid
605session ID
606.It Cm sig
607pending signals (alias
608.Cm pending )
609.It Cm sigcatch
610caught signals (alias
611.Cm caught )
612.It Cm sigignore
613ignored signals (alias
614.Cm ignored )
615.It Cm sigmask
616blocked signals (alias
617.Cm blocked )
618.It Cm sl
619sleep time (in seconds; 127 = infinity)
620.It Cm ssiz
621stack size (in Kbytes)
622.It Cm start
623time started
624.It Cm state
625symbolic process state (alias
626.Cm stat )
627.It Cm svgid
628saved gid from a setgid executable
629.It Cm svuid
630saved UID from a setuid executable
631.It Cm systime
632accumulated system CPU time
633.It Cm tdaddr
634thread address
635.It Cm tdev
636control terminal device number
637.It Cm time
638accumulated CPU time, user + system (alias
639.Cm cputime )
640.It Cm tpgid
641control terminal process group ID
642.\".It Cm trss
643.\"text resident set size (in Kbytes)
644.It Cm tsid
645control terminal session ID
646.It Cm tsiz
647text size (in Kbytes)
648.It Cm tt
649control terminal name (two letter abbreviation)
650.It Cm tty
651full name of control terminal
652.It Cm ucomm
653name to be used for accounting
654.It Cm uid
655effective user ID (alias
656.Cm euid )
657.It Cm upr
658scheduling priority on return from system call (alias
659.Cm usrpri )
660.It Cm uprocp
661process pointer
662.It Cm user
663user name (from UID)
664.It Cm usertime
665accumulated user CPU time
666.It Cm vsz
667virtual size in Kbytes (alias
668.Cm vsize )
669.It Cm wchan
670wait channel (as a symbolic name)
671.It Cm xstat
672exit or stop status (valid only for stopped or zombie process)
673.El
674.Pp
675Note that the
676.Cm pending
677column displays bitmask of signals pending in the process queue when
678.Fl H
679option is not specified, otherwise the per-thread queue of pending signals
680is shown.
681.Sh ENVIRONMENT
682The following environment variables affect the execution of
683.Nm :
684.Bl -tag -width ".Ev COLUMNS"
685.It Ev COLUMNS
686If set, specifies the user's preferred output width in column positions.
687By default,
688.Nm
689attempts to automatically determine the terminal width.
690.El
691.Sh FILES
692.Bl -tag -width ".Pa /boot/kernel/kernel" -compact
693.It Pa /boot/kernel/kernel
694default system namelist
695.El
696.Sh EXAMPLES
697Display information on all system processes:
698.Pp
699.Dl $ ps -auxw
700.Sh SEE ALSO
701.Xr kill 1 ,
702.Xr pgrep 1 ,
703.Xr pkill 1 ,
704.Xr procstat 1 ,
705.Xr w 1 ,
706.Xr kvm 3 ,
707.Xr strftime 3 ,
708.Xr mac 4 ,
709.Xr procfs 5 ,
710.Xr pstat 8 ,
711.Xr sysctl 8 ,
712.Xr mutex 9
713.Sh STANDARDS
714For historical reasons, the
715.Nm
716utility under
717.Fx
718supports a different set of options from what is described by
719.St -p1003.2 ,
720and what is supported on
721.No non- Ns Bx
722operating systems.
723.Sh HISTORY
724The
725.Nm
726command appeared in
727.At v4 .
728.Sh BUGS
729Since
730.Nm
731cannot run faster than the system and is run as any other scheduled
732process, the information it displays can never be exact.
733.Pp
734The
735.Nm
736utility does not correctly display argument lists containing multibyte
737characters.
738