Credit for this belongs to: Jim / James C. Warner, ---------------------------------- Ok, ok, I yield -- most of what follows has been removed from the manual page and packaged separately as this README (hey, it was only TEMPORARY insanity). Of course, that means that now absolutely nobody will ever read it. This is probably a good thing... ## Table of Contents ---------------------------------------------------## # the only darn thing that wasn't in the man page CUSTOMIZING the Sources # the following carry their original topic numbers DIFFERENCES / New Features Interface Etiquette Expanded Configurable Display Support Enhanced Field/Column Management Customization Flexibility NOTES and Rantings The top Binary Comparing Performance Cost of Stuff The top Sources EXAMPLES of Windows The 'A' Mode Command Toggle STACKIN' & WHACKIN' Windows ALL TOGETHER Now, Window(s) ## CUSTOMIZING the Sources ---------------------------------------------## Listed below are the conditionals available should you wish to recompile this top. The author's favorite is: PRETEND4CPUS. That's the #define allowing you to simulate an SMP environment, and (perhaps) impress your friends. It's currently set to display four separate CPUs, but could easily be changed. Caution: do NOT use this provision in an effort to impress someone who truly possesses such a machine! The fact that all 4 CPUs show the same dynamic results will likely have the opposite effect. //#define ATEOJ_REPORT /* report a bunch of stuff, at end-of-job */ //#define CASEUP_HEXES /* show any hex values in upper case */ //#define CASEUP_SCALE /* show scaled time/num suffix upper case */ //#define CASEUP_SUMMK /* show memory summary kilobytes with 'K' */ //#define POSIX_CMDLIN /* use '[ ]' for kernel threads, not '( )' */ //#define PRETEND2_5_X /* pretend we're linux 2.5.x (for IO-wait) */ //#define PRETEND4CPUS /* pretend we're smp with 4 ticsers (sic) */ //#define PRETENDNOCAP /* use a terminal without essential caps */ //#define SORT_SUPRESS /* *attempt* to reduce qsort overhead */ //#define STDOUT_IOLBF /* disable our own stdout _IOFBF override */ //#define USE_LIB_STA3 /* use lib status (3 ch) vs. proc_t (1 ch) */ //#define WARN_NOT_SMP /* restrict '1' & 'I' commands to true smp */ ## 6. DIFFERENCES / New Features ---------------------------------------## The following summarizes differences between this top and your former top. It was originally based on procps-2.0.7. However, except for the separate/summary CPU toggle, all of these differ- ences also apply through procps-2.0.10. 6a. Interface Etiquette -*- Input and output are far more carefully implemented in this top. You won't be subjected to 4 - 5 'Unknown command' messages should you press the wrong key. -*- You need suffer a confirmation message only when the results of a command are not obvious by their effects on the display. -*- The Help screen will no longer overflow, even when running with a 24 row xterm (vt100). -*- The fields selection/ordering screens do not carelessly destroy important information through unintended line wraps. -*- Should you narrow a xterm window to less than 80 columns while this top is running, you will not be left with an utterly worthless, embarrassing display. 6b. Expanded Configurable Display Support -*- In an SMP environment, you can choose between a summary dis- play or you may show each cpu separately. No longer must this choice be irrevocably made at startup. -*- There are new fields and with this top, any field is selectable for sorting. Plus, your sorted column can be instantly reversed with just a single keystroke. -*- You may optionally apply 2 distinct types of highlighting to running tasks and/or sorted columns. With this top, you'll be able to instantly spot running tasks and always know the current sort field. -*- While you could continue to use the more familiar (and boring) monochrome display, you might want to try this top's new color display. You can even create your own unique col- ors used in summaries, messages, headings and tasks, each of which can be made persistent until you choose to change them. -*- Up to four separate windows can be displayed simultaneously, giving you four separate ways to sort and view the tasks cur- rently cluttering up your system. You could have one view by pids, another by cpu usage, yet another showing memory con- sumption. You get the idea... -*- Each window comes with pre-configured (but user configurable) fields and you can size each window individually. -*- Virtually every one of this top's options (summaries, fields, colors, sorted column, etc.) is separately configurable for each of those four windows. Heck, you can even change a window's name, if you don't care for top's choices. Your changes will be reflected not only when you're in what top calls alternate-display mode but also on his special new 'Windows' help screen. -*- And, [ ** Drum-Roll + Ta-Da ** ] with just one keystroke you can quickly switch between full-screen and multiple window modes! Or, with a different keystroke, toggle a single win- dow Off for now, then On again later!! 6c. Enhanced Field/Column Management -*- Many Field/Column names have been changed to make them more intuitive, more self-descriptive. And with this top you won't be fooled with field choices that are "not yet imple- mented". -*- Task memory statistics are more meaningful and more accurate. -*- You'll finally have complete display integrity regardless of field selections, their order or screen width. And that means the command column no longer need be kept as the right- most field, lest your screen turn to when all the following columns get misaligned. 6d. Customization Flexibility -*- You have complete program naming freedom with no internal ties to a specific personal configuration file. Symbolic links could be used to establish different configuration files reflecting the different personalities of your cus- tomized "tops", under whatever aliases you've used. Thus, you could have an alias for running top 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! -*- All of your configuration choices can be preserved in a per- sonal configuration file, including any changes made on a per-window basis. Thus, once you personalize things they remain personalized until you decide to change them again. This top has been completely cured of: i-cant-remember-so-please-do-that-all-over-again ( and again, and again ... ) The bottom line is this: if you save your configuration before quitting top, upon restart the display will appear exactly as you left it. And that means you no longer have to keep top running until-the-end-of-time (ok, a long time anyway), lest your customizations go bye-bye. ## 7. NOTES and Rantings -----------------------------------------------## 7a. The top Binary To whom it may (should) concern: this top, 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. Throw source carelessly at objectives, it will produce equally careless machine instructions. example: (num_pages - an_address)/1024 == duh? kicker: document result as broken, due to elf! ---------------------------------------------- I know you're out there, are you getting this? Now, as for all those new capabilities like colors and windows and highlighting, you'd expect this top to be the "mother of all pigs" compared to old top -- right? Yea, with this top expect following piglets: . A smaller virtual image and resident footprint . Slightly fewer major page faults . A large reduction in minor page faults for SMP . The same or better response time . The same or even less CPU costs Ideally any comparison of the old and new top should be against the same libproc format (32-bit or 64-bit tics) and run in a true or simulated SMP environment (producing separate CPU stats). This latter requirement will coax old top into handling his own '/proc/stat' access -- something this top always does, but with less cost. 7b. Comparing Performance Even with equivalent libraries and '/proc/stat' access, it's dif- ficult to accurately compare tops using their own displays. Results for these cpu-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 tim- ing of process snapshots. For slightly 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 this top at a performance disadvantage, the higher scheduling priority and staggered timing will periodically yield a somewhat truer picture. You could even reverse those roles and get similar results. The most consistent 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, this top's cpu 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... 7c. Cost of Stuff Colors Cost -- Nada (almost). Once the terminfo strings are built (at and during 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. Highlighting Cost -- Nada (maybe), or blame it on Rio. On second thought, let's blame it on the user. For row highlighting, there is only the cost of those extra tty escape sequences (same as for colors). For column highlight- ing, there is a fairly significant cost associated with column transition management combined with even more tty output. These increased costs are incurred on every task display row. Sooo... hey USER -- do NOT highlight COLUMNS. You shouldn't need a constant visual reminder of your chosen sort field. However, if you forget which field top is sorting it can serve as a quick visual reminder. Windows Cost -- 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 top with a #define enabled, then we could 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 point- ers only. And, that's as good as it gets ! (right Mr. N?) 7d. The top Sources top.h Unlike his predecessor, this top has a proper header file. It contains ONLY declarations, NOT definitions. And there are several conditionals present to help with further customiza- tions and experimentation. All are Off by default. top.c 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, top.c even does a darn good job of following the suggestions in a document hardly anybody seems to observe. the Linus Torvalds CodingStyle guidelines ... -*- -*- -*- on indentation + etc. -*- -*- -*- well almost all, except for those stinkin'... I suppose even Linus Torvalds is entitled to err now and again. How so you say? Tabs, me' bucko, stinkin' tabs! That, plus the simplistic position regarding indentation espoused in that other- wise excellent document. -*- 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 top's use of dynamic colors on many static 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 comments to the right of actual code (you do, don't you?). Then YOU decide which approach makes the most SENSE! Stinkin' Tabs versus Spaces: the Linus way Hey, where'd my +----+----1----+----2----+----3----+----4+ many code lines | while (*sub_beg) { : up-and-gone-to? | switch (*sub_end: | case 0: : Gosh, wonder if | \ Tabs Induced / : Linus expects a | case 1: : fellow to stick | + WASTE-Lands! + case 5: : his comments on | : the left side?! | + Not a Living + : | : Ever see source | + line-of-code + : with not enough | : whitespace; and | / To Be Found! \ : this is better? | default:: | : Oh lookie here, \ } : there's just a hint of REAL code! ----> if (0 >= room) b: / } /* end: while 'subtrin: +----------------------------------------+ Spaces versus Stinkin' Tabs: the other way +----+----1----+----2----+----3----+----4+ Wow, now this is | while (*sub_beg) { : Visible hackin'! | switch (*sub_end) { : | case 0: : Hmmm, wonder how | *(sub_end + 1) = '\0'; : many programmers | case 1: case 2: case 3: case: read those lines | case 5: case 6: case 7: case: from the LEFT to | cap = Curwin->captab[(int: the RIGHT? This | *sub_end = '\0'; : "innovation" may | PUTP("%s%.*s%s", cap, roo: possibly benefit | room -= (sub_end - sub_be: those particular | sub_beg = ++sub_end; : kinds of people, | break; : you agree? Duh! | default: : | ++sub_end; : AND, there might | } : even be room for | if (0 >= room) break; : unseen comments! | } /* end: while 'subtrings' */ : +----------------------------------------+ Gosh, I just don't KNOW -- it's such a TOUGH choice... Oh you Stinkin' Tabs: correspondence, Who-Cares; documentation, Oh-Alright; even scripts, Well-If-You-Must. But you have NO place within the code-space of MY C-source listing! So be gone already!! In Summation... - If you want to use tabs to the right of the code, go-for-it. But PLEASE, not ever in the C-source code-space, thank-you- kindly. Just use three little ol' spaces (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. - Lastly, since SPACES (not stinkin' tabs) are SO beneficial, maybe we should use just a few more of 'em. Some of those C- thingies are VERY sensitive -- they don't like being TOUCHED by any other syntax element! Which ones? Why these guys: braces, reserved words and binary operators ( it's the TRUTH, they told me themselves ) It's so EASY to keep 'em HAPPY! And lo-and-behold, the combi- nation of thingy turns out to be a darn effective bug repellent, too. So much so, one can actually code while TOTALLY NUDE yet still avoid them ol' bug-bytes (sic-sic)! step down_from me_punctilious soap-box_once_again [1 +5 +5 +5 = huh?] ## 4c. EXAMPLES of Windows ---------------------------------------------## -*- The 'A' Mode Command Toggle -*- Here's what you'll see when you first invoke the alternate-display mode interactive command. This particular display was produce on a VT100 xterm, with only 24 rows. All four task displays are visible, but they could not be sized the same. Available lines are parceled out in the fairest way possi- ble so the last two task displays have an extra line each. Notice the 'current' window name in the summary area -- it's been emphasized because the associated task display is visible. Since 1:Def has a task area, the full range of interactive commands would be at your disposal. But remember, many of those commands will apply only to window 1:Def. +--------------------------------------+ 1:Def name is bold, |1:Def - 15:46:37 up 16:25, 9 users, : thus all commands |Tasks: 76 total, 1 running, 75 sle: will be available. |Cpu(s): 0.7% user, 1.3% system, : |Mem: 126588k total, 123688k used,: |Swap: 265032k total, 8232k used,: |______________________________________: Tough luck windows |1__PID_USER______PR__NI_%CPU____TIME+_: #1 & 2 - you lost | 7343 jtwm 16 0 0.9 0:00.59: one line each -- | 7339 jtwm 9 0 0.0 0:00.02: guess you'll just |__7337_root_______9___0__0.0___0:01.30: have to learn how |2__PID__PPID_Command____________TIME+_: to live with it. | 997 952 kdeinit 17:59.59: | 1115 952 kdeinit 2:16.47: |__1803__1116_led_______________1:55.30: |3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_: 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 |___991__7.2__9492__316_9176___12_9164_: sock 'em with the |4_UID_USER_____GROUP____TTY________PID: 'n' command and | 43 xfs xfs ? 806: take those lines, | 0 ykde users pts/7 5561: plus others, away! | 0 wgnome users pts/7 5560: | 0 root root pts/7 5325: +--------------------------------------+ So, what say we start applying some of those "full range of interac- tive commands"? Onward + Downward... -*- STACKIN' & WHACKIN' Windows -*- Whoa, hold on mate. Someone has already whacked these windows. See, there are no task areas for windows 1:Def and 4:Usr. Well, we can at least retrace their steps... Here's what was done, after issuing the 'A' command and entering alternate-display mode. 1) When #1 was the 'current' window, '-' was pressed, toggling Off the associated task display ( if 'l t m' had been applied to its summary, too ) ( then there'll be only a msg line when 'current' ) 2) Then the 'w' key was struck to cycle backward, making 4:Usr the 'current' window (could have used 'a a a', if one likes to type) 3) Then step #1 was repeated, and bye-bye window #4 4) Finally, window #2 was made the 'current' window ( Q. how many keystrokes were used? ) ( A. minimum of 2: 'a a' or 'w w'. ) +--------------------------------------+ No 'l','t','m','1' |2:Top - 15:48:35 up 16:27, 9 users, : commands have been |Tasks: 75 total, 1 running, 74 sle: issued here, |Cpu(s): 2.0% user, 0.7% system, : but... |Mem: 126588k total, 123712k used,: |Swap: 265032k total, 8232k used,: |______________________________________: #2's been changed; |2__PID__PPID_Command____________TIME+_: user applied a 'c' | 997 952 kdeinit: konsol 18:00.70: command (when it | 1115 952 kdeinit: konsol 2:16.47: was current) - now | 1803 1116 led tiptop.HELP 1:55.30: shows cmd lines 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 |___991_____1_kdeinit:_kicker___0:04.59: |3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_: 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 damage | 7329 7.0 9036 140 8896 36 8860 : might have been | 1115 6.9 8956 160 8796 36 8760 : done to it's | 987 6.4 8668 524 8144 20 8124 : summary info stuff | 1131 6.4 8268 144 8124 36 8088 : +--------------------------------------+ And that's what brought us to this current state. No, wait. Oh lordy, will you look at that -- someone has changed the name of win- dow #2 from 'Job' to 'Top'! How'd they do that? Well, they just issued the 'g' interactive com- mand, of course. That command is available whenever alternate-display mode is active and always impacts just the 'current' window. Gosh, you can even issue the 'g' command when 'l' has toggled Off the very summary area line containing the window name! Almost Done... -*- ALL TOGETHER Now, Window(s) -*- Here, the window 1:Def task display has been toggled Off but it remains the 'current' window. Since there is no task area, many com- mands will be restricted. However, the commands ('l', 't', 'm', '1') affecting the summary area, as well as some other global commands ('k', 'Z', etc.), would still be active. Notice that the Mem and Swap 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 'current' window with the 'a' or 'w' commands, the task display would remain the same (except possibly growing/shrinking slightly) but the summary area 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 -- the one with some empty rows... 1:Def no highlight, +--------------------------------------+ thus disabled cmds: |1:Def - 15:50:32 up 16:29, 9 users, : b,i,n,u,x,y, etc. |Tasks: 75 total, 2 running, 73 sle: & m = lost Mem/Swap |Cpu(s): 10.6% user, 0.0% system, : |______________________________________: 2:Job was very busy: |2__PID__PPID_Command____________TIME+_: 'n' cmd, w/ 7 tasks | 80 1 ( khubd ) 0:00.00: 'c' cmd, cmd line | 6 0 ( kreclaimd ) 0:00.00: 'O' cmd, sort cmd | 9 1 ( mdrecoveryd ) 0:00.00: 'R' cmd, sort bkwd | 11358 1 /bin/bash/ /usr 0:00.00: 'x' cmd, hi column | 1297 1 /sbin/mingetty 0:00.00: (when 2 WAS current) | 683 1 xinetd -stayali 0:00.00: |___836_____1_login_--_root_____0:00.00: 3:Mem has altered |3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_: some std defaults: | 4634 12.3 15620 0 15m 860 14m : 'y' turned Off | 7337 11.3 14396 92 13m 36 13m : 'x' turned On | 923 10.6 30544 16m 13m 1120 12m : (when 3 WAS current) | 991 7.2 9492 316 9176 12 9164 : |__7329__7.0__9036__140_8896___36_8860_: Huh? 4:Usr has some |4_UID_USER_____GROUP____TTY________PID: blank rows! ? ? ? ? | 0 jtwm root pts/2 5561: Aha, the 'i' command | 0 root root ? 5560: applied (when 4 WAS | : current); could be | : reversed with '=', | : when 4 IS current! +--------------------------------------+ Ok now, how about that 'current' window 1:Def and its unseen tasks? At any time, you can quickly retrieve lost tasks in a number of ways: 1) Press '-', toggling just the 'current' window 2) Press '_', toggling all visible/invisible windows ( 1:Def is the only window currently not shown ) ( afterward, it'll be the only window showing! ) * 3) Press '+', forcing all task displays to become visible 4) Press 'A' to return to full-screen mode, with only 1:Def tasks shown and without a window name Now that should be enough ways of getting a task area visible again to satisfy almost any user, don't ya think? Note: Use #3 above when you've messed up your screen beyond redemption. The four task displays will reappear, nice and even. They will also have retained any customizations you had previously applied, except for the 'i' (idle tasks) and 'n' (max tasks) com- mands. That's It ! Piece of Cake !! Enjoy them there windows !!!