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