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 cpu_me 206CPU time charged to me by other processes. 207.TP 208.B cpu_others 209CPU time charged to other processes by me. 210.TP 211.B csw 212Number of context switches. 213.TP 214.B time 215Execution time. 216.TP 217.B threads 218alias: 219.B th 220.br 221Number of threads (total/running). 222.TP 223.B ports 224alias: 225.B prt 226.br 227Number of Mach ports. 228.TP 229.B mregion 230alias: 231.B mreg, reg 232.br 233Number of memory regions. 234.TP 235.B mem 236Internal memory size. 237.TP 238.B rprvt 239Resident private address space size. 240.TP 241.B purg 242Purgeable memory size. 243.TP 244.B vsize 245Total memory size. 246.TP 247.B vprvt 248Private address space size. 249.TP 250.B kprvt 251Private kernel memory size. 252.TP 253.B kshrd 254Shared kernel memory size. 255.TP 256.B pgrp 257Process group id. 258.TP 259.B ppid 260Parent process id. 261.TP 262.B state 263alias: 264.B pstate 265.br 266Process state. 267.TP 268.B uid 269User ID. 270.TP 271.B wq 272alias: 273.B #wq, workqueue 274.br 275The workqueue total/running. 276.TP 277.B faults 278alias: 279.B fault 280.br 281The number of page faults. 282.TP 283.B cow 284alias: 285.B cow_faults 286.br 287The copy-on-write faults. 288.TP 289.B user 290alias: 291.B username 292Username. 293.TP 294.B msgsent 295.br 296Total number of mach messages sent. 297.TP 298.B msgrecv 299.br 300Total number of mach messages received. 301.TP 302.B sysbsd 303Total BSD syscalls. 304.TP 305.B sysmach 306Total Mach syscalls. 307.TP 308.B pageins 309Total pageins. 310.TP 311.B boosts 312The number of boosts held by the process. 313This is followed by the number of times the process has transitioned from unboosted to boosted in brackets. 314An asterisk before the value indicates that the process was able to send boosts at some point since the previous update. 315For more information about boosts, see xpc_transaction_begin(3). 316.RE 317.TP 318.BI \-R " " "" 319Do not traverse and report the memory object map for each process. 320.TP 321.BI \-r " " "" 322Traverse and report the memory object map for each process (default). 323.TP 324.BI \-S " " "" 325Display the global statistics for swap and purgeable memory. 326.TP 327.BI \-s " " "" <delay> 328Set the delay between updates to 329.I <delay> 330seconds. 331The default delay between updates is 1 second. 332.TP 333.BI \-stats " " "" <keys> 334Only display the comma separated statistics. See the -o flag for the valid 335.IR <keys> . 336.TP 337.BI \-pid " " "" <processid> 338Only display 339.IR <processid> 340in top. 341.TP 342.BI \-user " " "" <user> 343Only display processes owned by 344.IR <user> . 345.TP 346.BI \-U " " "" <user> 347This is an alias for -user. 348.TP 349.BI \-u 350This is an alias equivalent to: -o cpu -O time. 351 352.SH DISPLAY 353The first several lines of the 354.B top 355display show various global state. 356All of the information is labeled. 357Following is an alphabetical list of global state fields and their descriptions. 358.TP 12 359.B CPU 360Percentage of processor usage, broken into user, system, and idle components. 361The time period for which these percentages are calculated depends on the event 362counting mode. 363.TP 12 364.B Disks 365Number and total size of disk reads and writes. 366.TP 12 367.B LoadAvg 368Load average over 1, 5, and 15 minutes. 369The load average is the average number of jobs in the run queue. 370.TP 12 371.B MemRegions 372Number and total size of memory regions, and total size of memory regions broken 373into private (broken into non-library and library) and shared components. 374.TP 12 375.B Networks 376Number and total size of input and output network packets. 377.TP 12 378.B PhysMem 379Physical memory usage, broken into wired, active, inactive, used, and free 380components. 381.TP 12 382.B Procs 383Total number of processes and number of processes in each process state. 384.TP 12 385.B SharedLibs 386Resident sizes of code and data segments, and link editor memory usage. 387.TP 12 388.B Threads 389Number of threads. 390.TP 12 391.B Time 392Time, in H:MM:SS format. 393When running in logging mode Time is in YYYY/MM/DD HH:MM:SS format by default, but may be overridden with accumulative mode. 394When running in accumulative event counting mode, the Time is in HH:MM:SS since the beginning of the top process. 395.TP 12 396.B VirtMem 397Total virtual memory, virtual memory consumed by shared libraries, and number of 398pageins and pageouts. 399.TP 12 400.B Swap 401Swap usage: total size of swap areas, amount of swap space in use and amount 402of swap space available. 403.TP 12 404.B Purgeable 405Number of pages purged and number of pages currently purgeable. 406.PP 407Below the global state fields, a list of processes is displayed. 408The fields that are displayed depend on the options that are set. 409The pid field displays the following for the architecture: 410.TP 14 411.B + 412for 64-bit native architecture, or 413.B - 414for 32-bit native architecture, or 415.B * 416for a non-native architecture. 417.TP 14 418.SH INTERACTION 419When 420.B top 421is run in interactive (non-logging) mode, it is possible to control the output of 422.BR top , 423as well as interactively send signals to processes. 424The interactive command syntax is terse. 425Each command is one character, followed by 0 to 2 arguments. 426Commands that take arguments prompt interactively for the arguments, and where 427applicable, the default value is shown in square brackets. 428The default value can be selected by leaving the input field blank and pressing 429enter. 430.B ^G 431escapes the interactive argument prompt, and has the same effect as leaving 432the input field blank and pressing enter. 433.PP 434The following commands are supported: 435.TP 436.BR ? 437Display the help screen. 438Any character exits help screen mode. 439This command always works, even in the middle of a command. 440.TP 441.B ^L 442Redraw the screen. 443.TP 444.BI c <mode> 445Set output mode to 446.IR <mode> . 447The supported modes are: 448.RS 449.TP 450.B a 451Accumulative mode. 452.TP 453.B d 454Delta mode. 455.TP 456.B e 457Event mode. 458.TP 459.B n 460Non-event mode. 461.RE 462.TP 463.BI O <skey> 464Use 465.I <skey> 466as a secondary key when ordering the process display. 467See the 468.B -o 469option for key names. 470.TP 471.BI o <key> 472.RS 473Order the process display by sorting on 474.I <key> 475in descending order. 476A 477.B + 478or 479.B - 480can be prefixed to the key name to specify ascending or descending order, 481respectively. 482The supported keys and alises are listed with the -o option above. 483 484.RE 485.TP 486.B q 487Quit. 488.TP 489.B r 490Toggle traversal and reporting of the memory object map for each process. 491.TP 492.BI S <signal> "" <pid> 493Send 494.I <sig> 495to 496.IR <pid>. 497.I <sig> 498can be specified either as a number or as a name (for example, 499.BR HUP ). 500The default signal starts out as 501.BR TERM . 502Each time a signal is successfully sent, the default signal is updated to be 503that signal. 504.I <pid> 505is a process id. 506.TP 507.BI s <delay> 508Set the delay between updates to 509.I <delay> 510seconds. 511.TP 512.BI U <user> 513Only display processes owned by 514.IR <user> . 515Either the username or uid number can be specified. 516To display all processes, press enter without entering a username or uid number. 517.SH PERFORMANCE vs. ACCURACY 518Calculating detailed memory statistics is fundamentally resource-intensive. 519To reduce the cpu usage in top, the 520.I \-i 521parameter has been introduced to allow the user to tune this tradeoff. With the 522default value of 10, framework stats will be updated once every 10 samples. 523Specifying 524.I \-i 5251 will result in the most accurate display, at the expense of system resources. 526.SH N/A - Not Available 527When this occurs in a stat it's caused by the memory object map reporting being 528disabled. Memory object map reporting is disabled by default in delta mode, but 529may be optionally enabled via -r or the interactive 530.B r 531command. To enable the -r option use it after any -c mode options. 532.SH EXAMPLES 533.TP 534top -o cpu -O +rsize -s 5 -n 20 535Sort the processes according to CPU usage (descending) and resident memory size 536(ascending), sample and update the display at 5 second intervals, and limit the 537display to 20 processes. 538.TP 539top -c d 540Run top in delta mode. 541 542.TP 543top -stats pid,command,cpu,th,pstate,time 544Display only the specified statistics, regardless of any growth of the terminal. 545If the terminal is too small, only the statistics that fit will be displayed. 546 547.SH SEE ALSO 548kill(2), 549vm_stat(1), 550signal(3), 551vmmap(1) 552