Commit Graph

28 Commits

Author SHA1 Message Date
Jim Warner
76a8d7b5cb docs: tweak two man pages due to renaming of libproc-2
Reference(s):
commit 9aa09d8862

Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-23 22:07:48 +11:00
Craig Small
9aa09d8862 library: Rename to libproc-2
What to call the new library?

Keep using libprocps wouldn't do, its a very different library from
the programs' point of view. It would also mean we could have some
clashes around the packages (two package names, same library name).

The ancient procps used libproc or libproc-a.b.c where a.b.c was the
package version. Kept the revision numbers down (it was always 0.0.0)
but the name of the library changed.

So if we use libproc-2 is there a clash with an ancient procps?
procps v 2.0.0 was around in 1999 so it was 22 years ago, also the
name of the library would have been libproc-2.0.0.so not libproc-2.so
so we're fine with that.

libproc-2 seems to fit, our second major re-work of the procps
library.

Signed-off-by: Craig Small <csmall@dropbear.xyz>
2021-02-20 22:30:31 +11:00
Jim Warner
aaa0cd48b0 docs: adjust revision date for our three new man pages
Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-18 18:35:32 +11:00
Jim Warner
9c98179558 docs: expand 2 man pages 'Usage' to include VAL macros
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>
2021-02-18 18:35:32 +11:00
Jim Warner
9a0869e8ba docs: bring 2 man pages into agreement regarding sorts
Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-02-09 16:40:52 +11:00
Jim Warner
baa9dc93f9 docs: adapt procps_misc.3 for new 'misc.h' header file
This commit adapts our man page for a new consolidated
'misc.h' header file. Along the way, some descriptions
were shortened, others lengthened and whitespace added
in an effort to (hopefully) improve readability a bit.

[ the #include subdirectory was also corrected while ]
[ rearranging & grouping functions into 3 categories ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-01-21 17:30:25 +11:00
Jim Warner
38c38a317b docs: update copyright, revision plus name for 2 pages
Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-01-21 17:30:24 +11:00
Craig Small
a978f68c06 docs: Merge procps_uptime_* into procps_misc.3 2020-12-21 12:48:06 +11:00
Craig Small
8a9a1aef74 doc: fix typo in procps_misc 2020-12-21 12:43:00 +11:00
Craig Small
770505ded4 docs: Merge procps_ns_* into misc 2020-12-21 12:41:10 +11:00
Craig Small
7246249b8c docs: Merge procps_linux_version into misc 2020-12-21 12:32:57 +11:00
Craig Small
02e35c1fb1 docs: Add procps_misc.3 manpage
The last (I think) of the newlib man pages for the new API.
2020-10-24 18:25:48 +11:00
Jim Warner
3df74e7f3c docs: just a few changes to that new pids man document
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>
2020-06-29 21:13:40 +10:00
Jim Warner
9b3436e0e4 docs: tweak both of those newly created man docs a tad
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>
2020-06-25 20:08:22 +10:00
Jim Warner
fc4fb85e7b docs: replace 'procps_pids' stuff with revised version
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>
2020-06-23 19:09:05 +10:00
Jim Warner
eadb9db58f docs: update 'first cut' procps.3 with revised version
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>
2020-06-23 19:09:05 +10:00
Craig Small
fc69028d37 doc: First cut at new combined API doc
Instead of repeating the same thing for each info type, use one
huge man page. Needs more work but lets see how it looks for now.
2020-05-19 22:43:21 +10:00
Craig Small
0aa0f92727 docs: Add namespace man pages 2020-05-18 21:42:49 +10:00
Craig Small
2b6ad61f3c docs: Update the uptime man pages
Three functions in the same manpage but use the so commands
to refer to the main man page.
2020-05-18 21:10:03 +10:00
Craig Small
2598e9f2ce documentation: Update pids manual pages
Updated the full suite of manual pages for the procps_pids_*
functions. The only one missing is procps_pids_get which
may not be required.
2017-01-05 09:44:04 +11:00
Jim Warner
f8da0bb89a misc: eliminated every instance of trailing whitespace
[ alas, there were only two instances (1 file) found ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2016-07-09 12:48:28 +10:00
Craig Small
9abf7d879d library: protect against large version numbers.
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)
2016-05-01 17:14:48 +10:00
Craig Small
6b5cb345c5 library: procps_uptime() return value is a status
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.
2016-05-01 16:50:25 +10:00
Craig Small
d48c54f679 docs: Additional flags in man pages
More PIDS defintions
2016-04-19 23:28:53 +10:00
Craig Small
4217eddf47 docs: Start documenting the pids API
Started with procps_pids_new() and documenting this function
as well as the enum used in this function.
2016-04-18 22:57:01 +10:00
Craig Small
8e20fa7786 library: document and tests for uptime functions
man pages for the three procps_uptime* functions and simple
test scripts for same functions.
2016-04-16 22:02:10 +10:00
Craig Small
d15a8901d2 docs: Cleanup procps_linux_version page
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.
2016-04-16 08:34:08 +10:00
Craig Small
8639a97250 libprocps version test and documentation
test binary and man page for the version part of libprocps.
It's a simple start, but it's a start!
2016-04-14 22:28:38 +10:00