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