Commit Graph

17 Commits

Author SHA1 Message Date
Jim Warner
116ce62304 doc: revert mention of limits for fatal_proc_unmounted
With the next commit the fatal_proc_unmounted function
will be refactored to behave as it always should have.
So, a need for the user 'stat' caution will disappear.

Reference(s):
. original man page change
commit 7d44c94317

Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-08-01 22:12:47 +10:00
Craig Small
7d44c94317 doc: Mention fatal_proc_unmounted limitations
Discovered this while trying to port programs that use the deleted
libprocps function look_up_our_self() which can be found with the
fatal_proc_unmounted() function.

While procps_pids_new() will allow you to specify any items you
care to think of, a subsequent call to fatal_proc_unmounted()
will only fill in the values found in /proc/self/stat.

Added a caveat to the procps_pids manpage pointing out this
limitation.

References:
 https://salsa.debian.org/xorg-team/app/apitrace/-/blob/debian-unstable/lib/os/os_memory.hpp#L44
 https://gitlab.com/-/snippets/2377884

Signed-off-by: Craig Small <csmall@dropbear.xyz>
2022-07-27 21:12:10 +10:00
Jim Warner
0df22d89db doc: make the library API pages a little more readable
Use of the the '.B' and '.BI' man documentation macros
had rendered the three library API pages less readable
than they could be. In addition, sometimes the pointer
indicator and an identifier were separated by a space.

So, this commit will trade those macros for some '.RI'
and '.RB' macros plus treat the pointers consistently.

[ plus we no longer italicize sort 'stacks' brackets ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-07-27 20:24:54 +10:00
Jim Warner
854e85a50b doc: minor tweaks affecting three newlib man documents
. add the proper function names to the procps_pids man
page when discussing the 'LIBPROC_HIDE_KERNEL' feature
under recently added 'ENVIRONMENT VARIABLE(S)' section

. ensure the 'SEE ALSO' references are comma delimited

Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-02-27 21:27:02 +11:00
Jim Warner
91ffe81734 misc: fixed several inconsistencies in email addresses
[ you wouldn't believe how many back-and-forths were ]
[ involved in Craig convincing me there were several ]
[ inconsistencies. i am so dense sometimes (often?). ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-01-08 07:15:59 +11:00
Jim Warner
e243721f22 doc: updated 3 man pages for 'LIBPROC_HIDE_KERNEL' var
This patch was prompted by Björn Fischer's merge #147
request referenced below. And since the library change
may impact all users, multiple man pages were updated.

[ and thanks to Björn for initiating this extension ]

Reference(s):
https://gitlab.com/procps-ng/procps/-/merge_requests/147

Prototyped-by: Björn Fischer <bf@CeBiTec.Uni-Bielefeld.DE>
Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-01-07 19:19:15 +11:00
Jim Warner
afdd4690fc misc: amend the man page & source file copyright dates
This just updates the copyright dates in the documents
where I was already represented. Others are unchanged.

Signed-off-by: Jim Warner <james.warner@comcast.net>
2022-01-07 19:19:15 +11:00
Jim Warner
b652c35f7f doc: added the new valgrind 'warning-suppression' file
Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-10-18 17:38:43 +11:00
Jim Warner
17c30484bc docs: fix a couple of spelling errors in new man pages
Signed-off-by: Jim Warner <james.warner@comcast.net>
2021-04-06 16:51:03 +10:00
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
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
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
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