In response to Issue #21, the commit referred to below
provided some much needed improvements and corrections
to topic `3a. DESCRIPTIONS of Fields' in the man page.
However, it assumed a reader possessed much background
knowledge that may not, in truth, actually be present.
So without, hopefully, insulting anyone's intelligence
this patch offers an expanded discussion of some terms
and concepts within a separate section under OVERVIEW.
[ plus it affords an opportunity to incorporate that ]
[ extremely useful table from Florent Bruneau's post ]
Reference(s):
commit f2a08cf16794ec6085bdecbaf8f7c2887cd4e87f
https://techtalk.intersec.com/2013/07/memory-part-1-memory-types/
Signed-off-by: Jim Warner <james.warner@comcast.net>
Due to quirks in kernel memory management plus limited
information available from /proc/<pid>/status & statm,
some of the top resident memory fields were capable of
exceeding available physical memory. So this commit is
a bit of a band-aid until the kernel has been changed.
Such a change appears to be on the horizon in the form
of three new fields to be added to /proc/<pid>/status.
While not preventing 'resident' memory from apparently
exceeding physical memory, the new fields will help to
clarify any such contingency, if/when we exploit them.
Reference(s):
. original post by Samuel Thibault
https://gitlab.com/procps-ng/procps/issues/21
. informative memory analysis
https://techtalk.intersec.com/2013/07/memory-part-1-memory-types/https://techtalk.intersec.com/2013/07/memory-part-2-understanding-process-memory/
. kernel changes to /proc/<pid>/status
commit 8cee852ec53fb530f10ccabf1596734209ae336b
commit eca56ff906bdd0239485e8b47154a6e73dd9a2f3
Signed-off-by: Jim Warner <james.warner@comcast.net>
It is documented behavior that when certain other keys
are active, sorts column highlighting will temporarily
be disabled. Among those keys is the 'L' (locate/find)
provision. The equals ('=') key can be used to restore
column highlighting by resetting other keys, except 1.
When a locate/find is active, the '=' key will have no
effect on 'x' column highlighting, which still remains
disabled. Further, when 'L' is active an 'x' keystroke
is processed changing the state of column highlighting
but without any visual clue (since it's yet disabled).
So this commit just extends the '=' key to embrace 'L'
processing resets, just like other highlight disabling
keys while avoiding 'x' state changes if approproiate.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch will bring three of our man pages into line
with the recent refactor of the libprocps wchan logic.
[ and also eliminates more damn eol whitespace which ]
[ snuck in our repo with the commit referenced below ]
Reference(s):
http://www.freelists.org/post/procps/WCHAN,11
commit cf4788c28d
Signed-off-by: Jim Warner <james.warner@comcast.net>
[ in addition to the primary 'lxc' business, i found ]
[ numerous apostrophes used instead of that back-tic ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
Let's not report zero for kb_main_available when older
kernels don't have MemAvailable. Instead, if we simply
duplicate the 'free' amount we can avoid all ancillary
problems, such as those involving top's graphing mode.
Reference(s):
http://www.freelists.org/post/procps/kb-main-available-etc,3
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch will trade a former pessimistic calculation
of free physical memory for a more optimistic one that
uses the newly added kb_main_available library export.
But in case one might wish to return to the old former
method, there's a new #define that was made available.
[ the new calculation will affect graphing mode only ]
Reference(s):
http://www.freelists.org/post/procps/systemd-support-to-library,9
Signed-off-by: Jim Warner <james.warner@comcast.net>
Wow, even the linux/Documentation/filesystems/proc.txt
document doesn't provide us with that level of detail.
Thank you, Jaromir, for your additional clarification!
Reference(s):
commit 411d218793
Signed-off-by: Jim Warner <james.warner@comcast.net>
For over a decade top has used a startup configuration
mimicking the original redhat top. This decision dates
back to when the forked Sourceforge version was trying
to win over users in battles with that ancient kludge.
Will anybody deny that those defaults are coyote ugly?
Well, it is time that top presented a more modern look
at startup, providing that no saved rcfile exists. But
just in case some distro prefers that old, comfortable
look, there's the '--disable-modern-top' build option.
[ Pssst. With the widened memory fields it turns out ]
[ the 'Mem' default window had become almost useless ]
[ on an 80x24 terminal since %CPU & COMMAND were out ]
[ of view. So some other defaults were tweaked a bit ]
[ whether or not --disable-modern-top was specified. ]
Reference(s)
http://www.freelists.org/post/procps/tops-graph-mode-saga-continues,3
Signed-off-by: Jim Warner <james.warner@comcast.net>
When those new cpu/memory graphs modes were introduced
they had global impact. In other words, the modes that
were chosen for a 'current' window affect Summary Area
appearance for every other window as well, even though
each window sets unique View_STATES/View_MEMORY flags.
I do not know how widespread the use of top's separate
window provisions is, but I do know that documentation
promises every window (field group) provides "a unique
separately configurable summary area". And even though
that promise does not include memory scaling (separate
'E' command) the graph modes are integral to 't' & 'm'
and those were already observed on a per window basis.
So this patch just takes the cpu and memory graph mode
values out of global scope in the configuration file &
gives each window its own unique pair of graph values.
Reference(s):
commit 1d171ec741
Signed-off-by: Jim Warner <james.warner@comcast.net>
While the 'b' toggle remains window based (vs. global)
it should no longer require that the window be visible
and either the 'x' or 'y' toggles to be on. Previously
those requirements were intended to remind a user that
there must be something for this command to highlight.
With the introduction of graph modes (specifically the
the bar graph) the 'bold/reverse' toggle has important
implications beyond highlighting some columns or rows.
The %Cpu(s) graph and Mem portion of the memory graphs
are designed to offer a visual clue as to the separate
elements comprising them. But that separation could be
lost under some X color schemes or when top is running
without color (in monochrome mode) and the block graph
is selected. But, if the graph is then changed to bars
any separation always becomes visible whenever the 'b'
toggle is turned off. Portions then show in 'reverse'.
So from now on we'll check nothing, we'll just toggle.
[ Besides, with all the code thrown at restricting a ]
[ 'b' toggle use, it might have all been for naught. ]
[ That toggle could still be set/unset using the 'Z' ]
[ command and the color mapping screen. Geez Louise! ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch just beefs up the man documentation for the
new graphs modes while also reflecting the most recent
program changes, prompted by the feedback shown below.
Reference(s):
http://www.freelists.org/post/procps/latest-top-enhancements,1
Signed-off-by: Jim Warner <james.warner@comcast.net>
In release 3.3.6, some commands were equipped with the
concept of a 'default pid'. The initial implementation
meant that the intuitive <Esc> key would not always be
treated as one would expect under any well behaved UI.
This patch ensures the expected <Esc> key behavior of:
terminating user input while still making possible the
necessary distinction between 'no input' & 'defaults'.
Reference(s):
http://www.freelists.org/post/procps/top-Escape-doesnt-abort-kill-command
Signed-off-by: Jim Warner <james.warner@comcast.net>
In addition to eliminating numerous single quote usage
this commit also escaped '\' a few overlooked hyphens.
And some 'unformatted' spacings were adjusted as well.
Signed-off-by: Jim Warner <james.warner@comcast.net>
The majority of changes in this commit are intended to
enable translation of top's man page. There were three
kinds of errors as seen by that po4a-updatepo program.
. a valid but unrecognized request concerning no-break
. an internally defined macro with a groff .de request
. occasional apostrophe at the beginning of some lines
With respect to the apostrophe, some have been changed
to back-tic since line placement could not be assured.
And other parts were re-flowed to avoid temptations to
escape as \' (technically an acute accent). Of course,
the opening back-tic with closing apostrophe looks odd
when ASCII, but should be rendered correctly as UTF-8.
It may yet be necessary to change the remaining single
'opening' quotes to back-tics as translation proceeds.
Should that become necessary, I intend to reduce quote
usage to the bare minimum throughout the man document.
There were also some formatting changes to enhance the
man2html output and then to other formats via htmldoc.
And, I wish to acknowledge that my meager groff skills
do not serve those programs very well at all. In other
words groff yet remains mostly incomprehensible to me.
Lastly a few content plus copyright updates were made.
Message(s):
. Unknown macro '.c2 `'. Remove it from the document, or refer to the Locale::Po4a::Man manpage to see how po4a can handle new macros.
. This page defines a new macro with '.de'. Since po4a is not a real groff parser, this is not supported.
. Unknown macro ''real time' scheduling priority.'. Remove it from the document, or refer to the Locale::Po4a::Man manpage to see how po4a can handle new macros.
Reference(s):
. oriiginal post/patch
http://www.freelists.org/post/procps/Translations-for-man-pages
Signed-off-by: Jim Warner <james.warner@comcast.net>
Confession is supposed to be good for the sole, right?
After a senior moment regarding the 'x' toggle quirks,
and thinking top had somehow regressed, I concluded an
additional explanatory note might well be appropriate.
Those quirks were already documented under the 5d & 5e
topics. But there was no such caution documented under
the 'x' command explanation itself, found in topic 4c.
Signed-off-by: Jim Warner <james.warner@comcast.net>
The .Bd and .Ed macros, from the mdoc collection, have
caused a few raised eyebrows (lintian, doclifter, etc)
in the past. With this commit, we will trade their use
for the standard existing groff .nf & .fi equivalents.
Signed-off-by: Jim Warner <james.warner@comcast.net>
Some versions of man have had trouble with the leading
apostrophe employed with interactive commands/toggles.
Instead, a '?' would be displayed in their place. With
this patch all such conventions have now been removed.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit provides the NEWS and man document changes
supporting the new NUMA/Node top program enhancements.
For providing the initial impetus for this enhancement
I wish to thank Lance Shelton <LShelton@fusionio.com>.
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Signed-off-by: Jim Warner <james.warner@comcast.net>
Signed-off-by: Lance Shelton <LShelton@fusionio.com>
This commit involves very little content change and is
more concerned with better formatting for readability.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit provides the hard copy support for our new
'Other Filter' feature. The man document contains some
potentially useful examples and it will be interesting
to see what use this new tool is put to in the future.
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Signed-off-by: Jim Warner <james.warner@comcast.net>
After revisiting the issue of a new field, combining 2
existing fields (RES and SWAP), I've decided it indeed
makes sense. After all, with the vastly expanded field
capability and the ease of adding new fields, it would
save some precious horizontal screen real estate while
also eliminating some mental/manual user calculations.
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Reference(s):
http://www.freelists.org/post/procps/top-enhancements-i-hopehttp://www.freelists.org/post/procps/top-regression-reports
Signed-off-by: Jim Warner <james.warner@comcast.net>
top/top.1 | 23 ++++++++++++++---------
top/top.c | 14 ++++++++++++--
top/top.h | 6 ++++++
top/top_nls.c | 3 +++
4 files changed, 35 insertions(+), 11 deletions(-)
With this commit, users can now retrieve previous line
input for re-editing and/or re-input using the Up/Down
arrow keys (or their aliases). This mirrors the 'bash'
or 'less' interface and represents a major enhancement
achieved via a somewhat minor impact to our code base.
[ 33 lines of code, 5 closing braces & some comments ]
[ all in 1 function, when TERMIOS_ONLY isn't defined ]
Currently, the upper limit for such recallable strings
has been set at 50 but that could be easily increased.
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Signed-off-by: Jim Warner <james.warner@comcast.net>
With this commit top can now display users which match
a user id/name or just those users which do not match.
The distinction is based on the presence or absence of
a leading exclamation point '!' (C negation operator).
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Reference(s):
Wishlist, http://bugs.debian.org/682086
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit corrects one reference to 'decimal place'.
Even though a running top supports a delay interval of
unlimited precision, and a delay interval of thousands
of a second in the rcfile, we intentionally imply that
any delay interval is limited to tenths of a sec only.
Later in the man document, in section 7a, one finds an
admission that a user can set any desired delay value.
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Reference(s):
http://www.freelists.org/post/procps/tt,4
Signed-off-by: Jim Warner <james.warner@comcast.net>
There existed a small chance that the display could be
corrupted when a search string was found within a row.
For that to happen, conditions like these were needed:
. a very short Locate string was active in some window
. the string matched part of a terminfo <esc> sequence
. that sequence was used in highlighting running tasks
. the 'x' toggle was active (sort column highlighting)
One solution to this potential problem was to manually
turn off sort column highlighting before using Locate.
But rather than rely on a user remedy, we'll automate.
Since other top provisions were already being enforced
when Locate was in use (off 'i' and/or 'u'/'U'), we'll
now also force column highlighting off when the search
string in a given window is not empty. However, unlike
idle tasks and user filtering, when that search string
*is* emptied, we restore highlighting for that window.
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit just addresses the following minor issues:
. restored both lost end-of-job reporting capabilities
. added missing initializers to the DEF_RCFILE #define
. added 'nls_maybe' eye-catcher to the 'Scaled_sfxtab'
. removed a now superfluous 'READMINSZ' assertion test
. man document references to 'top' are more consistent
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Signed-off-by: Jim Warner <james.warner@comcast.net>
In a effort to anticipate a potential future wishlist,
the recent '-o' sort override command line switch will
now support an override of the sort direction as well.
By prepending a '+' or '-' to any valid field name the
user will be able to guarantee a specific desired sort
direction. The '+' forces a high-to-low (normal) order
while a '-' reverses that to yield a low-to-high sort.
Without this addition users would be left to the mercy
of whatever was last specified for Curwin as reflected
in the rcfile or top's default of a high-to-low order.
(everything is perfectly justified plus right margins)
(are completely filled, but of course it must be luck)
Signed-off-by: Jim Warner <james.warner@comcast.net>
The recent change to task area memory scaling was just
a little short of optimum in its consistency and upper
limits. In fact, top could only scale memory fields up
to a maximum of 99.9999 TiB (with VIRT a little more).
While that seems like more than enough it was actually
artificially low, due to an unnecessary decimal place.
So, this commit standardizes both precision and widths
to achieve a minimum amount of scaling beyond the user
requested target plus reclaim some horizontal spacing.
. VIRT & DATA are now 7 bytes wide (not eight and six)
. other memory fields are 6 wide (were formerly seven)
. as before, KiB shows whole numbers only (no decimal)
. MiB, for its precision, shows a single decimal place
. all other memory ranges display three decimal places
The net result is a more homogeneous display with less
forced scaling and the recovery of three lost columns.
(now that we know a '.' + 2 spaces is squeezed to one)
(everything's perfectly justified, but it's just luck)
Reference(s);
http://www.freelists.org/post/procps/top-enhancements-i-hope,1
Signed-off-by: Jim Warner <james.warner@comcast.net>
Everyone has either accepted this potential distortion
or patched top to eliminate it. Now, the time has come
to regain some consistency when calculating that %CPU.
We'll now limit such values to: 100.0 * total threads.
And, it took way too long to address this little flaw.
(now that we know a '.' + 2 spaces is squeezed to one)
(everything's perfectly justified, but it's just luck)
Reference(s):
http://www.freelists.org/post/procps/top-regression-reportshttp://www.freelists.org/post/procps/top-regression-reports,1
Signed-off-by: Jim Warner <james.warner@comcast.net>
With the increased width and precision of memory and %
columns, the proliferation of 0's when there's nothing
to report seems like a distraction versus useful data.
This commit introduces the '0' toggle which can either
display or suppress those zeros. And, like the scaling
states this new state is also preserved in the rcfile.
(now that we know a '.' + 2 spaces is squeezed to one)
(everything's perfectly justified, but it's just luck)
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is an unrequested outgrowth of the earlier
change dealing with summary area memory field scaling.
That user selectable scaling provision is now extended
to include 6 (at present) task oriented memory fields.
The new companion 'e' (lower case) interactive command
has been added and, like the 'E' command, it can cycle
each of the currently displayed memory columns between
KiB through TiB. There are, however, some differences.
Where '+' indicates summary area truncation at a given
radix, task memory fields are automatically scaled for
their column. Thus, not all rows use the same scaling.
And, while summary area field widths were not changed,
the task memory columns were widened in order to offer
more meaningful data when the radix was increased. The
precision is automatically increased in step with each
radix: MiB displays 2 decimal places, GiB 3 and TiB 4.
To compliment that additional precision, both the %CPU
and %MEM fields were widened by 1 column and now offer
precision up to 3 decimal places. But, unique to %CPU,
widening could already have occurred due to the number
of processors in some massively parallel boxes. At any
rate, total extra width for both memory and percentage
fields could amount to twenty (precious) columns more.
So for both the memory and % fields the original width
(along with loss of precision) can be restored via new
compiler conditionals which this commit also provides.
p.s. and it will be rcfile preserved for any restarts!
(now that we know a '.' + 2 spaces is squeezed to one)
(everything's perfectly justified, but it's just luck)
Reference(s):
http://www.freelists.org/post/procps/top-regression-reports
Signed-off-by: Jim Warner <james.warner@comcast.net>
Earlier this year, the switch from KiB to Mib as shown
in top's summary area was postponed to those occasions
when KiB exceeded 8 digits. In hindsight that may have
moved top in the wrong direction, given the difficulty
of digesting such large numbers of digits at a glance.
This commit adds a new 'E' interactive command used to
cycle the displayed memory amounts ranging from KiB to
TiB. Thus, users can choose the radix they wish shown.
p.s. and it will be rcfile preserved for any restarts!
(now that we know a '.' + 2 spaces is squeezed to one)
(everything's perfectly justified, but it's just luck)
Reference(s):
http://www.freelists.org/post/procps/top-regression-reports
commit 95f2201730
Author: James Cloos <cloos@jhcloos.com>
Date: Mon Feb 6 00:00:00 2012 -0500
Signed-off-by: Jim Warner <james.warner@comcast.net>
This 'Sleeping in function' field was made variable
width because the length of current kernel symbols
usually exceeded the former top's 9 character limit.
As a variable width field it would steal valuable
horizontal display positions from other, more likely,
displayed fields such as COMMAND or CGROUPS.
With the advent of the new 'X' toggle, no fixed-width
non-scalable field need suffer permanent truncation.
Thus, WCHAN is being made fixed width with a default
size of 10 characters.
Signed-off-by: Jim Warner <james.warner@comcast.net>
top/top.c | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
I have no idea what the maximum length of a terminal
name might be. However, the library provides for up
to 128 characters (ouch).
So just to be safe, this commit extends the ability
to widen columns to embrace this field.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This flaw was revealed under 'man2htm' and dates back
to the first Gitorious revised top submission.
Reference:
commit fd62123562
Date: Thu Mar 31 22:15:12 2011 +1100
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit represents mostly spelling corrections
in comments. It also includes a few very minor logic
changes/relocations.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This section purported to list fields in alphabetical
order, but this was not always true.
With this commit, strict ascii collating sequence is
now observed.
Signed-off-by: Jim Warner <james.warner@comcast.net>
All warnings where about unnecessary quoting. The scriptlet
below will tell what was wrong.
for I in ./top/top.1 ./ps/ps.1 ./*.[0-9]; do
echo "== $I warnings =="
man --warnings=all $I > /dev/null
done
This should probably be turned to 'make check' script.
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
Since its inception top has provided for monitoring
only specific process ids via the -p command line
switch. This provision has also embraced the top
process itself, even though its pid wasn't yet known.
This commit simply documents the special zero value,
which would otherwise be an invalid process id.
Signed-off-by: Jim Warner <james.warner@comcast.net>
Admittedly, top referred to memory quantities in
a variety of non-standard ways. This commit brings
the program and supporting documentation into strict
compliance with IEC standard binary names.
According to wikipedia, as of 2012 this IEC standard
was still not in widespread use. However, I'm making
this change now for the anal-retentive among us.
Reference:
http://en.wikipedia.org/wiki/Megabyte
Reported by: Roman Mamedov <rm@romanrm.ru>
Bug-Debian: http://bugs.debian.org/662786
Signed-off-by: Jim Warner <james.warner@comcast.net>
