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>
Linux release numbers are x.y.z we assumed but never protected
against x> 0x7fff and y,z > 0xff before.
Linux release in 1991, 1 major release per 6 years so we're fine
until 7452, unless they do way too many minor rels (max being 39)
procps_uptime, previously just plain uptime() used to put the
uptime (as a double) in the first argument and return uptime
(as an int).
It meant if you ran
myuptime2 = procps_uptime(&myuptime1, NULL);
You might get different results for myuptime1 and myuptime2 because
they are different types.
Most library calls use the return value to return the status,
procps_uptime was in the middle.
Until now.
This function will return 0 on success. If you want (for whatever
reason) uptime as an int then cast it.
All of the procps binaries didn't use the return value for uptime
except ps which set a variable to it but never used it anywhere.
Getting the manual page for procps_linux_version(3) fixed up so
it follows the man-pages(7) and other standards.
Added lgpl license to file, so its the same as the code.
