1.ig \" -*-mode:nroff-*-
2Copyright (c) 2002-2004, 2009, Apple Computer, Inc.  All rights reserved.
3
4@APPLE_LICENSE_HEADER_START@
5
6The contents of this file constitute Original Code as defined in and
7are subject to the Apple Public Source License Version 1.1 (the
8"License").  You may not use this file except in compliance with the
9License.  Please obtain a copy of the License at
10http://www.apple.com/publicsource and read it before using this file.
11
12This Original Code and all software distributed under the License are
13distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
14EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
15INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
16FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
17License for the specific language governing rights and limitations
18under the License.
19
20@APPLE_LICENSE_HEADER_END@
21..
22.TH top 1 "top"
23.hy 1
24.SH NAME
25top - display and update sorted information about processes
26.SH SYNOPSIS
27.TP
28.BR top
29.RB [ \-a
30|
31.B \-d
32|
33.B \-e
34|
35.B \-c
36.IR <mode> ]
37.br
38.RB [ \-F
39| 
40.BR \-f ]
41.br
42.RB [ \-h ]
43.br
44.RB [ \-i
45.IR <interval> ]
46.br
47.RB [ \-l
48.IR <samples> ]
49.br
50.RB [ \-ncols
51.IR <columns> ]
52.br
53.RB [ \-o
54.IR <key> ]
55.RB [ \-O
56.IR <skey> ]
57.br
58.RB [ \-R
59|
60.BR \-r ]
61.br
62.RB [ \-S ]
63.br
64.RB [ \-s
65.IR <delay> ]
66.br
67.RB [ \-n 
68.IR <nprocs> ]
69.br
70.RB [ \-stats 
71.IR <keys> ]
72.br
73.RB [ \-pid
74.IR <processid> ]
75.br
76.RB [ \-user
77.IR <username> ]
78.br
79.RB [ \-U
80.IR <username> ]
81.br
82.RB [ \-u ]
83.SH DESCRIPTION
84The
85.B top
86program periodically displays a sorted list of system processes.
87The default sorting key is pid, but other keys can be used instead.
88Various output options are available.
89.SH OPTIONS
90Command line option specifications are processed from left to right.
91Options can be specified more than once.
92If conflicting options are specified, later specifications override earlier
93ones.
94This makes it viable to create a shell alias for
95.B top
96with preferred defaults specified, then override those preferred defaults as
97desired on the command line.
98.TP
99.B \-a
100Equivalent to -c a.
101.TP
102.BI \-c " " "" <mode>
103Set event counting mode to
104.IR <mode> .
105The supported modes are:
106.RS
107.TP
108.B a
109Accumulative mode.
110Count events cumulatively, starting at the launch of
111.BR top .
112Calculate CPU usage and CPU time since the launch of
113.BR top .
114.TP
115.B d
116Delta mode.
117Count events relative to the previous sample.
118Calculate CPU usage since the previous sample.
119This mode by default disables the memory object map reporting.
120The memory object map reporting may be re-enabled with the -r option or the interactive r command.
121.TP
122.B e
123Absolute mode.
124Count events using absolute counters.
125.TP
126.B n
127Non-event mode (default).
128Calculate CPU usage since the previous sample.
129.RE
130.TP
131.B \-d
132Equivalent to -c d.
133.TP
134.B \-e
135Equivalent to -c e.
136.TP
137.B \-F
138Do not calculate statistics on shared libraries, also known as frameworks.
139.TP
140.B \-f 
141Calculate statistics on shared libraries, also known as frameworks (default).
142.TP
143.B \-h
144Print command line usage information and exit.
145.TP
146.BI \-i " " "" <interval>
147Update framework (-f) info every 
148.I <interval> 
149samples; see the 
150.B PERFORMANCE vs. ACCURACY
151section below for more details.
152.TP
153.BI \-l " " "" <samples>
154Use logging mode and display
155.I <samples>
156samples, even if standard output is a terminal.
1570 is treated as infinity.
158Rather than redisplaying, output is periodically printed in raw form.
159Note that the first sample displayed will have an invalid %CPU displayed
160for each process, as it is calculated using the delta between samples.
161.TP
162.BI \-ncols " " " " <columns>
163Display 
164.I <columns>
165when using logging mode.
166The default is infinite.  The number must be > 0 or an error will occur.
167.TP
168.BI \-n " " "" <nprocs>
169Only display up to
170.I <nprocs>
171processes.
172.TP
173.BI \-O " " "" <skey>
174Use
175.I <skey>
176as a secondary key when ordering the process display.
177See
178.B -o
179for key names
180.RB ( pid
181is the default).
182.TP
183.BI \-o " " "" <key>
184.RS
185Order the process display by sorting on
186.I <key>
187in descending order.
188A
189.B +
190or
191.B -
192can be prefixed to the key name to specify ascending or descending order,
193respectively.
194The supported keys are:
195.TP
196.B pid
197Process ID (default).
198.TP
199.B command
200Command name.
201.TP
202.B cpu
203CPU usage.
204.TP
205.B csw
206Number of context switches.
207.TP
208.B time
209Execution time.
210.TP
211.B threads
212alias:
213.B th
214.br
215Number of threads (total/running).
216.TP
217.B ports
218alias:
219.B prt
220.br
221Number of Mach ports.
222.TP
223.B mregion
224alias:
225.B mreg, reg
226.br
227Number of memory regions.
228.TP
229.B mem
230Internal memory size.
231.TP
232.B rprvt
233Resident private address space size.
234.TP
235.B purg
236Purgeable memory size.
237.TP
238.B vsize
239Total memory size.
240.TP
241.B vprvt
242Private address space size.
243.TP
244.B kprvt
245Private kernel memory size.
246.TP
247.B kshrd
248Shared kernel memory size.
249.TP
250.B pgrp
251Process group id.
252.TP
253.B ppid
254Parent process id.
255.TP
256.B state 
257alias:
258.B pstate
259.br
260Process state.
261.TP
262.B uid
263User ID.
264.TP 
265.B wq 
266alias:
267.B #wq, workqueue
268.br
269The workqueue total/running.
270.TP 
271.B faults 
272alias:
273.B fault
274.br
275The number of page faults.
276.TP
277.B cow
278alias:
279.B cow_faults
280.br
281The copy-on-write faults.
282.TP
283.B user
284alias:
285.B username
286Username.
287.TP
288.B msgsent
289.br
290Total number of mach messages sent.
291.TP 
292.B msgrecv
293.br
294Total number of mach messages received.
295.TP
296.B sysbsd
297Total BSD syscalls.
298.TP
299.B sysmach
300Total Mach syscalls.
301.TP
302.B pageins
303Total pageins.
304.RE
305.TP
306.BI \-R " " ""
307Do not traverse and report the memory object map for each process.
308.TP
309.BI \-r " " ""
310Traverse and report the memory object map for each process (default).
311.TP
312.BI \-S " " ""
313Display the global statistics for swap and purgeable memory.
314.TP
315.BI \-s " " "" <delay>
316Set the delay between updates to
317.I <delay>
318seconds.
319The default delay between updates is 1 second.
320.TP
321.BI \-stats " " "" <keys>
322Only display the comma separated statistics.  See the -o flag for the valid
323.IR <keys> .
324.TP
325.BI \-pid " " "" <processid>
326Only display 
327.IR <processid>
328in top.
329.TP
330.BI \-user " " "" <user>
331Only display processes owned by
332.IR <user> .
333.TP
334.BI \-U " " "" <user>
335This is an alias for -user.
336.TP
337.BI \-u
338This is an alias equivalent to: -o cpu -O time.
339
340.SH DISPLAY
341The first several lines of the
342.B top
343display show various global state.
344All of the information is labeled.
345Following is an alphabetical list of global state fields and their descriptions.
346.TP 12
347.B CPU
348Percentage of processor usage, broken into user, system, and idle components.
349The time period for which these percentages are calculated depends on the event
350counting mode.
351.TP 12
352.B Disks
353Number and total size of disk reads and writes.
354.TP 12
355.B LoadAvg
356Load average over 1, 5, and 15 minutes.
357The load average is the average number of jobs in the run queue.
358.TP 12
359.B MemRegions
360Number and total size of memory regions, and total size of memory regions broken
361into private (broken into non-library and library) and shared components.
362.TP 12
363.B Networks
364Number and total size of input and output network packets.
365.TP 12
366.B PhysMem
367Physical memory usage, broken into wired, active, inactive, used, and free
368components.
369.TP 12
370.B Procs
371Total number of processes and number of processes in each process state.
372.TP 12
373.B SharedLibs
374Resident sizes of code and data segments, and link editor memory usage.
375.TP 12
376.B Threads
377Number of threads.
378.TP 12
379.B Time
380Time, in H:MM:SS format.
381When running in logging mode Time is in YYYY/MM/DD HH:MM:SS format by default, but may be overridden with accumulative mode.
382When running in accumulative event counting mode, the Time is in HH:MM:SS since the beginning of the top process.
383.TP 12
384.B VirtMem
385Total virtual memory, virtual memory consumed by shared libraries, and number of
386pageins and pageouts.
387.TP 12
388.B Swap
389Swap usage: total size of swap areas, amount of swap space in use and amount
390of swap space available.
391.TP 12
392.B Purgeable
393Number of pages purged and number of pages currently purgeable.
394.PP
395Below the global state fields, a list of processes is displayed.
396The fields that are displayed depend on the options that are set.
397The pid field displays the following for the architecture:
398.TP 14
399.B +
400for 64-bit native architecture, or
401.B -
402for 32-bit native architecture, or
403.B *
404for a non-native architecture.
405.TP 14
406.SH INTERACTION
407When
408.B top
409is run in interactive (non-logging) mode, it is possible to control the output of
410.BR top ,
411as well as interactively send signals to processes.
412The interactive command syntax is terse.
413Each command is one character, followed by 0 to 2 arguments.
414Commands that take arguments prompt interactively for the arguments, and where
415applicable, the default value is shown in square brackets.
416The default value can be selected by leaving the input field blank and pressing
417enter.
418.B ^G
419escapes the interactive argument prompt, and has the same effect as leaving
420the input field blank and pressing enter.
421.PP
422The following commands are supported:
423.TP
424.BR ?
425Display the help screen.
426Any character exits help screen mode.
427This command always works, even in the middle of a command.
428.TP
429.B ^L
430Redraw the screen.
431.TP
432.BI c <mode>
433Set output mode to
434.IR <mode> .
435The supported modes are:
436.RS
437.TP
438.B a
439Accumulative mode.
440.TP
441.B d
442Delta mode.
443.TP
444.B e
445Event mode.
446.TP
447.B n
448Non-event mode.
449.RE
450.TP
451.BI O <skey>
452Use
453.I <skey>
454as a secondary key when ordering the process display.
455See the
456.B -o
457option for key names.
458.TP
459.BI o <key>
460.RS
461Order the process display by sorting on
462.I <key>
463in descending order.
464A
465.B +
466or
467.B -
468can be prefixed to the key name to specify ascending or descending order,
469respectively.
470The supported keys and alises are listed with the -o option above.
471
472.RE
473.TP
474.B q
475Quit.
476.TP
477.B r
478Toggle traversal and reporting of the memory object map for each process.
479.TP
480.BI S <signal> "" <pid>
481Send
482.I <sig>
483to
484.IR <pid>.
485.I <sig>
486can be specified either as a number or as a name (for example,
487.BR HUP ).
488The default signal starts out as
489.BR TERM .
490Each time a signal is successfully sent, the default signal is updated to be
491that signal.
492.I <pid>
493is a process id.
494.TP
495.BI s <delay>
496Set the delay between updates to
497.I <delay>
498seconds.
499.TP
500.BI U <user>
501Only display processes owned by
502.IR <user> .
503Either the username or uid number can be specified.
504To display all processes, press enter without entering a username or uid number.
505.SH PERFORMANCE vs. ACCURACY
506Calculating detailed memory statistics is fundamentally resource-intensive.
507To reduce the cpu usage in top, the
508.I \-i
509parameter has been introduced to allow the user to tune this tradeoff.  With the 
510default value of 10, framework stats will be updated once every 10 samples.
511Specifying
512.I \-i
5131 will result in the most accurate display, at the expense of system resources.
514.SH N/A - Not Available
515When this occurs in a stat it's caused by the memory object map reporting being 
516disabled.  Memory object map reporting is disabled by default in delta mode, but 
517may be optionally enabled via -r or the interactive
518.B r 
519command.  To enable the -r option use it after any -c mode options.
520.SH EXAMPLES
521.TP
522top -o cpu -O +rsize -s 5 -n 20
523Sort the processes according to CPU usage (descending) and resident memory size
524(ascending), sample and update the display at 5 second intervals, and limit the
525display to 20 processes.
526.TP
527top -c d
528Run top in delta mode.
529
530.TP
531top -stats pid,command,cpu,th,pstate,time
532Display only the specified statistics, regardless of any growth of the terminal.
533If the terminal is too small, only the statistics that fit will be displayed.
534
535.SH SEE ALSO
536kill(2),
537vm_stat(1),
538signal(3),
539vmmap(1)
540