1 Credit for this belongs to:
2 Jim / James C. Warner, <warnerjc@worldnet.att.net>
4 ----------------------------------
6 Ok, ok, I yield -- most of what follows has been removed from the manual page
7 and packaged separately as this README (hey, it was only TEMPORARY insanity).
9 Of course, that means that now absolutely nobody will ever read it.
11 This is probably a good thing...
14 ## Table of Contents ---------------------------------------------------##
15 # the only darn thing that wasn't in the man page
16 CUSTOMIZING the Sources
17 # the following carry their original topic numbers
18 DIFFERENCES / New Features
20 Expanded Configurable Display Support
21 Enhanced Field/Column Management
22 Customization Flexibility
29 The 'A' Mode Command Toggle
30 STACKIN' & WHACKIN' Windows
31 ALL TOGETHER Now, Window(s)
34 ## CUSTOMIZING the Sources ---------------------------------------------##
36 Listed below are the conditionals available should you wish to recompile
37 this top. The author's favorite is: PRETEND4CPUS.
39 That's the #define allowing you to simulate an SMP environment, and
40 (perhaps) impress your friends. It's currently set to display four
41 separate CPUs, but could easily be changed.
43 Caution: do NOT use this provision in an effort to impress someone
44 who truly possesses such a machine! The fact that all 4
45 CPUs show the same dynamic results will likely have the
49 //#define ATEOJ_REPORT /* report a bunch of stuff, at end-of-job */
50 //#define CASEUP_HEXES /* show any hex values in upper case */
51 //#define CASEUP_SCALE /* show scaled time/num suffix upper case */
52 //#define CASEUP_SUMMK /* show memory summary kilobytes with 'K' */
53 //#define POSIX_CMDLIN /* use '[ ]' for kernel threads, not '( )' */
54 //#define PRETEND2_5_X /* pretend we're linux 2.5.x (for IO-wait) */
55 //#define PRETEND4CPUS /* pretend we're smp with 4 ticsers (sic) */
56 //#define PRETENDNOCAP /* use a terminal without essential caps */
57 //#define SORT_SUPRESS /* *attempt* to reduce qsort overhead */
58 //#define STDOUT_IOLBF /* disable our own stdout _IOFBF override */
59 //#define USE_LIB_STA3 /* use lib status (3 ch) vs. proc_t (1 ch) */
60 //#define WARN_NOT_SMP /* restrict '1' & 'I' commands to true smp */
63 ## 6. DIFFERENCES / New Features ---------------------------------------##
64 The following summarizes differences between this top and your
65 former top. It was originally based on procps-2.0.7. However,
66 except for the separate/summary CPU toggle, all of these differ-
67 ences also apply through procps-2.0.10.
69 6a. Interface Etiquette
70 -*- Input and output are far more carefully implemented in
71 this top. You won't be subjected to 4 - 5 'Unknown command'
72 messages should you press the wrong key.
74 -*- You need suffer a confirmation message only when the results
75 of a command are not obvious by their effects on the display.
77 -*- The Help screen will no longer overflow, even when running
78 with a 24 row xterm (vt100).
80 -*- The fields selection/ordering screens do not carelessly
81 destroy important information through unintended line wraps.
83 -*- Should you narrow a xterm window to less than 80 columns
84 while this top is running, you will not be left with an
85 utterly worthless, embarrassing display.
87 6b. Expanded Configurable Display Support
88 -*- In an SMP environment, you can choose between a summary dis-
89 play or you may show each cpu separately. No longer must
90 this choice be irrevocably made at startup.
92 -*- There are new fields and with this top, any field is
93 selectable for sorting. Plus, your sorted column can be
94 instantly reversed with just a single keystroke.
96 -*- You may optionally apply 2 distinct types of highlighting to
97 running tasks and/or sorted columns. With this top, you'll
98 be able to instantly spot running tasks and always know the
101 -*- While you could continue to use the more familiar (and
102 boring) monochrome display, you might want to try this top's
103 new color display. You can even create your own unique col-
104 ors used in summaries, messages, headings and tasks, each of
105 which can be made persistent until you choose to change them.
107 -*- Up to four separate windows can be displayed simultaneously,
108 giving you four separate ways to sort and view the tasks cur-
109 rently cluttering up your system. You could have one view by
110 pids, another by cpu usage, yet another showing memory con-
111 sumption. You get the idea...
113 -*- Each window comes with pre-configured (but user configurable)
114 fields and you can size each window individually.
116 -*- Virtually every one of this top's options (summaries, fields,
117 colors, sorted column, etc.) is separately configurable for
118 each of those four windows.
120 Heck, you can even change a window's name, if you don't care
121 for top's choices. Your changes will be reflected not only
122 when you're in what top calls alternate-display mode but also
123 on his special new 'Windows' help screen.
125 -*- And, [ ** Drum-Roll + Ta-Da ** ] with just one keystroke you
126 can quickly switch between full-screen and multiple window
127 modes! Or, with a different keystroke, toggle a single win-
128 dow Off for now, then On again later!!
130 6c. Enhanced Field/Column Management
131 -*- Many Field/Column names have been changed to make them more
132 intuitive, more self-descriptive. And with this top you
133 won't be fooled with field choices that are "not yet imple-
136 -*- Task memory statistics are more meaningful and more accurate.
138 -*- You'll finally have complete display integrity regardless of
139 field selections, their order or screen width. And that
140 means the command column no longer need be kept as the right-
141 most field, lest your screen turn to <bleep> when all the
142 following columns get misaligned.
144 6d. Customization Flexibility
145 -*- You have complete program naming freedom with no internal
146 ties to a specific personal configuration file. Symbolic
147 links could be used to establish different configuration
148 files reflecting the different personalities of your cus-
149 tomized "tops", under whatever aliases you've used.
151 Thus, you could have an alias for running top in 'Batch
152 mode', another for when you work from the Linux console and
153 maybe a third used with X-Windows. All of that, yet still
154 just a single binary image!
156 -*- All of your configuration choices can be preserved in a per-
157 sonal configuration file, including any changes made on a
158 per-window basis. Thus, once you personalize things they
159 remain personalized until you decide to change them again.
160 This top has been completely cured of:
161 i-cant-remember-so-please-do-that-all-over-again
162 ( and again, and again ... )
164 The bottom line is this: if you save your configuration
165 before quitting top, upon restart the display will appear
166 exactly as you left it. And that means you no longer have to
167 keep top running until-the-end-of-time (ok, a long time
168 anyway), lest your customizations go bye-bye.
171 ## 7. NOTES and Rantings -----------------------------------------------##
173 To whom it may (should) concern: this top, even with its vastly
174 expanded capabilities, is only slightly larger than the old top.
175 Were it not for extensive help text and additional sort callbacks,
177 Throw source carelessly at objectives, it will
178 produce equally careless machine instructions.
179 example: (num_pages - an_address)/1024 == duh?
180 kicker: document result as broken, due to elf!
181 ----------------------------------------------
182 I know you're out there, are you getting this?
184 Now, as for all those new capabilities like colors and windows and
185 highlighting, you'd expect this top to be the "mother of all pigs"
186 compared to old top -- right?
188 Yea, with this top expect following piglets:
189 . A smaller virtual image and resident footprint
190 . Slightly fewer major page faults
191 . A large reduction in minor page faults for SMP
192 . The same or better response time
193 . The same or even less CPU costs
195 Ideally any comparison of the old and new top should be against
196 the same libproc format (32-bit or 64-bit tics) and run in a true
197 or simulated SMP environment (producing separate CPU stats). This
198 latter requirement will coax old top into handling his own
199 '/proc/stat' access -- something this top always does, but with
202 7b. Comparing Performance
203 Even with equivalent libraries and '/proc/stat' access, it's dif-
204 ficult to accurately compare tops using their own displays.
205 Results for these cpu-intensive programs (who frequently exceed
206 their time-slice) generally show a wide disparity in %CPU. This
207 is due to differing call patterns, kernel preemptions and the tim-
208 ing of process snapshots. For slightly better results, start each
209 program with the following commands:
211 nice -n-10 ./new-top -d 0.4
213 While actually putting this top at a performance disadvantage, the
214 higher scheduling priority and staggered timing will periodically
215 yield a somewhat truer picture. You could even reverse those
216 roles and get similar results.
218 The most consistent performance results will be obtained 'off-
219 line', using your shell's time pipe or the time program itself.
220 And even in a single processor environment or without equivalent
221 libraries, total cpu costs (user time + system time) are similar.
223 However, this top's cpu costs ARE influenced by the capabilities
224 you choose to exploit, even if they don't SEEM to be reflected in
225 such timings. So let's examine some...
228 Colors Cost -- Nada (almost).
229 Once the terminfo strings are built (at and during a user's
230 behest) they are SAVED with each window's stuff. And while
231 there will be extra tty escape sequences transmitted because of
232 colors, it makes no difference which 'char *' is actually used.
234 Highlighting Cost -- Nada (maybe), or blame it on Rio.
235 On second thought, let's blame it on the user.
237 For row highlighting, there is only the cost of those extra tty
238 escape sequences (same as for colors). For column highlight-
239 ing, there is a fairly significant cost associated with column
240 transition management combined with even more tty output.
241 These increased costs are incurred on every task display row.
243 Sooo... hey USER -- do NOT highlight COLUMNS. You shouldn't
244 need a constant visual reminder of your chosen sort field.
245 However, if you forget which field top is sorting it can serve
246 as a quick visual reminder.
248 Windows Cost -- Nada (if just 1 window).
249 If more than 1 window, almost certainly NOT Nada so blame it on
250 reality. Colors are not an issue, but those sort fields are.
252 If we could trust the user to always select the same 'c' state,
253 'S' state and sort field (hey, why ya got multiple windows then
254 user, huh?) AND if we can trust someone to recompile top with a
255 #define enabled, then we could achieve 'Nada'.
257 Ok, not likely, so we're gonna' be doing multiple sorts. BUT,
258 it may not be as bad as it sounds. Those sorts involve point-
259 ers only. And, that's as good as it gets ! (right Mr. N?)
263 Unlike his predecessor, this top has a proper header file. It
264 contains ONLY declarations, NOT definitions. And there are
265 several conditionals present to help with further customiza-
266 tions and experimentation. All are Off by default.
269 Hopefully proves that source code needn't be a disorganized,
270 misaligned MESS. And, WHO says a source listing shouldn't
271 occasionally make you SMILE? Why, top.c even does a darn good
272 job of following the suggestions in a document hardly anybody
275 the Linus Torvalds CodingStyle guidelines ...
276 -*- -*- -*- on indentation + etc. -*- -*- -*-
277 well almost all, except for those stinkin'...
279 I suppose even Linus Torvalds is entitled to err now and again.
280 How so you say? Tabs, me' bucko, stinkin' tabs! That, plus the
281 simplistic position regarding indentation espoused in that other-
282 wise excellent document.
284 -*- Rant On, and on -*-
285 Let's compare two approaches to the tab/indentation issue with a
286 small code sample using tabs then spaces. This snippet happens to
287 be the key to top's use of dynamic colors on many static screens,
288 while also ensuring screen width isn't exceeded so as to avoid
289 line wraps. We'll view just the first 40 columns, assuming one
290 wishes to occasionally provide comments to the right of actual
291 code (you do, don't you?).
293 Then YOU decide which approach makes the most SENSE!
295 Stinkin' Tabs versus Spaces: the Linus way
296 Hey, where'd my +----+----1----+----2----+----3----+----4+
297 many code lines | while (*sub_beg) { :
298 up-and-gone-to? | switch (*sub_end:
300 Gosh, wonder if | \ Tabs Induced / :
301 Linus expects a | case 1: :
302 fellow to stick | + WASTE-Lands! + case 5: :
304 the left side?! | + Not a Living + :
306 Ever see source | + line-of-code + :
308 whitespace; and | / To Be Found! \ :
309 this is better? | default::
311 Oh lookie here, \ } :
312 there's just a hint of REAL code! ----> if (0 >= room) b:
313 / } /* end: while 'subtrin:
314 +----------------------------------------+
316 Spaces versus Stinkin' Tabs: the other way
317 +----+----1----+----2----+----3----+----4+
318 Wow, now this is | while (*sub_beg) { :
319 Visible hackin'! | switch (*sub_end) { :
321 Hmmm, wonder how | *(sub_end + 1) = '\0'; :
322 many programmers | case 1: case 2: case 3: case:
323 read those lines | case 5: case 6: case 7: case:
324 from the LEFT to | cap = Curwin->captab[(int:
325 the RIGHT? This | *sub_end = '\0'; :
326 "innovation" may | PUTP("%s%.*s%s", cap, roo:
327 possibly benefit | room -= (sub_end - sub_be:
328 those particular | sub_beg = ++sub_end; :
329 kinds of people, | break; :
330 you agree? Duh! | default: :
332 AND, there might | } :
333 even be room for | if (0 >= room) break; :
334 unseen comments! | } /* end: while 'subtrings' */ :
335 +----------------------------------------+
337 Gosh, I just don't KNOW -- it's such a TOUGH choice...
339 Oh you Stinkin' Tabs: correspondence, Who-Cares; documentation,
340 Oh-Alright; even scripts, Well-If-You-Must. But you have NO place
341 within the code-space of MY C-source listing! So be gone
345 - If you want to use tabs to the right of the code, go-for-it.
346 But PLEASE, not ever in the C-source code-space, thank-you-
347 kindly. Just use three little ol' spaces (exactly 3, no-more,
348 no-less) where you WOULD have stuck a stinkin' tab.
350 We'll get far more READABLE files, much less WAISTED precious
351 horizontal space, more consistent CURSORS and on, and ON, AND
352 ON! Plus, without those awful *the-devil's-own-handiwork*, the
353 aforementioned document need NEVER speak of their EVILS again.
355 - Lastly, since SPACES (not stinkin' tabs) are SO beneficial,
356 maybe we should use just a few more of 'em. Some of those C-
357 thingies are VERY sensitive -- they don't like being TOUCHED
358 by any other syntax element! Which ones? Why these guys:
360 braces, reserved words and binary operators
361 ( it's the TRUTH, they told me themselves )
363 It's so EASY to keep 'em HAPPY! And lo-and-behold, the combi-
364 nation of <sp>thingy<sp> turns out to be a darn effective bug
365 repellent, too. So much so, one can actually code while
366 TOTALLY NUDE yet still avoid them ol' bug-bytes (sic-sic)!
374 ## 4c. EXAMPLES of Windows ---------------------------------------------##
376 -*- The 'A' Mode Command Toggle -*-
377 Here's what you'll see when you first invoke the alternate-display
378 mode interactive command.
380 This particular display was produce on a VT100 xterm, with only 24
381 rows. All four task displays are visible, but they could not be sized
382 the same. Available lines are parceled out in the fairest way possi-
383 ble so the last two task displays have an extra line each.
385 Notice the 'current' window name in the summary area -- it's been
386 emphasized because the associated task display is visible. Since
387 1:Def has a task area, the full range of interactive commands would be
388 at your disposal. But remember, many of those commands will apply
389 only to window 1:Def.
391 +--------------------------------------+
392 1:Def name is bold, |1:Def - 15:46:37 up 16:25, 9 users, :
393 thus all commands |Tasks: 76 total, 1 running, 75 sle:
394 will be available. |Cpu(s): 0.7% user, 1.3% system, :
395 |Mem: 126588k total, 123688k used,:
396 |Swap: 265032k total, 8232k used,:
397 |______________________________________:
398 Tough luck windows |1__PID_USER______PR__NI_%CPU____TIME+_:
399 #1 & 2 - you lost | 7343 jtwm 16 0 0.9 0:00.59:
400 one line each -- | 7339 jtwm 9 0 0.0 0:00.02:
401 guess you'll just |__7337_root_______9___0__0.0___0:01.30:
402 have to learn how |2__PID__PPID_Command____________TIME+_:
403 to live with it. | 997 952 kdeinit 17:59.59:
404 | 1115 952 kdeinit 2:16.47:
405 |__1803__1116_led_______________1:55.30:
406 |3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_:
407 The #3 & #4 windows | 4634 12.3 15620 0 15m 860 14m :
408 better not gloat | 7337 11.3 14396 92 13m 36 13m :
409 over 1 extra line. | 923 10.6 30524 16m 13m 1120 12m :
410 That user could yet |___991__7.2__9492__316_9176___12_9164_:
411 sock 'em with the |4_UID_USER_____GROUP____TTY________PID:
412 'n' command and | 43 xfs xfs ? 806:
413 take those lines, | 0 ykde users pts/7 5561:
414 plus others, away! | 0 wgnome users pts/7 5560:
415 | 0 root root pts/7 5325:
416 +--------------------------------------+
418 So, what say we start applying some of those "full range of interac-
423 -*- STACKIN' & WHACKIN' Windows -*-
424 Whoa, hold on mate. Someone has already whacked these windows. See,
425 there are no task areas for windows 1:Def and 4:Usr. Well, we can at
426 least retrace their steps...
428 Here's what was done, after issuing the 'A' command and entering
429 alternate-display mode.
430 1) When #1 was the 'current' window, '-' was pressed,
431 toggling Off the associated task display
432 ( if 'l t m' had been applied to its summary, too )
433 ( then there'll be only a msg line when 'current' )
434 2) Then the 'w' key was struck to cycle backward,
435 making 4:Usr the 'current' window
436 (could have used 'a a a', if one likes to type)
437 3) Then step #1 was repeated, and bye-bye window #4
438 4) Finally, window #2 was made the 'current' window
439 ( Q. how many keystrokes were used? )
440 ( A. minimum of 2: 'a a' or 'w w'. )
442 +--------------------------------------+
443 No 'l','t','m','1' |2:Top - 15:48:35 up 16:27, 9 users, :
444 commands have been |Tasks: 75 total, 1 running, 74 sle:
445 issued here, |Cpu(s): 2.0% user, 0.7% system, :
446 but... |Mem: 126588k total, 123712k used,:
447 |Swap: 265032k total, 8232k used,:
448 |______________________________________:
449 #2's been changed; |2__PID__PPID_Command____________TIME+_:
450 user applied a 'c' | 997 952 kdeinit: konsol 18:00.70:
451 command (when it | 1115 952 kdeinit: konsol 2:16.47:
452 was current) - now | 1803 1116 led tiptop.HELP 1:55.30:
453 shows cmd lines vs. | 923 922 X :0 1:09.60:
454 program names; | 973 1 klaptopdaemon 0:59.63:
455 still seems to be | 981 952 /usr/bin/artsd 0:48.63:
456 sorted on TIME+ | 987 1 kdeinit: kdeskt 0:24.34:
457 though |___991_____1_kdeinit:_kicker___0:04.59:
458 |3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_:
459 This #3 guy appears | 4634 12.3 15620 0 15m 860 14m :
460 to still be running | 7337 11.3 14396 92 13m 36 13m :
461 with the supplied | 923 10.6 30544 16m 13m 1120 12m :
462 defaults, but no | 991 7.2 9492 316 9176 12 9164 :
463 telling what damage | 7329 7.0 9036 140 8896 36 8860 :
464 might have been | 1115 6.9 8956 160 8796 36 8760 :
465 done to it's | 987 6.4 8668 524 8144 20 8124 :
466 summary info stuff | 1131 6.4 8268 144 8124 36 8088 :
467 +--------------------------------------+
469 And that's what brought us to this current state. No, wait. Oh
470 lordy, will you look at that -- someone has changed the name of win-
471 dow #2 from 'Job' to 'Top'!
473 How'd they do that? Well, they just issued the 'g' interactive com-
474 mand, of course. That command is available whenever alternate-display
475 mode is active and always impacts just the 'current' window. Gosh,
476 you can even issue the 'g' command when 'l' has toggled Off the very
477 summary area line containing the window name!
481 -*- ALL TOGETHER Now, Window(s) -*-
482 Here, the window 1:Def task display has been toggled Off but it
483 remains the 'current' window. Since there is no task area, many com-
484 mands will be restricted. However, the commands ('l', 't', 'm', '1')
485 affecting the summary area, as well as some other global commands
486 ('k', 'Z', etc.), would still be active.
488 Notice that the Mem and Swap lines are not shown. This means that the
489 loser (oops, user) has, in fact, issued the 'm' command! Now, if you
490 were to cycle the 'current' window with the 'a' or 'w' commands, the
491 task display would remain the same (except possibly growing/shrinking
492 slightly) but the summary area would change periodically.
494 The comments to the left of the image provide additional insights into
495 how things came to be. Note especially the comments for window 4:Usr
496 -- the one with some empty rows...
498 1:Def no highlight, +--------------------------------------+
499 thus disabled cmds: |1:Def - 15:50:32 up 16:29, 9 users, :
500 b,i,n,u,x,y, etc. |Tasks: 75 total, 2 running, 73 sle:
501 & m = lost Mem/Swap |Cpu(s): 10.6% user, 0.0% system, :
502 |______________________________________:
503 2:Job was very busy: |2__PID__PPID_Command____________TIME+_:
504 'n' cmd, w/ 7 tasks | 80 1 ( khubd ) 0:00.00:
505 'c' cmd, cmd line | 6 0 ( kreclaimd ) 0:00.00:
506 'O' cmd, sort cmd | 9 1 ( mdrecoveryd ) 0:00.00:
507 'R' cmd, sort bkwd | 11358 1 /bin/bash/ /usr 0:00.00:
508 'x' cmd, hi column | 1297 1 /sbin/mingetty 0:00.00:
509 (when 2 WAS current) | 683 1 xinetd -stayali 0:00.00:
510 |___836_____1_login_--_root_____0:00.00:
511 3:Mem has altered |3__PID_%MEM__VIRT_SWAP__RES_CODE_DATA_:
512 some std defaults: | 4634 12.3 15620 0 15m 860 14m :
513 'y' turned Off | 7337 11.3 14396 92 13m 36 13m :
514 'x' turned On | 923 10.6 30544 16m 13m 1120 12m :
515 (when 3 WAS current) | 991 7.2 9492 316 9176 12 9164 :
516 |__7329__7.0__9036__140_8896___36_8860_:
517 Huh? 4:Usr has some |4_UID_USER_____GROUP____TTY________PID:
518 blank rows! ? ? ? ? | 0 jtwm root pts/2 5561:
519 Aha, the 'i' command | 0 root root ? 5560:
520 applied (when 4 WAS | :
521 current); could be | :
522 reversed with '=', | :
523 when 4 IS current! +--------------------------------------+
525 Ok now, how about that 'current' window 1:Def and its unseen tasks?
526 At any time, you can quickly retrieve lost tasks in a number of ways:
527 1) Press '-', toggling just the 'current' window
528 2) Press '_', toggling all visible/invisible windows
529 ( 1:Def is the only window currently not shown )
530 ( afterward, it'll be the only window showing! )
531 * 3) Press '+', forcing all task displays to become visible
532 4) Press 'A' to return to full-screen mode,
533 with only 1:Def tasks shown and without a window name
535 Now that should be enough ways of getting a task area visible again to
536 satisfy almost any user, don't ya think?
538 Note: Use #3 above when you've messed up your screen beyond
539 redemption. The four task displays will reappear, nice and even.
540 They will also have retained any customizations you had previously
541 applied, except for the 'i' (idle tasks) and 'n' (max tasks) com-
544 That's It ! Piece of Cake !! Enjoy them there windows !!!
projects / external / procps.git / blob