A lack of documentation seems to be the major obstacle
to releasing this new library. So, in an effort to get
the ball rolling again, this patch adds the origins of
each item as a comment to six of the new header files.
However, before reviewing how such changes may benefit
that documentation objective, it seemed appropriate to
first reflect on newlib's background & current status.
___________________________________________ BACKGROUND
Discussions about and work on a new library began back
in July 2012 but quickly died. After a lull of 2 years
those discussions were resumed in August 2014 but soon
died also (and no code survived the gitorious demise).
With those early discussions, the recommended approach
was to encapsulate all of the libprocps data offerings
in individual functions. When it came to extensibility
it was suggested we should rely on symbols versioning.
Unfortunately that approach would have made for a huge
Application Programming Interface virtually impossible
to master or even document. And, runtime call overhead
would have been substantial for ps and especially top.
So, an alternative design was sought but there were no
new suggestions/contributions via freelists or gitlab.
Thus, in spite of a lack of library design experience,
the procps-ng team (Craig & Jim) set out to develop an
alternative API, more concise and with lower overhead.
Reference(s):
. 07/01/2012, begin library design discussion
https://www.freelists.org/post/procps/Old-library-calls
. 08/12/2014, revival of library design discussion
https://www.freelists.org/post/procps/libprocs-redesign
_____________________________________ DESIGN EVOLUTION
Our newlib branch first appeared on June 14, 2015. And
our current API actually represents the 4th generation
during the past 3 years of evolution. First, there was
a basic 'new', 'get' and 'unref' approach, using enums
to minimize the proliferation of 'get' function calls.
Then, in anticipation of other programs like ps, where
multiple fields times multiple processes would greatly
increase the number of 'get' function calls, a concept
of 'chains' was introduced. This became generation #2.
Such 'chains' proved unnecessarily complex so 'stacks'
replaced them. This was considered the 3rd generation,
but too many implementation details were still exposed
requiring those users to 'alloc', 'read', 'fill', etc.
Finally, a 4th generation emerged representing several
refinements to standardize and minimize those exported
functions, thus hiding all implementation details from
the users. Lastly, handling of 'errno' was normalized.
Reference(s):
. 06/14/2015, revival of new API discussion
https://www.freelists.org/post/procps/The-library-API-again
. 06/24/2015, birth of the newlib branch
https://www.freelists.org/post/procps/new-library
. 06/29/2015, 2nd generation introduced 'chains'
https://www.freelists.org/post/procps/new-library,8
. 07/22/2015, 3rd generation introduced 'stacks'
https://www.freelists.org/post/procps/newlib-stacks-vs-chains
. 06/18/2016, 4th generation refinements begin
https://www.freelists.org/post/procps/newlib-generation-35
. 11/10/2017, 4th generation standardized 'errno'
https://www.freelists.org/post/procps/some-more-master-newlib-stuff
_______________________________________ CURRENT DESIGN
Central to this new design is a simple 'result' struct
reflecting an item plus its value (thanks to a union).
As a user option, these item structures can be grouped
into 'stacks', yielding many results with just 1 call.
Such a 'stack' can be seen as a variable length record
whose content/order is determined solely by the users.
Within that 'result' structure, the union has standard
C language types so there is never a doubt how a value
should be used in a printf statement. Given that linux
requires a least a 32-bit platform the only difference
in capacity surrounds 'long' integers. And, where such
types might be used, the 32-bit maximums are adequate.
The items themselves are simply enumerators defined in
the respective header files. A user can name any items
of interest then the library magically provides result
structure(s). The approach was proven to be extensible
without breaking the ABI (in commit referenced below).
The 6 major APIs each provide for the following calls:
. 'new' ---------> always required as the first call .
. 'ref' -------------------------> strictly optional .
. 'unref' --------> optional, if ill-behaved program .
. 'get' --------------------> retrieve a single item .
. 'select' ----------------> retrieve multiple items .
And the 'get' and 'select' functions provide for delta
results representing the difference between successive
get/select calls (or a 'new' then 'get/select' call).
For the <diskstats>, <pids>, <slabinfo> & <stat> APIs,
where results are unpredictable, a 'reap' function can
return multiple result structures for multiple stacks.
The <pids> API differs from others in that those items
of interest must be provided at 'new' or 'reset' time,
a function unique to this API. And the <pids> 'select'
function requires PIDs or UIDs which are to be fetched
which then operates as a subset of 'reap'. Lastly, the
'get' function is an iterator for successive PIDs/TIDs
returning items previously identified via 'new/reset'.
To provide assistance to users during development, the
special header 'proc/xtra-procps-debug.h' is available
to check type usage against library expectations. That
check is activated by including this header explicitly
or via build using: ./configure '-DXTRA_PROCPS_DEBUG'.
Reference(s):
. 08/05/2016, type validation introduced
https://www.freelists.org/post/procps/newlib-types-validation
commit e3270d463d
. 08/11/2016, extensibility while preserving ABI example
https://www.freelists.org/post/procps/new-meminfo-fields
commit 09e1886c9e
_________________________ INITIAL DOCUMENTATION EFFORT
The initial attempt, referenced below, dealt primarily
with the <pids> interface. Separate man pages for each
exported function were created. Plus there was another
document describing the items, among other miscellany.
Adopting such an approach encounters several problems:
1. In order to use these man pages, users are 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.
2. While we can explain what all of those <pids> items
represent, that certainly isn't true for all the APIs.
See the gaps in kernel documentation for <meminfo> and
complete lack of documentation with that <vmstat> API.
3. Our documentation effort should take pains to avoid
unnecessary implementation details. Here's an example:
. "The pointer to info will have memory"
. "allocated and a structure created."
Alternatively, the following conveys user requirements
while not offering any internal implementation detail:
. "You must provide the address of a NULL"
. "info structure pointer."
Reference(s):
. 01/04/2017, initial documentation offering
https://www.freelists.org/post/procps/Using-reap-and-get
commit 2598e9f2ce
___________________ RECOMMENDED DOCUMENTATION APPROACH
I recommend that the newlib documentation consist of 3
man pages only. The first would cover the 5 major APIs
and their common functions. The second would deal with
the <pids> API exclusively, explaining how it differs.
Any remaining exported libproc functions which are yet
to be included could be represented in a 3rd document.
For these new documents the following are are assumed:
1. Since we will not be able to document all items, we
shouldn't try to document any items. We should instead
rely on proc(5) or Documentation/filesystems/proc.txt.
2. Program development often involves referencing some
header file(s). So, make that an absolute requirement.
3. With the addition of item origins, represented with
this commit, and considering that 'types' were already
present, the header file might be all some users need.
4. And who knows, when a user of our libproc complains
about gaps in their documentation, it might prompt the
kernel folks to correct those long standing omissions.
To summarize, I suggest that we replace that libproc.3
document with a more general one explaining the basics
of accessing this new library and the common calls for
most of the major interfaces. We can then create a new
document (libproc-pids.3?), which explains differences
in using the <PIDS> application programming interface.
A final document (libproc-misc.3?) covers what's left.
Signed-off-by: Jim Warner <james.warner@comcast.net>
If we ever were to eliminate the procps.h header file,
as discussed in the thread referenced below, then that
would impair the current XTRA_PROCPS_DEBUG provisions.
The only remaining way to verify result types would be
to explicitly include that <proc/xtra-procps-debug.h>.
So, this commit will once again enable the ./configure
provision for defining the -DXTRA_PROCPS_DEBUG option.
Reference(s):
https://www.freelists.org/post/procps/newlib-Qualys-patches,6
Signed-off-by: Jim Warner <james.warner@comcast.net>
When 'newlib' was introduced, in the commit referenced
below, the use of that glibc '__BEGIN_DECLS' macro was
standardized. However, as issue #88 revealed, this may
result in a fatal build error with other environments.
So, this patch just trades that macro for the standard
'#ifdef __cplusplus' conventions (thus avoiding use of
all those '#include <features.h>' directives as well).
Reference(s):
. newlib introduced
commit a410e236ab
. procps-ng-3.3.13 issue
https://gitlab.com/procps-ng/procps/issues/88
. some additional discussion
https://www.freelists.org/post/procps/PATCH-Replace-glibcspecific-macros-in-procnumah,1
. musl wiki (see: sys/cdefs.h error messages)
https://wiki.musl-libc.org/faq.html
Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit just contains some tweaks to comments plus
a few adjustments to whitespace for alignment purposes
and a normalization of the header inclusion #define's.
[ plus a spelling error in one header file was fixed ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
When users call the native 'get' functions they have a
responsibility to check that the result struct address
was indeed returned. But when using those 'GET' macros
there was no protection for possible NULL dereference.
So this patch will add some protection for a potential
failure of an underlying 'get' function. And should it
occur then those 'GET' macros will just return a zero.
Plus, we'll also mirror that behavior in the debugging
header should the XTRA_PROCPS_DEBUG #define be active.
And, we might as well add a warning when invalid items
are passed to 'GET' macros, just like we do for 'VAL'.
[ lastly, we added the missing opening parens/braces ]
[ to 2 'GET' macros in that xtra-procps-debug.h file ]
[ which went unnoticed until the qa folks caught up. ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch will set the stage for validating the types
referenced in the result union. For now, the parameter
representing that 'info' structure will remain unused.
[ and while we're at it, let us correct a faulty GET ]
[ macro in the diskstats header. that puppy missed a ]
[ parm which ain't so good if that guy is ever used! ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
Many of our item enumerator identifiers are very long,
especially in that <VMSTAT> module. Additionally, they
all contain the exact same universal 'PROCPS_' prefix.
The origins for this are likely found in the desire to
avoid name clashes with other potential include files.
But with procps-ng newlib, we've probably gone way too
far. Did 'PROCPS_PIDS_TICS_SYSTEM' actually offer more
protection against clash than 'PIDS_TICS_SYSTEM' does?
I don't think so. Besides, no matter how big that name
becomes, one can never guarantee they'll never be some
clash. And, conversely, extremely short names will not
always create conflict. Of course, in either case when
some clash occurs, one can always #undef that problem.
Thus, this commit will eliminate that 'PROCPS_' prefix
making all of those enum identifiers a little shorter.
And, we'll still be well above some ridiculously short
(criminally short) names found in some common headers:
- - - - - - - - - - <term.h>
- 'tab', 'TTY', etc
- - - - - - - - - - - - - - - - <search.h>
- 'ENTER', ENTRY', 'FIND', etc
------------------------------------------------------
Finally, with this as a last of the wholesale changes,
we will have established the naming conventions below:
. only functions will begin with that 'procps_' prefix
. exposed structures begin with the module/header name
. item enumerators begin like structs, but capitalized
. other enumerators work exactly like item enumerators
. macros and constants begin just like the enumerators
------------------------------------------------------
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch attempts to standardize the naming of those
most important (declared not defined) context structs.
The present practice represents a hodge podge of names
only some of which reflect the source /proc file name.
And 2 of those file names embed a literal 'info' which
is likely the origin of that required parm identifier.
Now we'll append a universal '_info' to such structure
names, while including the names of those /proc pseudo
files where possible. In any case, that context struct
will *always* begin with the actual module/header file
name. And only the following two sound a little weird!
---------> 'meminfo_info' + 'slabinfo_info' <---------
Signed-off-by: Jim Warner <james.warner@comcast.net>
The following commit message is shared with 4 patches.
------------------------------------------------------
Under the newlib interface most of our 'get' functions
represent a bit of a compromise in that the actual raw
values are coerced into one (probably ok) return type.
That approach creates the possibility of truncation at
best, and wouldn't serve future needs should something
other than numeric data be added to the 'get' results.
This commit trades the current compromise for a return
value guaranteed to satisfy all future needs, namely a
pointer to a particular api's specific results struct.
The impact on existing programs is minimal, especially
when using a new supplied macro. Otherwise, native 'C'
syntax could be used, but may feel somewhat unnatural.
[ as an aside, this new approach allows us to delete ]
[ all 'getsfunc' table entries & the supporting code ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
Following is a summary of significant changes (if any)
to each of these now upgraded 3rd gen library modules.
<meminfo> ............................................
. eliminated duplicate decl of 'struct procps_meminfo'
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. how did i miss relocating all these friggin' #undefs
. cleanup 'get' return logic (remove a redundant 'if')
<pids> ...............................................
. repositioned the procps_pidsinfo structure in header
. removed the extra trailing comma from enum pids_item
. standardized/normalized results struct union members
<slabinfo> ...........................................
. corrected comment typo (jeeze, in an 'aligned' para)
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. removed an obsolete #undef from procps_slabinfo_sort
. cleanup 'get' return logic (remove a redundant 'if')
<stat> ...............................................
. how did i miss relocating all these friggin' #undefs
. corrected an initialization fencepost used with numa <=== see Craig, here's a bug fix
. removed the extra trailing comma from enum stat_item
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. strengthen those parm checks in procps_stat_get func
. cleanup 'get' return logic (remove a redundant 'if')
<vmstat> .............................................
. standardized/normalized results struct union members
. added 'std' & 'var' dividers in .c file, like <pids>
. cleanup 'get' return logic (remove a redundant 'if')
[ virtually all of these tweaks reflect the author's ]
[ continuing pursuit of an unreasonable goal -- that ]
[ of a 'perfect' (plus 'pretty') C language program! ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
With the dust now settling on all those 3rd generation
upgrades, this patch tries to provide some consistency
among the separate modules involved. Someday we should
consider a 4th generation where all redundant code has
been removed and isolated in a new shared source file.
Following is a summary of significant changes (if any)
to each of these now upgraded 3rd gen library modules.
<meminfo> ............................................
. strictly formatting/comment changes, code unaffected
<pids> ...............................................
. replaced a local mkSTR macro with existing STRINGIFY
. added fetch narrative explaining duplicate addresses
<slabinfo> ...........................................
. rearranged some free logic for procps_slabinfo_unref
. added fetch narrative explaining duplicate addresses
<stat> ...............................................
. added #define ENFORCE_LOGICAL, just as in <slabinfo>
. replaced a local mkSTR macro with existing STRINGIFY
. alphabetized the function declarations in the header
<vmstat> .............................................
. made one coverity concession with read_vmstat_failed
[ several of these changes may reflect this author's ]
[ continuing pursuit of an unreasonable goal -- that ]
[ of a 'perfect' (plus 'pretty') C language program! ]
Signed-off-by: Jim Warner <james.warner@comcast.net>
This interface represented a 2nd generation attempt at
the opaque newlib approach. In other words, it did not
involve the 1st generation 'chains'. Instead, 'stacks'
were employed. But the interface wasn't user friendly.
Users were required to create their own stacks, before
calling 'getstack' to retrieve multiple results with a
single call. Even worse, sometimes 'read' was required
before calling 'get' when working with single results.
So this commit represents the 3rd generation approach.
We eliminate the burden of 'read' and creating stacks.
Rather, beyond those standard 'new', 'ref' and 'unref'
functions, we'll offer just 'get' (single result) plus
a 'select' function (for multiple results in 1 stack).
And along the way, this commit vastly expands the data
extracted from /proc/vmstat. All values that currently
exist (and their delta equivalents) are now available.
Deltas were included for everything because there's no
real runtime costs beyond using a little extra memory.
The only problem is a lack of documentation for all of
those fields, as is reflected in the references below.
Oh well, maybe someday someone will dig through kernel
sources & finally plug that rather large document gap.
[ as an aside, rather than using a 'strcmp' approach ]
[ when parsing the /proc/vmstat file, as is found in ]
[ the <meminfo> module, we exploit those hash search ]
[ provisions that are found in the <search.h> header ]
Reference(s):
http://www.spinics.net/lists/linux-man/msg09096.htmlhttp://www.linuxinsight.com/proc_vmstat.html
Signed-off-by: Jim Warner <james.warner@comcast.net>
The includes used to define a lot of things a library include
should not. It was also a bit messy what was exposed in the library
and what was not.
get_pid_digits -> procps_pid_length and exported correctly
MALLOC attribute move into relevant .c files
NORETURN attribute moved to relevant .c, not used in library
PURE attribute removed, it wasn't used
KLONG/KLF/STRTOUKL were fixed for long, so now just use long
HIDDEN attribute removed. It was for 3 functions. The PROCPS_EXPORT
seems to do the same (opposite) thing.
likely/unlikely removed from most places, its highly debateable
this does anything useful as CPUs have gotten smarter about branches.
Re-arranged the includes, ALL external programs should just #include
<proc/procps.h> then proc/procps.h includes headers for files that
have exported functions. procps.h and the headers it includes should
not use items that are not exportable (e.g. hidden functions or
macros) they go in procps-private.h
In addition to that text shown below the line which is
common to several commit messages, this patch contains
several minor changes with lessor impact upon the API:
. Standard copyright boilerplate was added in .c file.
. The #include header files are ordered alphabetically
now, with all those <sys/??> types separately grouped.
. The header file follows the conventions of indenting
(by 4 spaces) those parameters too lengthy for 1 line.
------------------------------------------------------
. The former 'chains' have now become 'stacks' without
the 'next' pointer in each result struct. The pointers
initially seemed to offer some flexibility with memory
allocations and benefits for the library access logic.
However, user access was always via displacement and a
a statically allocated chain was cumbersome to define.
. An enumerator ending in '_noop' will no longer serve
as a fencepost delimiter. Rather, it has become a much
more important and flexible user oriented tool. Adding
one or more such 'items' in any items list passed into
the library becomes the means of extending the 'stack'
to also include user (not just library) data. Any such
data is guaranteed to never be altered by the library.
. Anticipating PID support, where many different types
must be represented in a result structure, we'll adopt
a common naming standard. And, while not every results
structure currently needs to reflect disparate types a
union will be employed so the same dot qualifier ('.')
can be used consistently when accessing all such data.
Signed-off-by: Jim Warner <james.warner@comcast.net>
The earlier attempt at protecting these functions from
already freed memory worked just fine until the memory
was, in fact, reused by the OS. At that point, the ref
count would most likely fail an existing a test for 0.
So this commit will take control of the 'info' pointer
and force it to NULL when a reference count reaches 0.
Plus, since it makes little sense returning an address
that a caller already has, henceforth we will return a
reference count out of the 'ref' and 'unref functions.
Reference(s):
commit 74beff80ff
Signed-off-by: Jim Warner <james.warner@comcast.net>
If a caller chooses to reduce the overhead of repeated
function calls, this commit provides for acquiring all
the desired information in just a single library call.
Signed-off-by: Jim Warner <james.warner@comcast.net>
This patch mostly just eliminates darn tab characters.
Plus the library function declarations and definitions
have been standardized. Most visibly, the input params
now have all been indented on their own separate line.
Signed-off-by: Jim Warner <james.warner@comcast.net>
Created new set of functions for meminfo related calls. Liked the
format of that better so changed vmstat around so the look similar.
Missed the makefile change for uptime so added it in now.
Use the standard libc declarations.
For protecting the headers for C++ procps used to have its
own defines, this change makes them use the standard libc ones.
getstat() -> procps_stat_*
vminfo() -> procps_vmstat_*
These two components of the library now use the newer version of
the API with less exposed global variables. The old methods are
there for now.
Signed-off-by: Craig Small <csmall@enc.com.au>
