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