What had been stated as the contents of the cpu graphs
was never really inclusive enough. Those recent newlib
tweaks highlighted the need for these man doc changes.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch may be a little misleading in terms of size
since most of the changes just reorder a little logic.
The most significant changes involve two GUEST values.
My original implementation excluded such tics from the
TOTAL calculation and, therefore, the BUSY figure too.
That decision was erroneously based on some code found
in ./kernel/sched/cputime.c which in hindsight applies
only to processes, not those system level cpu figures.
[ another likely oops classified STOLEN tics as IDLE ]
So, this patch attempts to bring those SUM values into
better agreement with the calculations performed for a
root cgroup (see ./kernel/cgroup/rstat.c source file).
[ we differ from those above in that we also include ]
[ the IDLE plus IOWAIT tics in our TOTAL calculation ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
There's a huge toe-stubber awaiting future maintenance
as reflected in that commit below which deals with the
addition of new enumerators to the Item_table. Namely,
whenever the table is grown, one must remember to also
change that existing 'logical_end' enumerator's value.
Well, not anymore! Since that MAXTABLE macro was added
to the procps-private.h header we can now also exploit
it so a 'logical_end' automatically tracks table size.
This change also renders some code associated with the
ITEMTABLE_DEBUG #define unnecessary. So it's gone too.
Reference(s):
. 08/2016, add new enumerators
commit 09e1886c9e
. 08/2020, added MAXTABLE macro
commit c865b06c30
. 08/2020, introduced ITEMTABLE_DEBUG
commit 92d0297e1e
Signed-off-by: Jim Warner <james.warner@comcast.net>
[ this is what happens when i've run out of bugs and ]
[ issues and am now left with way too much free time ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
All of these changes are self-explanatory, so I'll not
provide any more comments thus avoiding further shame.
[ everything's perfectly justified and right margins ]
[ are filled entirely, but of course it must be luck ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
At 'new' time, the major API modules each ensure their
'info' parameter isn't NULL but what it pointed to was
except this single straggler, for some unknown reason.
So, this patch brings him into line with those others.
[ And, without going into the ugly details, this was ]
[ the reason I never experienced an abend originally ]
[ but Craig did. And, though related to stacks mgmt, ]
[ zero initialization was not a factor. Anyway, with ]
[ this patch, everybody would have experienced abend ]
[ under the original (faulty) test_Itemtables logic! ]
Reference(s):
https://www.freelists.org/post/procps/keep-on-patchin,13
Signed-off-by: Jim Warner <james.warner@comcast.net>
Me thinks Craig had the right idea but perhaps not the
most correct solution. As currently structured, all of
the tests now go way too far by checking every 'unref'
and 'new' call when what we're trying for is survival.
In the final analysis, it doesn't matter who issues an
EXIT_FAILURE - that run_tests guy or an early Exit out
of a procps_new() function. They both will produce the
same end result of the desired "FAIL" test diagnostic.
[ and this patch once again allows the slabinfo test ]
Reference(s):
commit 4eeed6dcff
Signed-off-by: Jim Warner <james.warner@comcast.net>
The referenced commit introduced a test program for the API
but it would often fail due to:
The given pointer for _new() not being NULL
The return value for _new not checked, so the subsequent _unref()
would free() random memory
slabinfo checks failing due to permission denied errors.
The first two are fixed, as well as returning a fail to the test
if they don't return correctly, with slabinfo waiting to see if there
is a way of initialising the structure without reading the slabinfo.
References:
commit e616409aa4
Signed-off-by: Craig Small <csmall@dropbear.xyz>
This change sets the stage for exploiting the recently
added ITEMTABLE_DEBUG #define. All tests are performed
in a single module (after trying 6 separate programs).
The chances of each test detecting errors is extremely
remote (at least while I'm maintaining these modules).
However, this single program approach has one flaw and
it relates to the response whenever an error is found.
Each of those six new API modules calls Exit() if they
detect an error. Otherwise, incorrect results would be
produced at the least or an abend encountered at most.
This means that multiple 'make check' invocations will
be needed if more than 1 module actually was in error.
All in all, it is a small price for a large assurance.
Reference(s):
https://www.freelists.org/post/procps/keep-on-patchin,7
Signed-off-by: Jim Warner <james.warner@comcast.net>
Exploiting a header file shouldn't also force users to
code their own '#include <stdio.h>'. More importantly,
unless this header is mentioned in dist_noinst_HEADERS
we'd fail 'make distcheck' with the error shown below.
[ the same error will apply to all 'noinst_PROGRAMS' ]
[ that happen to use this header. but please, do not ]
[ ask me to explain exactly why or how my fix works! ]
Reference(s):
../../proc/test_pids.c:24:10: fatal error: tests.h: No such file or directory
24 | #include "tests.h"
| ^~~~~~~~~
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is just preparing for adding an Itemtables
verification test by reorganizing stuff and activating
a few previously inactive (overlooked?) test programs.
Signed-off-by: Jim Warner <james.warner@comcast.net>
The recent work on updating the <meminfo> and <vmstat>
modules with some newly added linux fields reminded me
(again) of a need for some mechanism guaranteeing that
a header file agrees with the source file assumptions.
Sadly, in the past, if a table entry was omitted or if
the table and header are ordered differently, then the
library would silently return the wrong results values
or even potentially experience a SIGSEGV abnormal end.
This patch offers a much needed development assist for
ensuring that Item_table entries are synchronized with
header file enumerators in terms of number plus order.
It's intended solely for our use as libprocps evolves.
Now, by activating ITEMTABLE_DEBUG, either directly or
via ./configure CFLAGS='-DITEMTABLE_DEBUG', the number
and order will be verified. It is envisioned that this
feature will be used at least once prior to a release.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This macro should help the following patch be a little
less prolix. Besides, this private header could/should
do just a little more to help with our newlib efforts.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This cosmetic change just prepares for the later patch
introducing validation of Item_tables and enumerators.
[ and, we'll now have better 'set' function names of ]
[ 'set_diskstats_ENUM' instead of the more redundant ]
[ current 'set_diskstats_DISKSTATS_ENUM' convention. ]
[ now our only exception is the <slabinfo> api where ]
[ a full enumerator identifier with 'SLAB' & 'SLABS' ]
[ prefixes are used, and 'SLABINFO_noop/extra' guys. ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
Since last visited, there have been several new fields
added and one field deleted in the /proc/meminfo file.
[ references shown below represent linux git commits ]
Reference(s):
. 4/2020, added 'ShadowCallStack'
commit 628d06a48f57c36abdc2a024930212e654a501b7
. 9/2019, added 'FileHugePages' & 'FilePmdMapped'
commit 60fbf0ab5da1c360e02b7f7d882bf1c0d8f7e32a
. 9/2019, removed 'Quicklists'
commit 13224794cb0832caa403ad583d8605202cabc6bc
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit attempts to smooth some wrinkles impacting
any future libprocps user exploitation. The 2 problems
relate exclusively to our XTRA_PROCPS_DEBUG provision.
1. The 'xtra-procps-debug.h' header had an include for
'procps-private.h', which was not an installed header.
So the STRINGIFY macros will now be embedded directly.
2. Each of the new api headers referenced '<proc/...>'
rather than '<procps/...>' for the debugging #include.
So, we must drop that prefix in favor of a quoted file
name so that debugging builds work regardless of where
that 'xtra-procps-debug.h' header happens to be found.
Reference(s):
. Jun, 2020 - changed target install directory
commit d64755ea5f
. Sep, 2018 - #include migrated from procps.h
commit fab37662ef
Signed-off-by: Jim Warner <james.warner@comcast.net>
I almost feel like I should apologize for this kind of
patch ( *almost* ). But, since this comment was unique
to the <pids> api and since it was especially designed
to align with the following comment and since the next
comment already carried the alignment emphasis, I will
refrain from issuing any apology and submit it anyway.
[ plus to prove that i am not totally anal-retentive ]
[ and can exercise some restraint there are two more ]
[ places where i COULD have added alignment emphasis ]
[ see lines 804-806 and lines 1360-1361 for my proof ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch just repositions some .PP macros so they'll
immediately precede the paragraphs to which they apply
rather than a comment line used as a visual separator.
[ ok we also update the document date to 'July 2020' ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch just trades the 'typestr' for the much more
meaningful 'valid range' when a relative enum has been
deemed invalid under that XTRA_PROCPS_DEBUG provision.
[ and we'll also make one comment a bit more generic ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit addresses the errors/warnings shown below.
Reference(s):
ERROR: skipping end of block that is not open: RE
WARNING: skipping paragraph macro: sp after PP
WARNING: skipping paragraph macro: PP empty
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit only eliminates two 'nop' instructions and
one 'jmp' instruction. However, it makes that C source
code look a little bit prettier than it looked before.
[ and yes, some unnecessary parenthesis were used to ]
[ force an alignment of some related lines. it costs ]
[ us nothing in extra code yet helps in readability. ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch eliminates one variable which resulted in a
corresponding elimination of three 'mov' instructions.
[ that was 6 bytes per 'mov' for a total of 18 bytes ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
These headers were used only in the library itself and
it's wrong to have them in the user include directory.
* devname.h .. is used only by: ... pids.c, readproc.c
* numa.h ..... is used only by: ....... pids.c, stat.c
* pwcache.h .. is used only by: ........... readproc.c
* readproc.h . is used only by: ..... escape.c, pids.c
* wchan.h .... is used only by: ............... pids.c
Signed-off-by: Jim Warner <james.warner@comcast.net>
In that commit referenced below, a promise was made to
revisit an 'escape_str' function in efforts to make it
private to the library. The problem was it's needed by
both ps plus the library which is why it was exported.
So, in an effort to remove it from libprocps.sym, this
patch duplicates all the required code in ps/output.c.
Now, each version can be made private to their caller.
[ along the way we'll use this opportunity to remove ]
[ the 'restrict' qualifiers from function parameters ]
[ while swatting a compiler warning referenced below ]
Reference(s):
. April 2016, most escape functions made private
commit d916d5db86
proc/escape.c: In function `escape_command':
proc/escape.c:182:23: warning: initialization of `const char **' from incompatible pointer type `char **' [-Wincompatible-pointer-types]
182 | const char **lc = (char**)pp->cmdline;
| ^
Signed-off-by: Jim Warner <james.warner@comcast.net>
There was a time when that procps.h file served a more
traditional role. Prior to the commit referenced below
it held just macros plus manifest constants. But, with
that change, such items were replaced with a series of
includes embracing all the library exported functions.
That approach was known to disguise errors which would
have otherwise yielded a compiler warning. And without
such a warning, there was no way to address the error.
So this patch will trade the all inclusive header file
approach for individual includes only where necessary.
Reference(s):
. April 2016, procps.h header file revamped
commit ccb6ae8de1
. Sept 2018, top abandoned use of procps.h
commit a6dfc2382e
Signed-off-by: Jim Warner <james.warner@comcast.net>
The meminfo & vmstat file read buffers are now defined
through symbolic constants next to the symbolic names.
[ recent attention to the /proc/stat buffer size led ]
[ to this (hopefully) better approach to definitions ]
Reference(s):
commit 81f4a6acdf
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit just address the two warnings shown below.
Reference(s):
pgrep.c: In function `select_procs':
pgrep.c:535:12: warning: variable `now' set but not used [-Wunused-but-set-variable]
535 | time_t now;
| ^~~
pidof.c: In function `select_procs':
pidof.c:201:9: warning: `stat_cmd' may be used uninitialized in this function [-Wmaybe-uninitialized]
201 | !strcmp(program, stat_cmd) ||
| ^~~~~~~~~~~~~~~~~~~~~~~~~
Signed-off-by: Jim Warner <james.warner@comcast.net>
vmstat - align wording with proc manpage to clarify ambiguities (rhbz#1796043)
watch - manpage presumes ntp tools are present by default (which they're not on rpm and deb distros, rhbz#1583669)
We won't go as far as the merge request shown below in
increasing buffer size, but we will reduce by half the
total iterations while growing it to achieve one read.
[ and this seems in line with what was recently done ]
[ to help top under a massively parallel environment ]
[ thru 2 abreast ('4') and combined cpus ('!') modes ]
Reference(s:
https://gitlab.com/procps-ng/procps/-/merge_requests/105
Signed-off-by: Jim Warner <james.warner@comcast.net>
A patch to address the following man doc deficiencies:
. shorten NAME so there's no wrap in an 80x24 terminal
. typo wherein the 'item' parm should have been 'info'
. expand RETURN text for a potential NULL upon success
[ maybe, this might be my last tweak to this man doc ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
[ actually, this patch goes a little beyond what was ]
[ strictly required. some messages were expanded for ]
[ clarity and should an inactive node be selected by ]
[ the '3' command, a second '2' no longer is needed. ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
Now that we may be getting serious with documentation,
that stat module was revisited with an eye toward user
friendliness. Heck, even this author puzzled over some
of the existing notes and naming conventions employed.
So, this patch will adjust some identifiers and expand
the notes to (hopefully) better serve potential users.
The most significant change was making the STAT_TIC_ID
always valid for numa nodes, even if any are inactive.
Thus the -22222 special STAT_NODE_INVALID constant now
is applied only to STAT_TIC_NUMA_NODE. It will be used
on the cpu summary and reaps with STAT_REAP_CPUS_ONLY.
And it will also mark any numa node that was inactive.
Signed-off-by: Jim Warner <james.warner@comcast.net>
An important fact was omitted in the DEBUGGING section
for the two newest man documents. Users must utilize a
macro in the header files before verification happens.
So, this commit will sneak in such mention and in that
way reduce future liability if the feature won't work.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit cleans up some man document files. It also
changes the target install directory from the original
'proc/' to 'procps/' (feels like a more natural name).
[ and, now it agrees with those 2 preceding man docs ]
[ since it is obvious the tail was wagging this dog! ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
The original approach contained a fatal flaw. In order
to use those man pages, users would have been required
to already know how to use the library. Or alternately
one could randomly search each of them while trying to
ascertain which function call satisfies their need and
what exactly was the proper compliment/order required.
So, this revised approach tries to simplify things and
document only what is not apparent in the header file.
Along the way, the following assumptions were germane.
1) It is the kernel folks' job to document /proc files
not to mention fields within those files. And since we
don't yet know what some of those fields represent, we
shouldn't attempt to document any of those we do know.
2) Our header file serves as an essential reference in
successful exploitation of this new library interface.
3) The description represents functions as they appear
in the header itself making them immediately familiar.
4) Armed with our header file users can easily see the
self-documenting enumerators & structures. There isn't
a need to explain them yet again in this man document.
5) Contrary to man guidelines, we shouldn't list error
codes. Simple generic guidance serves everyone better.
The following references represent a history for those
man documents this new version is intended to replace.
Reference(s):
. 04/18/16, create libproc.3 + procps_pids_new.3
commit 4217eddf47
. 04/19/16, create procps_pids_read_open.3
commit d48c54f679
. 01/05/17, create many procps_pids_... docs
commit 2598e9f2ce
Signed-off-by: Jim Warner <james.warner@comcast.net>
This represents the 'second cut' at providing a shared
man page that supports more than one newlib interface.
In this approach, the following assumptions were made:
1) It is the kernel folks' job to document /proc files
not to mention fields within those files. And since we
don't yet know what some of those fields represent, we
shouldn't attempt to document any of those we do know.
2) Our header files serve as an essential reference in
successful exploitation of the new library interfaces.
3) The description represents functions as they appear
in the header itself making them immediately familiar.
4) Some inconsistencies among the interfaces have been
handled more visually rather than in a narrative form.
5) Armed with our header file users can easily see the
self-documenting enumerators & structures. There isn't
a need to explain them yet again in this man document.
6) Contrary to man guidelines, we shouldn't list error
codes. Simple generic guidance serves everyone better.
Reference(s):
. 05/19/20, procps.3 man page introduced
commit fc69028d37
Signed-off-by: Jim Warner <james.warner@comcast.net>
In preparation for a documentation attempt, this patch
renames 'struct reap' to 'struct reaped' in two of our
interfaces. That will bring all the non-pid interfaces
into agreement since the <stat> api already used that.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is prompted by the preceding change to the
library's escape.c module which, in turn, was prompted
by that issue shown below (with thanks to Konstantin).
Reference(s):
https://gitlab.com/procps-ng/procps/-/issues/176
Signed-off-by: Jim Warner <james.warner@comcast.net>
Thanks to Konstantin for discovering 2 problems in the
issue referenced below. That 15+ year old logic went a
little too far overboard wrestling with a utf8 string.
Henceforth, we will not treat 'x9b' as special. And we
also will handle a 'combining acute accent' correctly.
Reference(s):
https://gitlab.com/procps-ng/procps/-/issues/176
Signed-off-by: Jim Warner <james.warner@comcast.net>
I've grown to hate that man document rendering when it
comes to hyphenation. So this patch will eliminate it.
And we'll also eliminate an unnecessary initialization
in that top program code concerned with combined cpus.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This ensures that a single '4' keystroke will reliably
toggle the new 2 abreast mode ON. Depending on whether
an older configuration file existed or whether top was
configured with '--disable-modern-top', keying the '4'
for a second time might otherwise have been necessary.
Signed-off-by: Jim Warner <james.warner@comcast.net>
An old PRETEND8CPUS #define was reintroduced & changed
to PRETEND48CPU to better exercise the new '4' and '!'
toggles. But, the implementation simply duplicated the
/proc/stat summary line for each cpu. Therefore, every
cpu showed the same graph/detail (depending upon 't').
This patch shows the actual individual cpu information
(duplicated, of course, when total cpus are exceeded).
Signed-off-by: Jim Warner <james.warner@comcast.net>
