Maybe, the biggest obstacle to successfully exploiting
this new library is after those `stacks' are returned.
Unless a user requests all available `items', there is
always a need to translate an actual enumerator into a
relative position within returned stack(s) of results.
So, this patch attempts to bridge that gap by adding a
brief explanation to the existing discussion in Usage.
[ along the way, 'Usage' & 'Caveats' were refactored ]
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>
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>
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>
