xref: /dragonfly/bin/ps/ps.1 (revision 277350a0)
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. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)ps.1	8.3 (Berkeley) 4/18/94
29.\" $FreeBSD: src/bin/ps/ps.1,v 1.24.2.7 2002/06/20 22:43:33 charnier Exp $
30.\"
31.Dd June 16, 2016
32.Dt PS 1
33.Os
34.Sh NAME
35.Nm ps
36.Nd process status
37.Sh SYNOPSIS
38.Nm
39.Op Fl AaCcefHhjlmrRSTuvwx
40.Op Fl M Ar core
41.Op Fl N Ar system
42.Op Fl O Ar fmt
43.Op Fl o Ar fmt
44.Op Fl p Ar pid
45.Op Fl t Ar tty
46.Op Fl U Ar username
47.Nm
48.Op Fl L
49.Sh DESCRIPTION
50The
51.Nm
52utility
53displays a header line followed by lines containing information about your
54processes that have controlling terminals.
55This information is sorted by controlling terminal, then by process ID.
56.Pp
57The information displayed is selected based on a set of keywords (see the
58.Fl L
59.Fl O
60and
61.Fl o
62options).
63The default output format includes, for each process, the process' ID,
64controlling terminal, CPU time (including both user and system time),
65state, and associated command.
66.Pp
67The process file system (see
68.Xr procfs 5 )
69should be mounted when
70.Nm
71is executed, otherwise not all information will be available.
72.Pp
73The options are as follows:
74.Bl -tag -width indent
75.It Fl a
76Display information about other users' processes as well as your own.
77This can be disabled by setting the
78.Va security.ps_showallprocs
79sysctl to zero.
80.It Fl A
81Same as
82.Fl ax .
83.It Fl c
84Change the ``command'' column output to just contain the executable name,
85rather than the full command line.
86.It Fl C
87Change the way the CPU percentage is calculated by using a ``raw''
88CPU calculation that ignores ``resident'' time (this normally has
89no effect).
90.It Fl e
91Display the environment as well.
92.It Fl f
93Show commandline and environment information about swapped out processes.
94This option is honored only if the uid of the user is 0.
95.It Fl H
96Print one line per lightweight process (LWP) instead of one line per process.
97When this option is set and the
98.Fl o
99option is not set, the
100.Cm tid
101column is inserted in the output format after the
102.Cm pid
103one.
104.It Fl h
105Repeat the information header as often as necessary to guarantee one
106header per page of information.
107.It Fl j
108Print information associated with the following keywords:
109.Cm user , pid , ppid , pgid , sess , jobc , state , tt , time ,
110and
111.Cm command .
112.It Fl L
113List the set of available keywords.
114.It Fl l
115Display information associated with the following keywords:
116.Cm uid , pid , ppid , cpu , pri , nice , vsz , rss , wchan , state ,
117.Cm tt , time ,
118and
119.Cm command .
120.It Fl M
121Extract values associated with the name list from the specified core
122instead of the default
123.Pa /dev/kmem .
124.It Fl m
125Sort by memory usage, instead of by process ID.
126.It Fl N
127Extract the name list from the specified system instead of the default
128.Pa /boot/kernel .
129.It Fl O
130Add the information associated with the space or comma separated list
131of keywords specified, after the process ID,
132in the default information
133display.
134Keywords may be appended with an equals (``='') sign and a string.
135This causes the printed header to use the specified string instead of
136the standard header.
137.It Fl o
138Display information associated with the space or comma separated list
139of keywords specified.
140Keywords may be appended with an equals (``='') sign and a string.
141This causes the printed header to use the specified string instead of
142the standard header.
143.It Fl p
144Display information associated with the specified process ID.
145.It Fl r
146Sort by current CPU usage, instead of by process ID.
147.It Fl R
148Subsort by parent/child chain.  This very useful option makes
149the parent/child associations clear and understandable.
150If used in combination with
151.Fl p
152then all children of the specified process will be output
153recursively in addition to the process itself.
154.It Fl S
155Change the way the process time is calculated by summing all exited
156children to their parent process.
157.It Fl T
158Display information about processes attached to the device associated
159with the standard input.
160.It Fl t
161Display information about processes attached to the specified terminal
162device.
163.It Fl U
164Display the processes belonging to the specified
165.Ar username .
166.It Fl u
167Display information associated with the following keywords:
168.Cm user , pid, %cpu , %mem , vsz , rss , tt , state , start , time ,
169and
170.Cm command .
171The
172.Fl u
173option implies the
174.Fl r
175option.
176.It Fl v
177Display information associated with the following keywords:
178.Cm pid , state , time , sl , re , pagein , vsz , rss , lim , tsiz ,
179.Cm %cpu , %mem
180and
181.Cm command .
182The
183.Fl v
184option implies the
185.Fl m
186option.
187.It Fl w
188Use 132 columns to display information, instead of the default which
189is your window size.
190If the
191.Fl w
192option is specified more than once,
193.Nm
194will use as many columns as necessary without regard for your window size.
195.It Fl x
196Display information about processes without controlling terminals.
197.El
198.Pp
199A complete list of the available keywords are listed below.
200Some of these keywords are further specified as follows:
201.Bl -tag -width ".Cm lstart"
202.It Cm %cpu
203The CPU utilization of the process; this is a decaying average over up to
204a minute of previous (real) time.
205Since the time base over which this is computed varies (since processes may
206be very young) it is possible for the sum of all
207.Cm %cpu
208fields to exceed 100%.
209.It Cm %mem
210The percentage of real memory used by this process.
211.It Cm flags
212The flags associated with the process as in
213the include file
214.In sys/proc.h .
215.It Cm lim
216The soft limit on memory used, specified via a call to
217.Xr setrlimit 2 .
218.It Cm lstart
219The exact time the command started, using the ``%c'' format described in
220.Xr strftime 3 .
221.It Cm nice
222The process scheduling increment (see
223.Xr setpriority 2 ) .
224.It Cm rss
225the real memory (resident set) size of the process (in 1024 byte units).
226.It Cm start
227The time the command started.
228If the command started less than 24 hours ago, the start time is
229displayed using the ``%l:ps.1p'' format described in
230.Xr strftime 3 .
231If the command started less than 7 days ago, the start time is
232displayed using the ``%a6.15p'' format.
233Otherwise, the start time is displayed using the ``%e%b%y'' format.
234.It Cm state
235The state is given by a sequence of letters, for example,
236.Dq Li RWNA .
237The first letter indicates the run state of the process:
238.Pp
239.Bl -tag -width indent -compact
240.It Li B
241Marks a blocked kernel thread.
242.It Li D
243Marks a process in disk (or other short term, uninterruptible) wait.
244.It Li I
245Marks a process that is idle (sleeping for longer than about 20 seconds).
246.It Li J
247Marks a process which is in
248.Xr jail 2 .
249The hostname of the prison can be found in
250.Pa /proc/ Ns Ao Ar pid Ac Ns Pa /status .
251.It Li R
252Marks a runnable process and is followed by the CPU number.
253.It Li S
254Marks a process that is sleeping for less than about 20 seconds.
255.It Li T
256Marks a stopped process.
257.It Li Z
258Marks a dead process (a
259.Dq zombie ) .
260.El
261.Pp
262Additional characters after these, if any, indicate additional state
263information:
264.Pp
265.Bl -tag -width indent -compact
266.It Li +
267The process is in the foreground process group of its control terminal.
268.It Li <
269The process has raised CPU scheduling priority.
270.It Li >
271The process has specified a soft limit on memory requirements and is
272currently exceeding that limit; such a process is (necessarily) not
273swapped.
274.It Li A
275the process has asked for random page replacement
276.Pf ( Dv MADV_RANDOM ,
277from
278.Xr madvise 2 ,
279for example,
280.Xr lisp 1
281in a garbage collect).
282.It Li E
283The process is trying to exit.
284.It Li L
285The process has pages locked in core (for example, for raw
286.Tn I/O ) .
287.It Li N
288The process has reduced CPU scheduling priority (see
289.Xr setpriority 2 ) .
290.It Li S
291The process has asked for FIFO page replacement
292.Pf ( Dv MADV_SEQUENTIAL ,
293from
294.Xr madvise 2 ,
295for example, a large image processing program using virtual memory to
296sequentially address voluminous data).
297.It Li s
298The process is a session leader.
299.It Li V
300The process is suspended during a
301.Xr vfork 2 .
302.It Li W
303The process is swapped out.
304.It Li X
305The process is being traced or debugged.
306.El
307.It Cm tt
308An abbreviation for the pathname of the controlling terminal, if any.
309The abbreviation consists of the three letters following
310.Pa /dev/tty ,
311or, for the console, ``con''.
312This is followed by a ``-'' if the process can no longer reach that
313controlling terminal (i.e., it has been revoked).
314.It Cm wchan
315The event (an address in the system) on which a process waits.
316When printed numerically, the initial part of the address is
317trimmed off and the result is printed in hex, for example, 0x80324000 prints
318as 324000.  Note that blocked threads often only have ascii wchan's.
319.El
320.Pp
321When printing using the
322.Cm command
323keyword, a process that has exited and
324has a parent that has not yet waited for the process (in other words, a zombie)
325is listed as ``<defunct>'', and a process which is blocked while trying
326to exit is listed as ``<exiting>''.
327The
328.Nm
329utility
330makes an educated guess as to the file name and arguments given when the
331process was created by examining memory or the swap area.
332The method is inherently somewhat unreliable and in any event a process
333is entitled to destroy this information, so the names cannot be depended
334on too much.
335The
336.Cm ucomm
337(accounting) keyword can, however, be depended on.
338.Sh KEYWORDS
339The following is a complete list of the available keywords and their
340meanings.
341Several of them have aliases (keywords which are synonyms).
342.Pp
343.Bl -tag -width ".Cm sigignore" -compact
344.It Cm %cpu
345percentage CPU usage (alias
346.Cm pcpu )
347.It Cm %mem
348percentage memory usage (alias
349.Cm pmem )
350.It Cm acflag
351accounting flag (alias
352.Cm acflg )
353.It Cm batch
354batchness of the process (higher numbers mean less interactivity)
355.It Cm command
356command and arguments (alias
357.Cm args )
358.It Cm cpu
359short-term CPU usage factor (for scheduling)
360.It Cm f
361the process flags, in hexadecimal (alias
362.Cm flags )
363.It Cm inblk
364total blocks read (alias
365.Cm inblock )
366.It Cm jail
367jail ID
368.It Cm jobc
369job control count
370.It Cm ktrace
371tracing flags
372.\" .It Cm ktracep
373.\" tracing vnode
374.It Cm lastcpu
375CPU ID the process was last scheduled on
376.It Cm lim
377memoryuse limit
378.It Cm login
379login name of user who started the process (alias
380.Cm logname )
381.It Cm lstart
382time started
383.It Cm majflt
384total page faults
385.It Cm minflt
386total page reclaims
387.It Cm msgrcv
388total messages received (reads from pipes/sockets)
389.It Cm msgsnd
390total messages sent (writes on pipes/sockets)
391.It Cm nice
392nice value (alias
393.Cm ni )
394.It Cm nivcsw
395total involuntary context switches
396.It Cm nlwp
397number of lightweight processes
398.It Cm nsigs
399total signals taken (alias
400.Cm nsignals )
401.It Cm nswap
402total swaps in/out
403.It Cm nvcsw
404total voluntary context switches
405.It Cm nwchan
406wait channel (as an address)
407.It Cm oublk
408total blocks written (alias
409.Cm oublock )
410.It Cm p_ru
411resource usage (valid only for zombie)
412.It Cm paddr
413swap address
414.It Cm pagein
415pageins (same as
416.Cm majflt )
417.It Cm pgid
418process group number
419.It Cm pid
420process ID
421.It Cm ppid
422parent process ID
423.It Cm pri
424scheduling priority (lower == better)
425.It Cm re
426core residency time (in seconds; 127 = infinity)
427.It Cm rgid
428real group ID
429.\" .It Cm rlink
430.\" reverse link on run queue, or 0
431.It Cm rss
432resident set size
433.It Cm rsz
434resident set size + (text size / text use count) (alias
435.Cm rssize )
436.It Cm rtprio
437realtime priority (101 = not a realtime process)
438.It Cm ruid
439real user ID
440.It Cm ruser
441user name (from ruid)
442.It Cm sess
443session pointer
444.It Cm sig
445pending signals (alias
446.Cm pending )
447.It Cm sigcatch
448caught signals (alias
449.Cm caught )
450.It Cm sigignore
451ignored signals (alias
452.Cm ignored )
453.It Cm sigmask
454blocked signals (alias
455.Cm blocked )
456.It Cm sl
457sleep time (in seconds; 127 = infinity)
458.It Cm start
459time started
460.It Cm state
461symbolic process state (alias
462.Cm stat )
463.It Cm svgid
464saved gid from a setgid executable
465.It Cm svuid
466saved uid from a setuid executable
467.It Cm tdev
468control terminal device number
469.It Cm tdpri
470LWKT thread priority (0-31, 31 highest), and critical section count
471.It Cm tid
472thread ID (aka lightweight process ID)
473.It Cm time
474accumulated CPU time, user + system (alias
475.Cm cputime )
476.It Cm tpgid
477control terminal process group ID
478.\".It Cm trss
479.\"text resident set size (in Kbytes)
480.It Cm tsess
481control terminal session pointer
482.It Cm tsig
483pending thread signals
484.It Cm tsiz
485text size (in Kbytes)
486.It Cm tt
487control terminal name (two letter abbreviation)
488.It Cm tty
489full name of control terminal
490.It Cm ucomm
491name to be used for accounting (alias
492.Cm comm )
493.It Cm uid
494effective user ID
495.It Cm user
496user name (from uid)
497.It Cm vsz
498virtual size in Kbytes (alias
499.Cm vsize )
500.It Cm wchan
501wait channel (as a symbolic name)
502.It Cm xstat
503exit or stop status (valid only for stopped or zombie process)
504.El
505.Sh FILES
506.Bl -tag -width /var/db/kvm_kernel.db -compact
507.It Pa /dev/kmem
508default kernel memory
509.It Pa /var/run/dev.db
510/dev name database
511.It Pa /var/db/kvm_kernel.db
512system namelist database
513.It Pa /boot/kernel
514default system namelist
515.It Pa /proc
516the mount point of
517.Xr procfs 5
518.El
519.Sh SEE ALSO
520.Xr kill 1 ,
521.Xr w 1 ,
522.Xr kvm 3 ,
523.Xr strftime 3 ,
524.Xr procfs 5 ,
525.Xr pstat 8 ,
526.Xr sysctl 8
527.Sh HISTORY
528The
529.Nm
530command appeared in
531.At v4 .
532.Sh BUGS
533Since
534.Nm
535cannot run faster than the system and is run as any other scheduled
536process, the information it displays can never be exact.
537