.ig igEND . manual page for NEW top . Copyright (c) 2002, by: JC Warner & Associates, Ltd. . . Permission is granted to copy, distribute and/or modify this document . under the terms of the GNU Free Documentation License, Version 1.1 or . any later version published by the Free Software Foundation; . with no Front-Cover Texts, no Back-Cover Texts, and with the following . Invariant Sections (and any sub-sections therein): . this .ig-section . DIFFERENCES / New Features . STUPID TRICKS Sampler . NOTES and Rantings . AUTHOR . . A copy of the Free Documentation License is included in the section . entitled "GNU Free Documentation License". . . [ that section is found near the end of this document & ] . [ can be made printable by disabling the .ig directive! ] . .igEND . .\" Setup //////////////////////////////////////////////////////////////// \# ** Comment out '.nr' or set to 0 to eliminate WIDTH fiddlin' ! .nr half_xtra 4 . . ll +(\n[half_xtra] + \n[half_xtra]) . \# Special right justify macros --------------------- \# - right justify start . de Rjb . ll -\n[half_xtra] . rj \\$1 .. \# - right justify end . de Rje . ll +\n[half_xtra] .. \# Jimmy's darn Bullet style ------------------------ . de Jbu . IP "-" 3 .. \# - bullet continuation paragraph . de Jp . IP "" 3 .. \# New features/differences style ------------------- . de New . IP "-*-" 5 .. \# Screen image style ------------------------------- . de Img . IP "" -4 . Rjb 26 .. \# Code image style --------------------------------- . de ImgC . IP "" -4 . Rjb 20 .. \# Screen narrative (wide narrative) style ---------- . de Scr .PP . in -4 .. \# Special emphasis --------------------------------- . de Zzz . ce -*- -*- -*- .. . \# Commonly used strings (for consistency) ---------- \# - a real em-dash, darn-it . ds EM \ \fB\-\-\ \fR \# - these two are for chuckles, makes great grammar . ds Me top . ds ME \fBtop\fR \# - hey, these two ain't too shabby, either . ds Us this\ \*(Me . ds US \fBthis\fR\ \*(Me \# - other misc strings for consistent usage/emphasis . ds F \fIOff\fR . ds O \fIOn\fR . . ds AM alternate\-display mode . ds AS asterisk ('*') . ds CF configuration file . ds CI interactive command . ds CO command\-line option . ds CW \'current' window . ds FM full\-screen mode . ds MP \fBphysical\fR memory . ds MS \fBshared\fR memory . ds MV \fBvirtual\fR memory . ds NT \fBNote\fR: . ds PU CPU . ds Pu cpu . ds SA summary area . ds TA task area . ds TD task display . ds TW task window \# - xref's that depend on commands or topic names . ds XC See the . ds Xc see the . ds XT See topic . ds Xt see topic . .\" ////////////////////////////////////////////////////////////////////// .\" ---------------------------------------------------------------------- .TH TOP 1 "September 2002" "Linux" "Linux User's Manual" .\" ---------------------------------------------------------------------- .\" ---------------------------------------------------------------------- .SH NAME .\" ---------------------------------------------------------------------- top \- display Linux tasks .\" ---------------------------------------------------------------------- .SH SYNOPSIS .\" ---------------------------------------------------------------------- \*(ME \-\fBhv\fR | \-\fBbcisS\fR \-\fBd\fI delay\fR \-\fBn\fI iterations\fR \-\fBp\fI pid\fR [,\fI pid\fR ...] The traditional switches '-' and whitespace are optional. .\" ---------------------------------------------------------------------- .SH DESCRIPTION .\" ---------------------------------------------------------------------- The \*(ME program provides a dynamic real-time view of a running system. It can display\fB system\fR summary information as well as a list of\fB tasks\fR currently being managed by the Linux kernel. The types of system summary information shown and the types, order and size of information displayed for tasks are all user configurable and that configuration can be made persistent across restarts. The program provides a limited interactive interface for process\fB manipulation\fR as well as a much more extensive interface for personal\fB configuration\fR \*(EM encompassing every aspect of its operation. And while \*(ME is referred to throughout this document, you are free to name the program anything you wish. That new name, possibly an alias, will then be reflected on \*(Me's display and used when reading and writing a \*(CF. .\" ---------------------------------------------------------------------- .SH DIFFERENCES / New Features .\" ---------------------------------------------------------------------- With no basis for comparison, those new to \*(ME might want to skip to the next section. For those who have used a prior version, fasten your seat-belts and hold on tight as we review the features of \*(US. Details regarding their exploitation will be covered in later sections. .\" ...................................................................... .SS Expanded Configurable Display Support .New In an SMP environment, screen height may be insufficient to simultaneously accommodate all \*(Pu states plus a meaningful \*(TD. So with \*(Us, you can alternate between a\fB summary\fR display or one showing\fB each \*(Pu\fR separately. No longer must this choice be irrevocably made at startup. .New There are new fields and with \*(Us,\fB any\fR field is selectable for sorting. Plus, your sorted column can be\fB instantly reversed\fR with just a single keystroke. .New You may optionally apply 2 distinct types of\fB highlighting\fR to running\fB tasks\fR and/or\fB sorted columns\fR. With \*(Us, you'll be able to instantly spot running tasks and always know the current sort field. .New While you could continue to use the more familiar (and boring)\fB monochrome display\fR, you might want to try \*(Us's new\fB color display\fR. You can even create your own\fB unique colors\fR used in\fI summaries\fR,\fI messages\fR,\fI headings\fR and\fI tasks\fR, each of which can be made\fB persistent\fR until you choose to change them. .New Up to\fB four separate windows\fR can be displayed simultaneously, giving you four separate ways to\fB sort\fI and\fB view\fR the tasks currently cluttering up your system. You could have one view by\fB pids\fR, another by\fB \*(Pu usage\fR, yet another showing\fB memory consumption\fR. You get the idea... Each window comes with pre-configured (but user configurable)\fB fields\fR and you can\fB size\fR each window individually. Virtually every one of \*(Us's options (summaries, fields, colors, sorted column, etc.) is\fB separately configurable\fR for each of those four windows. Heck, you can even\fB change\fR a window's name, if you don't care for \*(Me's choices. Your changes will be reflected not only when you're in what \*(Me calls\fB \*(AM\fR but also on his special new 'Windows' help screen. And, [ ** Drum-Roll + Ta-Da ** ] with just one keystroke you can quickly\fB switch\fR between full-screen and multiple window modes! Or, with a different keystroke, toggle a single window \*F for now, then \*O again later!! .ce 2 ( come on, NONE of that's really TRUE, is it? ) ( ** you betcha' it is, AND there's MORE ! ** ) .\" ...................................................................... .SS Enhanced Field/Column Management .New Many Field/Column names have been changed to make them more intuitive, more self-descriptive. And with \*(Us you won't be fooled with field choices that are "not yet implemented". .New Task memory statistics are more meaningful\fI and\fR more accurate\fR. .New You'll finally have complete\fB display integrity\fR regardless of field selections, their order or screen width. And\fB that\fR means the\fI command\fR column no longer need be kept as the right-most field, lest your screen turn to when all the following columns get misaligned. .\" ...................................................................... .SS Customization Flexibility .New .I All\fR of your configuration choices can be\fB preserved\fR in a personal \*(CF, including any changes made on a per-window basis. Thus, once you personalize things they\fB remain personalized\fR until you decide to change them again. This \*(Me has been completely cured of: .Rjb 2 i-cant-remember-so-please-do-that-all-over-again ( and again, and again ... ) .Rje The bottom line is this:\ \ if you save your configuration before quitting \*(Me, upon restart the display will appear\fB exactly\fR as you left it. And\fB that\fR means you no longer have to keep \*(Me running until-the-end-of-time (ok, a long time anyway), lest your customizations go bye-bye. .New You have complete program\fB naming freedom\fR with no internal ties to a specific personal \*(CF. Symbolic links could be used to establish different \*(CFs reflecting the different personalities of your customized "\*(Mes", under whatever aliases you've used. Thus, you could have an alias for running \*(Me in 'Batch mode', another for when you work from the Linux console and maybe a third used with X-Windows. All of that, yet still just a single binary image! .\" ...................................................................... .SS What?\fR\ \ A\fB Stupid Tricks\fR Section?? .New Given all the enhanced capability of \*(Us, why not have a stupid tricks section? Just remember, \*(Us will never judge you, just support you. Ultimately, you'll decide when the time's right to sock-it-to-\fBm'self\fR and actually try that stuff! .\" ---------------------------------------------------------------------- .SH 0. OVERVIEW, Operation and Documentation .\" ---------------------------------------------------------------------- .Scr When you start \*(Us for the first time, you'll be presented with the traditional screen elements: 1) Summary Area; 2) Message/Prompt Line; 3) Columns Header; 4) Task Area. But even out-of-the-box, there are numerous subtle differences, compared to the former top. .SS Highlighting .I Summary_Area\fR: It's retina-friendly with\fB no\fR highlighting for load/uptime and only\fB values\fR highlighted for other elements. .I Task_Area\fR: Tasks\fB running\fR (or ready to run) will be highlighted, and bold is only one way of emphasizing such processes. .SS Content/Labels .I Summary_Area\fR: The program\fB name\fR is shown (symlinks/aliases, remember?). The Cpu\fI(s)\fR state\fR\fB label\fR hints at other possibilities (smp folks, stand by). The\fB memory\fR stats use a lower case '\fBk\fR' (making numbers and letters more distinct). .I Columns_Header\fR: Shows a\fB new\fR field and some\fB changed\fR labels (unseen to the right). Precious horizontal space is no longer squandered. .Scr All of that, however, is just the tip of the old iceberg. So please, do not touch that dial! You may, however, peruse the following screen representation before we acknowledge \*(Us's default settings and the topics which follow in this document... .Img +\fB--------------------------------------\fR+ 1.\fB Summary Area .\fBl\fR |top - 15:37:33 up 16:16, 9 users, lo: via 4 toggles .\fBt\fR |Tasks: \fB 73\fR total, \fB 3\fR running, \fB 70\fR sle: l, t, 1, m .\fB1\fR |Cpu(s) state: \fB 6.6%\fR user, \fB 2.3%\fR syst:\fB ------------> .\fBm\fR |Mem: \fB 126588k\fR total, \fB 116504k\fR used,: " |Swap: \fB 265032k\fR total, \fB 8232k\fR used,: 2.\fB Msg/Pmt line --->\fR |______________________________________: 3.\fB Columns Header ->\fR |\fI__PID_USER______PR__NI_%CPU____TIME+__\fR: 4.\fB Task Area ------>\fR |\fB 7328 root 10 0 0.6 0:00.09\fR : via a bunch of > | 7326 root 9 0 0.0 0:00.06 : commands and > | 7324 root 8 0 0.0 0:00.00 : toggles ! > | 7321 root 9 0 0.0 0:00.05 : ... | 7320 root 9 0 0.0 0:00.00 : | 7316 jfvwm 8 0 0.0 0:00.00 : ( top provides\fI four\fR )| 7315 jfvwm 9 0 0.0 0:00.01 : ( \fIseparate\fR fld grps )| 7312 root 9 0 0.0 0:00.00 : ( or windows &\fB each\fR )| 6725 root 9 0 0.0 0:00.03 : ( could be shown in )| 6232 root 7 -10 1.9 4:25.86 : ( this way, or show )| 5561 root 9 0 0.0 0:00.33 : (\fB all concurrently\fR! )| 5560 xfs 9 0 0.0 0:00.01 : | 5325 root 9 0 0.0 0:00.05 : ( will\fI change\fR often )| 4634 root 9 0 0.0 0:04.23 : -*-\fBRow hilites-->\fR |\fB 1803 jgnome 9 0 0.0 1:55.30\fR : ( depending on your )| 1708 root 9 0 0.0 0:00.27 : ( \fIdelay time\fR value! )| 1703 lp 9 0 0.0 0:00.03 : +\fB--------------------------------------\fR+ .Rje .Scr Within the following categories, \*(Us's startup defaults are documented assuming no \*(CF, thus no user customizations. However, items shown with an \*(AS could be overridden through the\fB command line\fR \*(EM a subject soon to be dealt with. \fIGlobal_defaults\fR 'A' - Alt display \fBOff\fR (full-screen) * 'd' - Delay time 3.0 seconds 'I' - Irix mode On\ \ (no, 'solaris' smp) * 'p' - PID monitoring \fBOff\fR * 's' - Secure mode \fBOff\fR (unsecured) \fISummary_Area_defaults\fR 'l' - Load Avg/Uptime On\ \ (thus program name) 't' - Task/Cpu state On\ \ (1+1 lines, see '1') 'm' - Mem/Swap stats On\ \ (2 lines worth) '1' - Single Cpu On\ \ (thus 1 line if smp) \fITask_Area_defaults\fR 'b' - Bold hilite On\ \ (not 'reverse') * 'c' - Command line \fBOff\fR (name, not cmdline) * 'i' - Idle tasks On\ \ (show all tasks) 'R' - Reverse sort On\ \ (sort pids high-to-low) * 'S' - Cumulative time \fBOff\fR (exclude dead children) 'x' - Column hilite \fBOff\fR\ (no, sort field) 'y' - Row hilite On\ \ (yes, running tasks) 'z' - color/mono \fBOff\fR\ (no, colors) Listed below are the remaining topics in this document. Be advised that none of these topics need be read now, or studied later, for a successful\fB close-encounter-of-the-1st-kind\fR with \*(Us. You need remember just the\fB help key\fR ('h' or '?') to survive \*(EM nay, prosper! What about quitting, you ask? Well, of course there's the 'Q' \*(CI, but then \*(Me does quite well with\fB signals\fR. So just zap him with the traditional \fI^C\fR when you're done. .br Oh, almost forgot... You could use \*(Me's own '\fBk\fR' command, to sock-it-to-\fBhisself\fR. .Rjb 4 ( He actually ENJOYS that one, really! ) ( He sees SUICIDE as a chance to rest; ) ( confronted-with-death, top'll LAUGH! ) ( ooh, should 'k' be in stupid tricks? ) .Rje Remaining Table of Contents 1.\fB COMMAND\-LINE Options\fR 2.\fB FIELDS / Columns\fR a. DESCRIPTIONS of Fields b. SELECTING and ORDERING Columns 3.\fB INTERACTIVE Commands\fR a. GLOBAL Commands b. SUMMARY Area Commands c. TASK Area Commands d. COLOR Mapping 4.\fB ALTERNATE\-DISPLAY Mode\fR a. WINDOWS Overview b. COMMANDS for Windows c. EXAMPLES of Windows -*- The 'A' Mode Command Toggle -*- -*- STACKIN' & WHACKIN' Windows -*- -*- ALL TOGETHER Now, Window(s) -*- 5.\fB FILES\fR a. SYSTEM Configuration File b. PERSONAL Configuration File 6.\fB STUPID TRICKS Sampler\fR a. Kernel Magic b. Bouncing Windows c. The Big Bird Window 7.\fB NOTES and Rantings\fR a. The top Binary b. Comparing Performance c. Cost of Stuff d. The top Sources -*- Rant On, and on -*- lastly,\fB the usual\fR... 8. BUGS, 9. HISTORY Former top, 10. AUTHOR, 11. SEE ALSO .\" ---------------------------------------------------------------------- .SH 1. COMMAND-LINE Options .\" ---------------------------------------------------------------------- The command-line syntax for \*(Us consists of: \-\fBhv\fR\ |\ -\fBbcisS\fR\ \-\fBd\fI\ delay\fR\ \-\fBn\fI\ iterations\ \fR\ \-\fBp\fI\ pid\fR\ [,\fIpid\fR...] The typically mandatory switches ('-') and even whitespace are completely optional. .TP 5 \-\fBb\fR :\fB Batch mode\fR operation Starts \*(Me in 'Batch mode', which could be useful for sending output from \*(Me to other programs or to a file. In this mode, \*(Me will\fB not\fR accept input and runs until the iterations limit you've set with the '-n' \*(CO or until killed. Output is plain text suitable for any dumb terminal. .br ( or dumb user, heh heh ) .TP 5 \-\fBc\fR :\fB Command line/Program name\fR toggle Starts \*(Me with the last remembered '\fBc\fR' state reversed. Thus, if \*(Me was displaying command lines, now that field will show program names, and visa versa. \*(XC 'c' \*(CI for additional information. .TP 5 \-\fBd\fR :\fB Delay time\fR interval as:\ \ \fB-d ss.tt\fR (\fIseconds\fR.\fItenths\fR) Specifies the delay between screen updates, and overrides the corresponding value in one's personal \*(CF or the startup default. Later this can be changed with the 'd' or 's' \*(CIs. In all cases, however, such changes are\fI prohibited\fR if \*(Me is running in 'Secure mode', except for root and excluding\fR the 's' \*(CO, documented later in this section. For additional information on 'Secure mode' \*(Xt 5a. SYSTEM Configuration File. Fractional seconds are honored, but a negative number is not allowed. If you set the delay to anything less than 1 second, and you expect \*(Me to do a proper job of it, then you really owe him a\fB scheduling boost\fR. So please renice him using \*(Me's own 'r' \*(CI or more directly with something like the following: nice -n-10 top -d.1 With the ability to highlight\fB running\fR tasks, \*(Us will then produce an amazing display. One representing the results of the kernel's\fB previously unseen\fR scheduling efforts. You may be surprised. .Rjb 2 ( but try not to waste too many \*(Pu cycles ) ( with such sub-second delays & refreshes! ) .Rje .TP 5 \-\fBh\fR :\fB Help\fR Show library version and the usage prompt, then quit. .TP 5 \-\fBi\fR :\fB Idle Processes\fR toggle Starts \*(Me with the last remembered '\fBi\fR' state reversed. When this toggle is \*F, tasks that \fBare\fR idled or zombied will\fB not\fR be displayed. .TP 5 \-\fBn\fR :\fB Number of iterations\fR limit as:\ \ \fB -n number\fR Specifies the maximum number of iterations, or frames, \*(Me should produce before: .Rjb 6 tellin'-a-user-what-he-really-thinks :1 stoppin'-4-a-beer-with-the-guys :2 quittin'-an-going-2-hawaii :3 hangin'-it-up-forever :4 rollin'-deadover :5 [1 -5-5-5-5 = huh?] .Rje .TP 5 \-\fBp\fR :\fB Monitor PIDs\fR as:\fB\ \ -pN1 -pN2 ...\fR\ \ or\fB\ \ -pN1, N2 [,...] Monitor only processes with specified process IDs. This option can be given up to 20 times, or you can provide a comma delimited list with up to 20 pids. For the indecisive, go ahead and co-mingle both approaches. This is a \*(CO \fBonly\fR. And should you wish to return to normal operation, it is not necessary to quit and and restart \*(Us \*(EM just issue the '=' \*(CI. .TP 5 \-\fBs\fR :\fB Secure mode\fR operation Starts \*(Me with \fBsecure mode forced\fR, even for root. This mode is far better controlled through the system \*(CF. In fact, one could argue that this switch has little practical use\fB except\fR to test the nifty\fI delayed message handling\fR \*(Us employs during bootstrap. Oh, you wanna' see? Test thus:\ \ \*(Me\fB d.1s\fR .Rjb 3 ( see, NO '-' & 'sp' but ) ( you\fB can't change delay\fR ) ( in\fI secure mode\fR, silly! ) .Rje Don't bother trying that precise command line with your old top \*(EM he'll completely overlook that 's' \*(CO because he-sees-poorly-but-won't-wear-glasses. .TP 5 \-\fBS\fR :\fB Cumulative time mode\fR toggle Starts \*(Me with the last remembered '\fBS\fR' state reversed. When 'Cumulative mode' is \*O, each process is listed with the \*(Pu time that it\fB and\fR its dead children have used. \*(XC 'S' \*(CI for additional information regarding this mode. .TP 5 \-\fBv\fR :\fB Version\fR Show library version and the usage prompt, then quit. .\" ---------------------------------------------------------------------- .SH 2. FIELDS / Columns .\" ---------------------------------------------------------------------- .\" ...................................................................... .SS 2a. DESCRIPTIONS of Fields .\" ---------------------------------------------------------------------- Listed below are \*(Us's\fB available\fR fields. They are always associated with the letter shown, regardless of the position you may have established for them with the 'o' (Order fields) \*(CI, reviewed in the following topic. Any field is selectable as the\fB sort field\fR, and you control whether they are sorted high-to-low or low-to-high. For additional information on sort provisions \*(Xt 3c. TASK Area Commands. .TP 3 a:\fB PID\fR \*(EM Process Id\fR The task's unique process ID, which periodically wraps at 32767, though never restarting at zero. .TP 3 b:\fB PPID\fR \*(EM Parent Process Pid\fR The process ID of a task's parent. .TP 3 c:\fB PGID\fR \*(EM Process Group Id\fR The grouping of tasks which becomes part of job control. It is used for distribution of signals and to arbitrate terminal I/O requests. There is one process group per pipeline. .TP 3 d:\fB UID\fR \*(EM User Id\fR The user ID of the task's owner. .TP 3 e:\fB USER\fR \*(EM User Name The user name of the task's owner. .TP 3 f:\fB GROUP\fR \*(EM Group Name The group name of the task's owner. .TP 3 g:\fB TTY\fR \*(EM Controlling Tty The name of the controlling terminal. This is usually the\fB device\fR (serial port, pty, etc.) from which the process was started, and which it uses for input or output. However, a task need\fI not\fR be associated with a terminal, in which case you'll see '\fB?\fR' displayed. .TP 3 h:\fB PR\fR \*(EM Priority The priority of the task. .TP 3 i:\fB NI\fR \*(EM Nice value The nice value of the task. A\fI negative\fR nice value means\fB higher priority\fR, whereas a\fI positive\fR nice value means\fB lower priority\fR. Zero in this field simply means priority will not be adjusted in determining a task's dispatchability. .TP 3 j:\fB #C\fR \*(EM Last used \*(PU (SMP) A number representing the last used processor. In a true SMP environment this will likely change frequently since the kernel intentionally uses weak affinity. Also, the very act of running \*(Me may break this weak affinity and cause more processes to change \*(PUs more often (because of the extra demand for \*(Pu time). .TP 3 k:\fB %CPU\fR \*(EM \*(PU usage The task's share of the elapsed \*(PU time since the last screen update, expressed as a percentage of total \*(PU time. In a true SMP environment, if 'Irix mode' is \*F, \*(Me will operate in \'Solaris mode' where a task's \*(Pu usage will be divided by the total number of \*(PUs. You toggle 'Irix/Solaris' modes with the 'I' \*(CI. .TP 3 l:\fB TIME\fR \*(EM \*(PU Time Total \*(PU time the task has used since it started. When 'Cumulative mode' is \*O, each process is listed with the \*(Pu time that\fB it\fR and its\fB dead children\fR has used. You toggle 'Cumulative mode' with 'S', which is a \*(CO and an \*(CI. .TP 3 m:\fB TIME+\fR \*(EM \*(PU Time, hundredths The same as 'TIME', but reflecting more granularity through hundredths of a second. .TP 3 n:\fB %MEM\fR \*(EM Memory usage (RES) A task's currently used share of available \*(MP. .TP 3 o:\fB VIRT\fR \*(EM Virtual Image (kb) The total amount of \*(MV used by the task. It includes all code, data and shared libraries plus pages that have been swapped out. VIRT = SWAP + RES. .TP 3 p:\fB SWAP\fR \*(EM Swapped size (kb) The swapped out portion of a task's total \*(MV image. .TP 3 q:\fB RES\fR \*(EM Resident size (kb) The non-swapped \*(MP a task has used. RES = CODE + DATA. .TP 3 r:\fB CODE\fR \*(EM Code size (kb) The amount of \*(MP devoted to executable code, also known as the 'text resident set' size or TRS. .TP 3 s:\fB DATA\fR \*(EM Data+Stack size (kb) The amount of \*(MP devoted to other than executable code, also known as the 'data resident set' size or DRS. .TP 3 t:\fB SHR\fR \*(EM Shared Mem size (kb) The amount of \*(MS used by a task. It simply reflects memory that could be potentially shared with other processes. It is not an assurance that such memory is actually being shared. .TP 3 u:\fB nFLT\fR \*(EM Page Fault count The number of\fB major\fR page faults that have occurred for a task. A page fault occurs when a process attempts to read from or write to a virtual page that is not currently present in its address space. A\fB major\fR page fault is when\fI disk access\fR is involved in making that page available. .TP 3 v:\fB nDRT\fR \*(EM Dirty Pages count The number of pages that have been\fB modified\fR since they were last written to disk. Dirty pages must be written to disk before the corresponding physical memory location can be used for some other virtual page. .TP 3 w:\fB S\fR \*(EM Process Status The status of the task which can be one of: '\fBD\fR' = uninterruptible sleep '\fBR\fR' = running '\fBS\fR' = sleeping '\fBT\fR' = traced or stopped '\fBZ\fR' = zombies Tasks shown as running should be more properly thought of as 'ready to run' \*(EM their task_struct is simply represented on Linux's run-queue. Even without a true SMP machine you may see numerous tasks in this state, depending on \*(Me's delay interval and nice value. .TP 3 x:\fB Command\fR \*(EM Command\fB line\fR or Program\fB name\fR Display the command line used to start a task or the name of the associated program. You toggle between command\fI line\fR and\fI name\fR with 'c', which is both a \*(CO and an \*(CI. When you've chosen to display command\fB lines\fR, processes without a command line (kernel threads) will be shown with only the program name in parentheses, as in this example: \fR( mdrecoveryd ) Either form of display is subject to potential truncation if it's too long to fit in this field's\fI current width\fR. That width depends upon other fields selected, their order and the current screen width. .in +4 \*(NT The 'Command' field/column is\fB unique\fR, in that \fRit is not fixed-width, like all other fields. When displayed, this column will be allocated \fBall remaining screen width\fR to provide for the potential growth of program names into command lines! .in .TP 3 y:\fB WCHAN\fR \*(EM Sleeping in Function Depending on the availability of the kernel link map ('System.map'), this field will show the \fB name\fR or the\fB address\fR of the kernel function in which the task is currently sleeping. Running tasks will display a dash ('-') in this column (but only if you're using the best, the most proper libproc). .in +4 \*(NT By displaying this field, \*(Me's own working set will be increased by over 700Kb. Your only means of reducing that overhead will be to stop and restart \*(Me. .in .TP 3 z:\fB Flags\fR \*(EM Task Flags This column represents the task's current scheduling flags which \*(Us expresses in hexadecimal notation, but with zeros suppressed. These flags are officially documented in . Less formal documentation can also be found on the 'Fields select' and 'Order fields' screens \*(EM the next topic. .\" ...................................................................... .SS 2b. SELECTING and ORDERING Columns .\" ---------------------------------------------------------------------- After pressing the \*(CIs 'f' (Fields select) or \'o' (Order fields) you will be shown a screen containing the current \fBfields string\fR followed by names and descriptions for all fields. Here is a sample\fB fields string\fR from one of \*(Us's four windows/field groups and an explanation of the conventions used: .Jbu Sample fields string: \fIANOPQRSTUVXbcdefgjlmyzWHIK\fR .Jbu The order of displayed fields corresponds to the order of the letters in that string. .Jbu If the letter is\fI upper case\fR the corresponding field itself will then be\fB shown\fR as part of the \*(TD (screen width permitting). This will also be indicated by a leading \*(AS, as in this excerpt: \fR... \fB* K: %CPU = CPU usage \fR l: TIME = CPU Time \fR m: TIME+ = CPU Time, hundredths \fB* N: %MEM = Memory usage (RES) \fB* O: VIRT = Virtual Image (kb) \fR... .TP .B Fields select\fR screen \*(EM the 'f' \*(CI You\fI toggle\fR the\fB display\fR of a field by simply pressing the corresponding letter. .TP .B Order fields\fR screen \*(EM the 'o' \*(CI You\fI move\fR a field to the\fB left\fR by pressing the corresponding\fB upper case\fR letter and to the\fB right\fR with the\fB lower case\fR letter. .\" ---------------------------------------------------------------------- .SH 3. INTERACTIVE Commands .\" ---------------------------------------------------------------------- Listed below is a brief index of commands within categories. Some commands appear more than once \*(EM their meaning or scope may vary depending on the context in which they are issued. 3a.\fI GLOBAL_Commands\fR , ?, =, A, d, G, h, I, k, Q, r, s, W, Z 3b.\fI SUMMARY_Area_Commands\fR l, m, t, 1 3c.\fI TASK_Area_Commands\fR Appearance: b, x, y, z Content: c, f, o, S, u Size: #, i, n Sorting: <, >, F, O, R 3d.\fI COLOR_Mapping\fR , a, b, H, M, q, S, T, w, z, 0 - 7 4b.\fI COMMANDS_for_Windows\fR -, _, =, +, A, a, G, g, w .\" ...................................................................... .SS 3a. GLOBAL Commands The global \*(CIs are\fB always\fR available\fR in both \*(FM and \*(AM. However, some of these \*(CIs are\fB not available\fR when running in 'Secure mode'. If you wish to know in advance whether or not your \*(Me has been secured, simply ask for help and view the system summary on the second line. .TP 7 \ \ \<\fBEnter\fR> or <\fBSpace\fR> :\fIRefresh_Display\fR In truth, these commands do nothing, they are simply ignored. However, they will awaken \*(Me and following receipt of any input the entire display will be repainted within milliseconds. If you have set a large delay interval and wish to see current status, just use either of these keys. .TP 7 \ \ \'\fB?\fR\' or \'\fBh\fR\' :\fIHelp\fR There are\fB two help levels\fR available. The first will provide a reminder of all the basic \*(CIs. If \*(Me is\fI secured\fR, that screen will be abbreviated. Typing 'h' or '?' on that help screen will take you to help for those \*(CIs applicable to \*(AM. .TP 7 \ \ \'\fB=\fR\' :\fIExit_Task_Limits\fR Removes restrictions on which tasks are shown. This command will reverse any 'i' (idle tasks) and 'n' (max tasks) commands that might be active. It also provides for an 'exit' from PID monitoring. See the '-p' \*(CO for a discussion of PID monitoring. When operating in \*(AM this command has a slightly broader meaning. .TP 7 \ \ \'\fBA\fR\' :\fIAlternate_Display_Mode_toggle\fR This command will switch between \*(FM and \*(AM. \*(XT 4. ALTERNATE\-DISPLAY Mode and the 'G' \*(CI for insight into \*(CWs and field groups. .TP 7 *\ \'\fBd\fR\' or \'\fBs\fR\' :\fIChange_Delay_Time_interval\fR You will be prompted to enter the delay time, in seconds, between display updates. Fractional seconds are honored, but a negative number is not allowed. If you set the delay to anything less than 1 second, and you expect \*(Me to do a proper job of it, then you really owe him a\fB scheduling boost\fR. So please renice him using \*(Me's own 'r' \*(CI. Entering 0 causes (nearly) continuous updates, with an unsatisfactory display as the system and tty driver try to keep up with \*(Me's demands. The delay value is inversely proportional to system loading, so set it with care. If at any time you wish to know the current delay time, simply ask for help and view the system summary on the second line. .TP 7 \ \ \'\fBG\fR\' :\fIChoose_Another_Window/Field_Group\fR You will be prompted to enter a number between 1 and 4 designating the window/field group which should be made the \*(CW. You will soon grow comfortable with these 4 windows, especially after experimenting with \*(AM. .TP 7 \ \ \'\fBI\fR\' :\fIIrix/Solaris_Mode_toggle\fR When operating in 'Solaris mode' ('I' toggled \*F), a task's \*(Pu usage will be divided by the total number of \*(PUs. After issuing this command, you'll be informed of the new state of this toggle. .TP 7 *\ \'\fBk\fR\' :\fIKill_a_task\fR You will be prompted for a PID and then the signal to send. The default signal, as reflected in the prompt, is SIGTERM. However, you can send any signal, via number or name. If you wish to\fI abort\fR the kill process, do one of the following depending on your progress: 1) at the\fB pid\fR prompt, just press 2) at the\fB signal\fR prompt, type 0 .TP 7 \ \ \'\fBQ\fR\' :\fIQuit\fR Please note that this is a capital \'Q' since the 'a' and 'w' keys will probably be used frequently and they are adjacent to 'q'. This \*(Me cares deeply for you and does not want you quitting ever \*(EM make that accidentally. .TP 7 *\ \'\fBr\fR\' :\fIRenice_a_Task\fR You will be prompted for a PID and then the value to nice it to. Entering a positive value will cause a process to lose priority. Conversely, a negative value will cause a process to be viewed more favorably by the kernel. .TP 7 \ \ \'\fBW\fR\' :\fIWrite_the_Configuration_File\fR This will save all of your options and toggles plus the current display mode and delay time. By issuing this command just before quitting \*(Me, you will be able restart later in\fB exactly\fR that same state. .TP 7 \ \ \'\fBZ\fR\' :\fIChange_Color_Mapping This key will take you to a separate screen where you can change the colors for the \*(CW, or for all windows. For details regarding this \*(CI \*(Xt 3d. COLOR Mapping. .IP "*" 3 The commands shown with an \*(AS are\fB not available\fR in 'Secure mode', nor will they be shown on the level-1 help screen. .\" ...................................................................... .SS 3b. SUMMARY Area Commands The \*(SA \*(CIs are\fB always available\fR in both \*(FM and \*(AM. They affect the beginning lines of your display and will determine the position of messages and prompts. These commands always impact just the \*(CW/field group. \*(XT 4. ALTERNATE\-DISPLAY Mode and the 'G' \*(CI for insight into \*(CWs and field groups. .TP 7 \ \ \'\fBl\fR\' :\fIToggle_Load_Average/Uptime\fR \*(EM On/Off This is also the line containing the program name (possibly an alias) when operating in \*(FM or the \*(CW name when operating in \*(AM. If you murder-this-line, \*(Me will prosecute you. Later, get-out-of-jail by turning it back on. .TP 7 \ \ \'\fBm\fR\' :\fIToggle_Memory/Swap_Usage\fR \*(EM On/Off This command affects two \*(SA lines. .TP 7 \ \ \'\fBt\fR\' :\fIToggle_Task/Cpu_States\fR \*(EM On/Off This command affects from 2 to many \*(SA lines, depending on the state of the '1' toggle and whether or not \*(Me is running under true SMP. .TP 7 \ \ \'\fB1\fR\' :\fIToggle_Single/Separate_Cpu_States\fR \*(EM On/Off This command affects how the 't' command's Cpu States portion is shown. Although this toggle exists primarily to serve massively-parallel SMP machines, it is not restricted to solely SMP environments. When you see 'Cpu(s) state:' in the \*(SA, the '1' toggle is \*O and all \*(Pu information is gathered in a single line. Otherwise, each \*(Pu is displayed separately as: 'cpu0, cpu1, ...' .in +4 \*(NT If you receive a fatal error message in response to this command, your version of the kernel does not provide separate \*(Pu data in '/proc/stat'. You can either avoid issuing this command or recompile \*(Me with the appropriate #define enabled so the command will be restricted to SMP. .in .PP If the\fB entire\fR \*(SA has been toggled \*F for any window, you would be left with just the\fB message line\fR. In that way, you will have maximized available task rows but (temporarily) sacrificed the program name in \*(FM or the \*(CW name when in \*(AM. .\" ...................................................................... .SS 3c. TASK Area Commands The \*(TA \*(CIs are\fB always\fR available in \*(FM. The \*(TA \*(CIs are\fB never available\fR in \*(AM\fI if\fR the \*(CW's \*(TD has been toggled \*F (\*(Xt 4. ALTERNATE\-DISPLAY Mode). .PP .\" ......................... .B APPEARANCE\fR of \*(TW .PD 0 .TP 7 \ \ \'\fBb\fR\' :\fIBold/Reverse_toggle\fR This command will impact how the 'x' and 'y' toggles are displayed. Further, it will only be available when at least one of those toggles is \*O. .TP 7 \ \ \'\fBx\fR\' :\fIColumn_Highlight_toggle\fR You probably don't need a constant visual reminder of your chosen sort field and \*(Us hopes that you always run with 'column highlight' \*F, due to the cost in path-length. However, if you forget which field \*(Me is sorting this command can serve as a quick visual reminder. .TP 7 \ \ \'\fBy\fR\' :\fIRow_Highlight_toggle\fR Please use this toggle \*(EM highlight running tasks! It's an important insight into your system's health and it was largely this provision that was responsible for your-brand-new-top. You'll make the program author a happy guy. .TP 7 \ \ \'\fBz\fR\' :\fIColor/Monochrome_toggle\fR Switches the \*(CW between your last used color scheme and the older form of black-on-white or white-on-black. This command will alter\fB both\fR the \*(SA and \*(TA but does not affect the state of the 'x', 'y' or 'b' toggles. .PP .\" ......................... .B CONTENT\fR of \*(TW .PD 0 .TP 7 \ \ \'\fBc\fR\' :\fICommand_Line/Program_Name_toggle\fR This command will be honored whether or not the 'Command' column is\fB currently visible\fR. Later, should that field come into view, the change you applied will be seen. .TP 7 \ \ \'\fBf\fR\' and \'\fBo\fR\' :\fIFields_select\fR or \fIOrder_fields\fR These keys display separate screens where you can change which fields are displayed and their order. For additional information on these \*(CIs \*(Xt 2b. SELECTING and ORDERING Columns. .TP 7 \ \ \'\fBS\fR\' :\fICumulative_Time_Mode_toggle\fR When 'Cumulative mode' is \*O, each process is listed with the \*(Pu time that it\fB and\fR its dead children\fR have used. When \*F, programs that fork into many separate tasks will appear less demanding. For programs like 'init' or a shell this is appropriate but for others, like compilers, perhaps not. Experiment with two \*(TWs sharing the same sort field but with different 'S' states and see which representation you prefer. After issuing this command, you'll be informed of the new state of this toggle. If you wish to know in advance whether or not 'Cumulative mode' is in effect, simply ask for help and view the window summary on the second line. .TP 7 \ \ \'\fBu\fR\' :\fIShow_Specific_User_Only\fR You will be prompted to enter the name of the user to display. Thereafter, in that \*(TW only matching User ID's will be shown, or possibly no tasks will be shown. Later, if you wish to monitor all tasks again, re-issue this command but just press at the prompt, without providing a name. .PP .\" ......................... .B SIZE\fR of \*(TW .PD 0 .TP 7 \ \ \'\fBi\fR\' :\fIIdle_Processes_toggle\fR Displays all tasks or just active tasks. When this toggle is \*F, idled or zombied processes will\fB not\fR be displayed. If this command is applied to the last \*(TD when in \*(AM, then it will not affect the window's size, as all prior \*(TDs will have already been painted. .TP 7 \ \ \'\fBn\fR\' or \'#\' :\fISet_Maximum_Tasks\fR You will be prompted to enter the number of tasks to display. The lessor of your number and available screen rows will be used. This is the command that, when used in \*(AM, gives you precise control over the size of each currently visible \*(TD. .PP .\" ......................... .B SORTING\fR of \*(TW .br .in +2 Before using any of these sort provisions, \*(Me suggests that you temporarily turn on column highlighting using the '\fBx\fR' \*(CI. That will help ensure that the actual sort environment matches your intent. The following \*(CIs will\fB only\fR be honored when the current sort field is\fB visible\fR. The sort field might\fI not\fR be visible because: 1) there is insufficient\fI Screen Width\fR 2) the 'f' \*(CI turned it \*F .in .TP 7 \ \ \'\fB<\fR\' :\fIMove_Sort_Field_Left\fR Moves the sort column to the left unless the current sort field is the first field being displayed. .TP 7 \ \ \'\fB>\fR\' :\fIMove_Sort_Field_Right\fR Moves the sort column to the right unless the current sort field is the last field being displayed. .PP .in +2 The following \*(CIs will\fB always\fR be honored whether or not the current sort field is visible. .in .TP 7 \ \ \'\fBF\fR\' or \'\fBO\fR\' :\fISelect_Sort_Field\fR These keys display a separate screen where you can change which field is used as the sort column. If a field is selected which was not previously being displayed, it will be forced \*O when you return to the \*(Me display. However, depending upon your screen width and the order of your fields, this sort field may not be displayable. This \*(CI can be a convienent way to simply verify the current sort field, when running \*(Me with column highlighting turned \*F. .TP 7 \ \ \'\fBR\fR\' :\fIReverse/Normal_Sort_Field_toggle\fR Internally to \*(Me, 'normal' is 'reverse'. .Rjb 1 ...\fBsay what\fR? .Rje Without 'R', \*(Me will sort fields high-to-low. .Rjb 1 ...that's\fI reverse\fR, \*(Me's\fI normal\fR mode! .Rje Try this:\ \ using 'R' you can\fI alternate\fR between high-to-low and low-to-high sorts. Lose no sleep over 'reverse' and 'normal', ok? .PP .in +2 \*(NT Field sorting uses internal values, not those in column display. Thus, the TTY and WCHAN fields will violate strict ASCII collating sequence. .in .\" ...................................................................... .SS 3d. COLOR Mapping .Scr When you issue the 'Z' \*(CI, you are presented with the following screen. On that screen, separate commands (though sometimes related) are in effect. This screen can be used to change the colors in just the \*(CW or in\fB all\fR four windows before returning to the \*(Me display. .P .B Available \*(CIs \fB4\fR upper case letters to select a\fB target\fR \fB8\fR numbers to select a\fB color\fR normal toggles available\fR 'b' :bold/reverse 'z' :color/mono other commands available\fR 'a'/'w' :apply, then go to next/prior :apply and exit 'q' :abandon current changes and exit .Img +\fB--------------------------------------\fR+ this shows you the |\fBHelp for color mapping\fR - procps versio:\fB Target Window ----->\fR |current window:\fB 1:Def\fR : -*- | : a\fB Sample Screen\fR with | color - 04:25:44 up 8 days, 50 min,: \fIyour_current_results\fR | Tasks: \fB 64\fR total, \fB 2\fR running, \fB 62\fR : \'\fBS\fR' color \fB ---->\fR | State cpu0 : \fB 76.5%\fR user, \fB 11.2%\fR s: \'\fBM\fR' color\fIs \fB ---->\fR | \fB _Nasty_Message!___-or-__Input_Promp\fR: \'\fBH\fR' color \fB ---->\fR | \fI __PID_TTY_____PR__NI_%CPU____TIME+_\fR: \'\fBT\fR' color \fB ---->\fR | 17284\fB pts/2\fR 8 0 0.0 0:00.75: + a\fB row\fR for '\fBb\fR'\fB--->\fR | \fB 8601\fB pts/1 7 -10 0.4 0:00.03\fR: -*- | 11005\fB ? \fR 9 0 0.0 0:02.50: addt'l toggles \fB---->\fR | available toggles:\fB b\fR =bold/reverse(: \'\fBb\fR'(bold), '\fBz\fR'(mono) | : |Select\fB target\fR as upper case letter: : instructions for the | \fB S\fR = Summary Data, \fB M\fR = Messages/Pro: target (4) | \fB H\fR = Column Heads, \fB T\fR = Task Informa: |Select\fB color\fR as number: : instructions for the | \fB 0\fR = black, \fB 1\fR = red, \fB 2\fR = green: colors (8) | \fB 4\fR = blue, \fB 5\fR = magenta, \fB 6\fR = cyan,: | : -*- -*- -*- |Selected:\fB target T\fR ;\fB color 1\fR : current\fB target\fR | press 'q' to abort changes to windo: current\fB color\fR | press 'a' or 'w' to commit & change: -*- -*- -*- | : +\fB--------------------------------------\fR+ .Rje .in +4 \*(NT If your use 'a' or 'w' to cycle the targeted window, you\fI will have applied\fR the color scheme that was displayed when you left that window. You can, of course, easily return to any window and reapply different colors or turn colors \*F completely with the 'z' toggle. .in The Color Mapping screen can also be used to change the \*(CW/field group in either \*(FM or \*(AM. Whatever was targeted when 'q' or was pressed\fI will\fR be made\fB current\fR as you return to the \*(Me display. .Zzz .\" ---------------------------------------------------------------------- .SH 4. ALTERNATE\-DISPLAY Mode .\" ---------------------------------------------------------------------- .\" ...................................................................... .SS 4a. WINDOWS Overview You must find comfort with two concepts if you are to successfully manage windows and prosper in \*(AM. .TP .B Field Groups/Windows\fR: .br In \*(FM there is a single window represented by the entire screen. That single window can still be\fI changed\fR to display 1 of 4 different\fB field groups\fR (\*(Xc 'G' \*(CI, repeated below). Each of the 4 field groups has a unique separately configurable\fB \*(SA\fR and its own configurable\fB \*(TA\fR. In \*(AM, those 4 underlying\fB field groups\fR can now be made\fI visible\fR simultaneously, or can be turned \*F individually at your command. The\fB \*(SA\fR will\fI always\fR exist, even if it's only the message line. At any given time only\fI one\fR \*(SA can be displayed. However, depending on your commands, there could be from\fI zero\fR to\fI four\fR separate \*(TDs currently showing on the screen. .TP .B Current Window\fR: .br The \*(CW is the window associated with the \*(SA and the window to which task related commands are always directed. Since in \*(AM you can toggle the \*(TD \*F, some commands might be restricted for the \*(CW. A further complication arises when you have toggled the\fB entire\fR \*(SA \*F, leaving only the\fB message line\fR visible. With the loss of the window\fB name\fR (the 'l' toggled line), you'll not easily know what window is the \*(CW. .PP You must never blame \*(Us for any potential confusion. Someone must have misapplied some commands. Come on, let's hear it, who ya gonna' blame, huh? .\" ...................................................................... .SS 4b. COMMANDS for Windows .TP 7 \ \ \'\fB-\fR\' and \'\fB_\fR\' :\fIShow/Hide_Window(s)_toggles\fR The '-' (minus) key turns the \*(CW's \*(TD \*O and \*F. When \*O, that \*(TA will show a minimum of the columns header you've established with the 'f' and 'o' commands. It will also reflect any other \*(TA options/toggles you've applied yielding zero or more tasks. The '_' (upper case minus) key does the same for\fB all\fR \*(TDs. In other words, it switches between the currently visible \*(TD(s) and any \*(TD(s) you had toggled \*F. If all 4 \*(TDs\fB are\fR currently visible, \*(Me is betting you will find the '_' command not terribly satisfying (inside, he'll wonder what-kind-of-user-he's-dealing-with). On the other hand, if all you're interested in is the system summary, \*(Me acknowledges this is the best means to that objective (inside, he'll wonder how-did-this-user-become-so-very-wise). .TP 7 *\ \'\fB=\fR\' and \'\fB+\fR\' :\fIEqualize_(re-balance)_Window(s)\fR The '=' (equals) key\fB forces\fR the \*(CW's \*(TD to be visible. It also reverses any 'i' (idle tasks) and 'n' (max tasks) commands that might be active. The \'+' (upper case equals) key does the same for\fB all\fR windows. The four \*(TDs will reappear, nice and even. They will also have\fB retained\fR any customizations you had previously applied,\fI except\fR for the 'i' (idle tasks) and 'n' (max tasks) commands. This is the command you'll use when your screen has somehow become a mess (hmmm, how-in-the-world-did-THAT-happen?). .TP 7 *\ \'\fBA\fR\' :\fIAlternate_Display_Mode_toggle\fR This command will switch between \*(FM and \*(AM. The first time you issue this command, all four \*(TDs will be shown. Thereafter when you switch modes, you will see only the \*(TD(s) you've chosen to make visible. .TP 7 *\ \'\fBa\fR\' and \'\fBw\fR\' :\fINext_Window_Forward/Backward\fR This will change the \*(CW, which in turn changes the window to which commands are directed. These keys act in a circular fashion so you can reach any desired \*(CW using either key. Assuming the window name is visible (you have not toggled 'l' \*F), whenever the \*(CW name loses its emphasis/color, that's a reminder the \*(TD is \*F and many commands will be restricted. .TP 7 *\ \'\fBG\fR\' :\fIChoose_Another_Window/Field_Group\fR You will be prompted to enter a number between 1 and 4 designating the window/field group which should be made the \*(CW. In \*(FM, this command is necessary to alter the \*(CW. In \*(AM, it is simply a less convenient alternative to the 'a' and 'w' commands. .TP 7 \ \ \'\fBg\fR\' :\fIChange_Window/Field_Group_Name\fR You will be prompted for a new name to be applied to the \*(CW. It does not require that the window name be visible (the 'l' toggle to be \*O). .IP "*" 3 The \*(CIs shown with an \*(AS have use beyond \*(AM. \'=', 'A', 'G' are\fB always\fR available \'a', 'w' act the same when\fB color mapping\fR .\" ...................................................................... .SS 4c. EXAMPLES of Windows .Jp .ce .\" ......................... .SS -*- The 'A' Mode Command Toggle -*- .Scr Here's what you'll see when you first invoke the \*(AM \*(CI. This particular display was produce on a VT100 xterm, with only 24 rows. All four \*(TDs are visible, but they could not be sized the same. Available lines are parceled out in the fairest way possible so the last two \*(TDs have an extra line each. Notice the \*(CW\fB name\fR in the \*(SA \*(EM it's been emphasized because the associated \*(TD is visible. Since 1:Def has a \*(TA, the full range of \*(CIs would be at your disposal. But remember, many of those commands will apply only to window 1:Def. .Img +\fB--------------------------------------\fR+ 1:Def name is bold, |\fB1:Def\fR - 15:46:37 up 16:25, 9 users, : thus all commands |Tasks: \fB 76\fR total, \fB 1\fR running, \fB 75\fR sle: will be available. |Cpu(s) state: \fB 0.7%\fR user, \fB 1.3%\fR syst: |Mem: \fB 126588k\fR total, \fB 123688k\fR used,: |Swap: \fB 265032k\fR total, \fB 8232k\fR used,: |______________________________________: Tough luck windows |\fI1__PID_USER______PR__NI_%CPU____TIME+_\fR: #1 & 2 - you\fB lost\fR |\fB 7343 jtwm 16 0 0.9 0:00.59\fR:\fB one line\fR each \*(EM | 7339 jtwm 9 0 0.0 0:00.02: guess you'll just |\fI__7337_root_______9___0__0.0___0:01.30\fR: have to learn how |\fI2__PID__PPID_Command____________TIME+_\fR: to live with it. |\fB 997 952 kdeinit 17:59.59\fR: | 1115 952 kdeinit 2:16.47: |\fI__1803__1116_led_______________1:55.30\fR: |\fI3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_\fR: The #3 & #4 windows | 4634 12.3 15620 0 15m 860 14m : better not gloat | 7337 11.3 14396 92 13m 36 13m : over 1 extra line. | 923 10.6 30524 16m 13m 1120 12m : That user could yet |\fI___991__7.2__9492__316_9176___12_9164_\fR: sock 'em with the |\fI4_UID_USER_____GROUP____TTY________PID\fR: 'n' command and | 43 xfs xfs ? 806: take\fI those lines\fR, | 0 ykde users pts/7 5561:\fB plus others\fR, away! | 0 wgnome users pts/7 5560: | 0 root root pts/7 5325: +\fB--------------------------------------\fR+ .Rje .Scr So, what say we start applying some of those "full range of \*(CIs"? Onward + Downward... .ce .\" ......................... .SS -*- STACKIN' & WHACKIN' Windows -*- .Scr Whoa, hold on mate. Someone has already whacked these windows. See, there are no \*(TAs for windows 1:Def and 4:Usr. Well, we can at least retrace their steps... Here's what was done, after issuing the '\fBA\fR' command and entering \*(AM. \fB1\fR) When #1\fB was\fR the \*(CW, '-' was pressed, toggling \*F the associated \*(TD ( if 'l t m'\fI had been\fR applied to its summary, too ) ( then there'll be\fI only\fR a msg line when 'current' ) \fB2\fR) Then the 'w' key was struck to cycle\fB backward\fR, making 4:Usr the \*(CW (could have used 'a a a', if one likes to type) \fB3\fR) Then step #1 was repeated, and bye-bye window #4 \fB4\fR) Finally, window #2 was made the \*(CW ( Q. how many keystrokes were used? ) ( A. minimum of 2: 'a a' or 'w w'. ) .Img +\fB--------------------------------------\fR+ No 'l','t','m','1' |\fB2:Top\fR - 15:48:35 up 16:27, 9 users, : commands have been |Tasks: \fB 75\fR total, \fB 1\fR running, \fB 74\fR sle: issued here, |Cpu(s) state: \fB 2.0%\fR user, \fB 0.7%\fR syst: but... |Mem: \fB 126588k\fR total, \fB 123712k\fR used,: |Swap: \fB 265032k\fR total, \fB 8232k\fR used,: |______________________________________: #2's been changed; |\fI2__PID__PPID_Command____________TIME+_\fR: user applied a 'c' |\fB 997 952 kdeinit: konsol 18:00.70\fR: command (when it | 1115 952 kdeinit: konsol 2:16.47:\fB was\fR current) - now | 1803 1116 led tiptop.HELP 1:55.30: shows cmd\fI lines\fR vs. | 923 922 X :0 1:09.60: program names; | 973 1 klaptopdaemon 0:59.63: still seems to be | 981 952 /usr/bin/artsd 0:48.63: sorted on TIME+ | 987 1 kdeinit: kdeskt 0:24.34: though |\fI___991_____1_kdeinit:_kicker___0:04.59\fR: |\fI3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_\fR: This #3 guy appears | 4634 12.3 15620 0 15m 860 14m : to still be running | 7337 11.3 14396 92 13m 36 13m : with the supplied | 923 10.6 30544 16m 13m 1120 12m : defaults, but no | 991 7.2 9492 316 9176 12 9164 : telling what\fI damage\fR |\fB 7329 7.0 9036 140 8896 36 8860\fR : might have been | 1115 6.9 8956 160 8796 36 8760 : done to it's | 987 6.4 8668 524 8144 20 8124 :\fB summary info\fR stuff | 1131 6.4 8268 144 8124 36 8088 : +\fB--------------------------------------\fR+ .Rje .Scr And that's what brought us to this current state. No, wait. Oh lordy, will you look at that \*(EM someone has changed the\fB name\fR of window #2 from 'Job' to 'Top'! How'd they do that? Well, they just issued the 'g' \*(CI, of course. That command is available whenever \*(AM is active and always impacts just the \*(CW. Gosh, you can even issue the 'g' command when 'l' has toggled \*F the very \*(SA line containing the window name! Almost Done... .ce .\" ......................... .SS -*- ALL TOGETHER Now, Window(s) -*- .Scr Here, the window 1:Def \*(TD has been toggled \*F but it remains the \*(CW. Since there is no \*(TA, many commands will be restricted. However, the commands ('l', 't', 'm', '1') affecting the \*(SA, as well as some other global commands ('k', 'Z', etc.), would still be active. Notice that the\fB Mem\fR and\fB Swap\fR lines are not shown. This means that the loser (oops, user) has, in fact, issued the 'm' command! Now, if you were to cycle the \*(CW with the 'a' or 'w' commands, the \*(TD would remain the same (except possibly growing/shrinking slightly) but the \*(SA would change periodically. The comments to the left of the image provide additional insights into how things came to be. Note especially the comments for window 4:Usr \*(EM the one with some empty rows... .Img 1:Def\fI no\fR highlight, +\fB--------------------------------------\fR+ thus disabled cmds: |1:Def - 15:50:32 up 16:29, 9 users, : b,i,n,u,x,y, etc. |Tasks: \fB 75\fR total, \fB 2\fR running, \fB 73\fR sle: & m = lost Mem/Swap |Cpu(s) state: \fB 10.6%\fR user, \fB 0.0%\fR syst: |______________________________________: 2:Job was very busy: |\fI2__PID__PPID_Command____________TIME+_\fR: 'n' cmd, w/ 7 tasks | 80 1\fB ( khubd ) \fR 0:00.00: 'c' cmd, cmd line | 6 0\fB ( kreclaimd ) \fR 0:00.00: 'O' cmd, sort cmd | 9 1\fB ( mdrecoveryd )\fR 0:00.00: 'R' cmd, sort bkwd | 11358 1\fB /bin/bash/ /usr\fR 0:00.00: 'x' cmd, hi column | 1297 1\fB /sbin/mingetty \fR 0:00.00: (when 2\fB WAS\fR current) | 683 1\fB xinetd -stayali\fR 0:00.00: |\fI___836_____1_\fBlogin_--_root\fI_____0:00.00\fR: 3:Mem has altered |\fI3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_\fR: some std defaults: | 4634\fB 12.3\fR 15620 0 15m 860 14m : 'y' turned Off | 7337\fB 11.3\fR 14396 92 13m 36 13m : 'x' turned On | 923\fB 10.6\fR 30544 16m 13m 1120 12m : (when 3\fB WAS\fR current) | 991\fB 7.2\fR 9492 316 9176 12 9164 : |\fI__7329__\fB7.0\fI__9036__140_8896___36_8860_\fR: Huh? 4:Usr has some |\fI4_UID_USER_____GROUP____TTY________PID\fR: \fBblank rows\fR! ? ? ? ? | \fB 0 jtwm root pts/2 5561\fR: Aha, the 'i' command | \fB 0 root root ? 5560\fR: applied (when 4\fB WAS\fR | : current); could be | : reversed with '=', | : when 4\fB IS\fR current! +\fB--------------------------------------\fR+ .Rje .Scr Ok now, how about that \*(CW 1:Def and its\fB unseen tasks\fR? At any time, you can quickly\fB retrieve\fR lost tasks in a number of ways: 1) Press '-', toggling just the \*(CW 2) Press '_', toggling\fB all\fR visible/invisible windows ( 1:Def is the\fI only\fR window currently\fB not shown\fR ) ( afterward, it'll be the\fI only\fR window\fB showing\fR! ) * 3) Press '+', forcing all \*(TDs to become\fB visible\fR 4) Press 'A' to return to \*(FM, with\fI only\fR 1:Def tasks shown and\fI without\fR a window name Now that should be enough ways of getting a \*(TA\fB visible\fR again to satisfy almost any user, don't ya think? .in +4 \*(NT Use #3 above when you've messed up your screen beyond redemption. The four \*(TDs will reappear, nice and even. They will also have\fB retained\fR any customizations you had previously applied,\fI except\fR for the 'i' (idle tasks) and 'n' (max tasks) commands. .in That's It !\ \ Piece of Cake !!\ \ Enjoy them there windows !!!\fR .Zzz .\" ---------------------------------------------------------------------- .SH 5. FILES .\" ---------------------------------------------------------------------- .\" ...................................................................... .SS 5a. SYSTEM Configuration File The presence of this file will influence which version of the 'help' screen is shown to an ordinary user. More importantly, it will\fI limit\fR what ordinary users are allowed to do when \*(Me is running. They will\fB not\fR be able to issue the following commands (well, at least not successfully, ha ha): \fBk Kill\fR a task \fBr Renice\fR a task \fBd\fR or\fB s\fR Change\fB delay/sleep\fR interval The system \*(CF is\fB not\fR created by \*(Me. Rather,\fB you create this file manually\fR and place it in the \fI/etc\fR directory. Its name must be 'toprc' and must have\fI no\fR leading '.' (period). It must have only\fI two lines\fR. Here is an example of the contents of\fI /etc/toprc\fR: \fBs\fR # line 1: 'secure' mode switch \fB5.0\fR # line 2: 'delay'\ \ interval in seconds .\" ...................................................................... .SS 5b. PERSONAL Configuration File This file, written as '$HOME/\fI.your-name-4-top\fR' + '\fBrc\fR', is eminently editable due to the numerous labels it contains. But please don't! Rather, use the 'W' \*(CI to create it or update it. For the benefit of those who never follow such advise, here is the general layout. \fBglobal\fR # line 1: a shameless advertisement \fR " \fR # line 2: id,altscr,irixps,delay,curwin \fBper ea\fR # line a: winname,fieldscur \fBwindow\fR # line b: winflags,sortindx,maxtasks \fR " \fR # line c: summclr,msgsclr,headclr,taskclr ( and good luck with those winflags on line #b! ) If the $HOME variable is not present, \*(US will try to write the personal \*(CF to the current directory, subject to permissions. .\" ---------------------------------------------------------------------- .SH 6. STUPID TRICKS Sampler .\" ---------------------------------------------------------------------- With this task/process viewer, lots of things become\fB possible\fR. Of course, that doesn't mean they should become\fB probable\fR. So if you try any of them, just don't let anyone catch you. Many of these 'tricks' work best when you give ol' \*(Me a scheduling boost \*(EM so plan on starting him with a nice value of -10 (assuming you've got the authority). .\" ...................................................................... .SS 6a. Kernel Magic .\" sorry, just can't help it -- don't ya love the sound of this? For these stupid tricks, \*(Me needs \*(FM. .\" ( apparently static was a potential concern ) .New The user interface, through prompts and help, intentionally implies that the delay interval is limited to tenths of a second. However, you're free to set any desired delay. If you want to see Linux at his scheduling best, try a delay of .09 seconds or less. For this experiment, under x-windows open an xterm and maximize it. Then do the following: . provide a scheduling boost and tiny delay via: nice -n -10 top -d.09 . keep sorted column highlighting \*F to minimize path length . turn \*O reverse row highlighting for emphasis . try various sort columns (TIME/MEM work well), and normal or reverse sorts to bring the most active processes into view What you'll see is a\fB very busy Linux\fR doing what he's always done for you, but there was no program available to illustrate this (until now). .Rjb 2 ( now please, don't waste too many ) ( \*(Pu cycles in this way, alright? ) .Rje .New Under an xterm using 'white-on-black' colors, try setting \*(Me's task color to black and be sure that task highlighting is set to bold, not reverse. Then set the delay interval to around .3 seconds. After bringing the most active processes into view, what you'll see are the\fB ghostly images\fR of just the currently running tasks. Of course, a much better display is achieved by toggling idle processes \*F and using normal/visible colors. .\" ...................................................................... .SS 6b. Bouncing Windows For these stupid tricks, \*(Me needs \*(AM. .New With 3 or 4 \*(TDs visible, pick any window other than the last and turn idle processes \*F.   Depending on where you applied 'i', sometimes several \*(TDs are\fB bouncing\fR and sometimes it's like an\fB accordion\fR, as \*(Me tries his best to allocate space. .New Set each window's summary lines differently: one with no memory; another with no states; maybe one with nothing at all, just the message line.   Then hold down 'a' or 'w' and watch a variation on bouncing windows. What say we call these '\fBhopping windows\fR'. .New Display all 4 windows and for each, in turn, set idle processes to \*F. You've just entered the "\fBextreme bounce\fR" zone.   .\" ...................................................................... .SS 6c. The Big Bird Window This stupid trick also requires \*(AM. .New Display all 4 windows and make sure that 1:Def is the \*(CW. Then, keep increasing window size until the all the other \*(TDs are "\fBpushed out of the nest\fR". When they've all been displaced, toggle between all visible/invisible windows. Then ponder this: .br is \*(Me fibbing or telling honestly your imposed truth? .\" ---------------------------------------------------------------------- .SH 7. NOTES and Rantings .\" ---------------------------------------------------------------------- .\" ...................................................................... .SS 7a. The top Binary .PP To whom it may (should) concern: \*(Us, even with its vastly expanded capabilities, is only slightly larger than the old top. Were it not for extensive help text and additional sort callbacks, it would be smaller. .Rjb 6 Throw source carelessly at objectives, it\fI will\fR produce equally careless machine instructions. example: (num_\fBpages\fR - an_\fBaddress\fR)/1024 == duh? kicker: \fBdocument\fR result as broken, due to\fB elf\fR! \fB----------------------------------------------\fR I know you're out there, are you getting this? .Rje .PP Now, as for all those new capabilities like colors and windows and highlighting, you'd expect \*(Us to be the "mother of all pigs" compared to old \*(Me \*(EM right? Yea, with \*(US expect following piglets: .br \ \. A\fI smaller\fR virtual image and resident footprint .br \ \. Slightly\fI fewer\fR major page faults .br \ \. A\fI large reduction\fR in minor page faults for SMP .br \ \. The\fI same\fR or better response time .br \ \. The same or\fI even less\fR \*(PU costs Ideally any comparison of the old and new \*(Me should be against the same libproc format (32-bit or 64-bit tics) and run in a true or simulated SMP environment (producing separate \*(PU stats). This latter requirement will coax old \*(Me into handling his own '/proc/stat' access \*(EM something \*(Us always does, but with less cost. .\" ...................................................................... .SS 7b. Comparing Performance .PP Even with equivalent libraries and '/proc/stat' access, it's difficult to accurately compare tops using their \fBown displays\fR. Results for these \*(Pu\-intensive programs (who frequently exceed their time-slice) generally show a wide disparity in %CPU. This is due to differing call patterns, kernel preemptions and the timing of process snapshots. For\fI slightly\fR better results, start each program with the following commands: ./old-top -d 0.5 nice -n-10 ./new-top -d 0.4 While actually putting \*(Us at a performance disadvantage, the higher scheduling priority and staggered timing will\fI periodically\fR yield a somewhat truer picture. You could even reverse those roles and get similar results. The most\fI consistent\fR performance results will be obtained 'off-line', using your shell's time pipe or the time program itself. And even in a single processor environment or without equivalent libraries, total cpu costs (user time + system time) are similar. However, \*(Us's \*(Pu costs ARE influenced by the capabilities you choose to exploit, even if they don't SEEM to be reflected in such timings. So let's examine some... .\" ...................................................................... .SS 7c. Cost of Stuff .TP 3 .B Colors Cost\fR \*(EM Nada (almost). Once the terminfo strings are built (\fIat\fR and\fI during\fR a user's behest) they are SAVED with each window's stuff. And while there will be extra tty escape sequences transmitted because of colors, it makes no difference which 'char *' is actually used. .TP 3 .B Highlighting Cost\fR \*(EM Nada (maybe), or blame it on Rio. On second thought, let's blame it on the user. For\fI row\fR highlighting, there is only the cost of those extra tty escape sequences (same as for colors). For\fI column\fR highlighting, there is a fairly\fB significant cost\fR associated with column transition management combined with even more tty output. These increased costs are incurred on every \*(TD row. Sooo... hey USER \*(EM \fIdo NOT highlight COLUMNS\fR. You shouldn't need a constant visual reminder of your chosen sort field. However, if you forget which field \*(Me is sorting it can serve as a quick visual reminder. .TP 3 .B Windows Cost\fR \*(EM Nada (if just 1 window). If more than 1 window, almost certainly NOT Nada so blame it on reality. Colors are not an issue, but those sort fields are. If we could trust the user to always select the same 'c' state, 'S' state and sort field (hey, why ya got multiple windows then user, huh?) AND if we can trust someone to recompile \*(Me with a #define enabled, then we\fB could\fR achieve 'Nada'. Ok, not likely, so we're gonna' be doing multiple sorts. BUT, it may not be as bad as it sounds. Those sorts involve\fB pointers only\fR. And,\fI that's as good as it gets\fR\ !\ \ (right Mr. N?) .\" ...................................................................... .SS 7d. The top Sources .TP 3 .B top.h\fR Unlike his predecessor, \*(Us has a proper header file. It contains ONLY declarations, NOT definitions. And there are several conditionals present to help with further customizations and experimentation. All are \*F by default. .TP 3 .B top.c\fR Hopefully proves that source code needn't be a disorganized, misaligned MESS. And, WHO says a source listing shouldn't occasionally make you SMILE? Why, \*(Me.c even does a darn good job of following the suggestions in a document hardly anybody seems to observe. .Rjb 3 \fRthe\fB Linus Torvalds CodingStyle\fR guidelines ... \fR-*- -*- -*- on indentation + etc. -*- -*- -*-\fR \fRwell\fB almost all\fR, except for those\fB stinkin'\fR... .Rje .P I suppose even Linus Torvalds is entitled to err now and again. How so you say? Tabs, me' bucko,\fB stinkin' tabs\fR! That, plus the simplistic position regarding\fB indentation\fR espoused in that otherwise excellent document. .\" ...................................................................... .SS -*- Rant On, and on -*- Let's compare two approaches to the tab/indentation issue with a small code sample using tabs then spaces. This snippet happens to be the key to \*(Me's use of\fB dynamic\fR colors on many\fB static\fR screens, while also ensuring screen width isn't exceeded so as to avoid line wraps. We'll view just the first 40 columns, assuming one wishes to occasionally provide\fI comments\fR to the right of actual code (you\fB do\fR, don't you?). Then YOU decide which approach makes the most SENSE! .ImgC .B Stinkin' Tabs\fR versus\fB Spaces\fR: the Linus way Hey, where'd my +\fB----\fR+\fB----\fR1\fB----\fR+\fB----\fR2\fB----\fR+\fB----\fR3\fB----\fR+\fB----\fR4+ many\fB code\fR lines | while (*sub_beg) { : up-and-gone-to? | switch (*sub_end: | case 0: : Gosh, wonder if | \e Tabs Induced / : Linus expects a | case 1: : fellow to stick | +\fB WASTE-Lands\fR! + case 5: : his\fB comments\fR on | : the\fB left\fR side?! | + Not a Living + : | : Ever see source | +\fB line-of-code\fR + : with\fI not enough\fR | : whitespace; and | / To Be Found! \e : this is\fB better\fR? | default:: | : Oh\fI lookie here\fR, \e } : there's just a\fB hint\fR of\fI REAL\fB code! ----> if (0 >= room) b\fR: / } /* end: while 'subtrin: +\fB----------------------------------------\fR+ .Rje .ImgC .B Spaces\fR versus\fB Stinkin' Tabs\fR: the other way +\fB----\fR+\fB----\fR1\fB----\fR+\fB----\fR2\fB----\fR+\fB----\fR3\fB----\fR+\fB----\fR4+ Wow, now\fB this\fR is | while (*sub_beg) { :\fB Visible\fR hackin'! | switch (*sub_end) { : | case 0: : Hmmm, wonder\fB how\fR | *(sub_end + 1) = '\e0'; :\fB many\fR programmers | case 1: case 2: case 3: case:\fB read\fR those lines | case 5: case 6: case 7: case: from the\fB LEFT\fR to | cap = Curwin->captab[(int: the\fB RIGHT\fR? This | *sub_end = '\e0'; : "innovation" may | printf("%s%.*s%s", cap, r:\fI possibly benefit\fR | room -= (sub_end - sub_be: those particular | sub_beg = ++sub_end; : kinds of people, | break; : you agree? Duh! | default: : | ++sub_end; : AND, there\fI might\fR | } : even be room for | if (0 >= room) break; : unseen\fB comments\fR! | } /* end: while 'subtrings' */ : +\fB----------------------------------------\fR+ .Rje .PP .B Gosh, I just don't KNOW \*(EM\fB it's such a TOUGH choice... Oh you\fB Stinkin' Tabs\fR:\ \ correspondence, Who-Cares; documentation, Oh-Alright; even scripts, Well-If-You-Must. But you have NO place within the\fB code-space\fR of MY C-source listing! So\fB be gone\fR already!! .\" ...................................................................... .SS In Summation... .Jbu If you want to use tabs to the\fB right\fR of the\fB code\fR, go-for-it. But PLEASE, not ever in the C-source\fB code-space\fR, thank-you-kindly. Just use\fB three little ol' spaces\fR (exactly 3, no-more, no-less) where you WOULD have stuck a stinkin' tab. We'll get far more READABLE files, much less WAISTED precious horizontal space, more consistent CURSORS and on, and ON, AND ON! Plus, without those awful *the-devil's-own-handiwork*, the aforementioned document need NEVER speak of their EVILS again. .Jbu Lastly, since SPACES (not stinkin' tabs) are SO beneficial, maybe we should use just a\fB few more\fR of 'em. Some of those C-thingies are VERY sensitive \*(EM they don't like being TOUCHED by any other syntax element! Which ones? Why these guys: \fBbraces\fR, \fBreserved words\fR and\fB binary operators\fR ( it's the TRUTH, they told me themselves ) .Jp It's so EASY to keep 'em HAPPY! And lo-and-behold, the combination of <\fBsp\fR>thingy<\fBsp\fR> turns out to be a darn effective\fB bug repellent\fR, too. So much so, one can actually code while TOTALLY NUDE yet still avoid them ol' bug-bytes (sic-sic)! .Rjb 5 step down_from me_punctilious soap-box_once_again [1 +5 +5 +5 = huh?] .Rje .\" ---------------------------------------------------------------------- .SH 8. BUGS .\" ---------------------------------------------------------------------- Bugs? What bugs? But, if ever there were, then... Please send bug reports to: Albert D\. Cahalan, [ thanks Albert, heaven forbid author should be bothered ] .\" ---------------------------------------------------------------------- .SH 9. HISTORY Former top .\" ---------------------------------------------------------------------- The original top was written by Roger Binns, based on Branko Lankester's ps program. Robert Nation adapted it for the proc file system. Helmut Geyer added support for configurable fields. Plus many other individuals contributed over the years. .\" ---------------------------------------------------------------------- .SH 10. AUTHOR .\" ---------------------------------------------------------------------- This entirely new and enhanced replacement was written by: Jim / James C. Warner, .ig ( as a means to learn Linux, can you believe it? ) ( & he accidentally learned a little groff, too! ) .. With invaluable help from: Craig Small, Albert D\. Cahalan, .ig .rj 2 .B -*-\fR few though they are, some yet believe\fB -*-\fR .B -*-\~\~\~\~\~\~\~\fRin-the-\fBart\fR-of-programming\~\~\~\~\~\~\~\fB-*-\fR .. .\" ---------------------------------------------------------------------- .SH 11. SEE ALSO .\" ---------------------------------------------------------------------- .BR free (1), .BR ps (1), .BR uptime (1), .BR vmstat (8), .BR w (1). .\" ---------------------------------------------------------------------- .ig CCend .rj 1 \-*- .PD .in -3 Copyright (c) 2002 \*(EM JC Warner & Associates, Ltd. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Front-Cover Texts, no Back-Cover Texts, and with the following Invariant Sections and any sub-sections therein: .na .hy 0 .in +3 DIFFERENCES\ /\ New Features; .br STUPID\ TRICKS\ Sampler; .br NOTES\ and\ Rantings; .br AUTHOR .in A copy of the license is included in the section entitled \(dqGNU Free Documentation License\(dq. . CCend . .\" end: active doc |||||||||||||||||||||||||||||||||||||||||||||||||| .\" |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||| .ig GFDLend .\" ---------------------------------------------------------------------- .SH GNU Free Documentation License Version 1.1, March 2000 Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. .SS 0. PREAMBLE The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others. This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference. .SS 1. APPLICABILITY AND DEFINITIONS This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language. A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque". Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only. The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text. .SS 2. VERBATIM COPYING You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3. You may also lend copies, under the same conditions stated above, and you may publicly display copies. .SS 3. COPYING IN QUANTITY If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document. .SS 4. MODIFICATIONS You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: .HP 3 .B A\fR.\ Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. .HP 3 .B B\fR.\ List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five). .HP 3 .B C\fR.\ State on the Title page the name of the publisher of the Modified Version, as the publisher. .HP 3 .B D\fR.\ Preserve all the copyright notices of the Document. .HP 3 .B E\fR.\ Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. .HP 3 .B F\fR.\ Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. .HP 3 .B G\fR.\ Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. .HP 3 .B H\fR.\ Include an unaltered copy of this License. .HP 3 .B I\fR.\ Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. .HP 3 .B J\fR.\ Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. .HP 3 .B K\fR.\ In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. .HP 3 .B L\fR.\ Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. .HP 3 .B M\fR.\ Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version. .HP 3 .B N\fR.\ Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section. .PP If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles. You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard. You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version. .SS 5. COMBINING DOCUMENTS You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements." .SS 6. COLLECTIONS OF DOCUMENTS You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document. .SS 7. AGGREGATION WITH INDEPENDENT WORKS A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate. .SS 8. TRANSLATION Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail. .SS 9. TERMINATION You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. .SS 10. FUTURE REVISIONS OF THIS LICENSE The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. .SS ADDENDUM: How to use this License for your documents To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: .IP "" 3 Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation;\ \ with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License". If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software. .\" ---------------------------------------------------------------------- .SH \fRend of\fB GNU Free Documentation License .IP "" .PP .GFDLend .\" end: gfdl license |||||||||||||||||||||||||||||||||||||||||||||||| .\" ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||