1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
|
Credit for this belongs to:
Jim / James C. Warner, <warnerjc@worldnet.att.net>
----------------------------------
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 <bleep> 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 <sp>thingy<sp> 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 !!!
|