From: Craig Small <csmall@dropbear.xyz>
Date: Wed, 27 Jul 2022 11:12:10 +0000 (+1000)
Subject: doc: Mention fatal_proc_unmounted limitations
X-Git-Tag: v4.0.1rc1~31
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=7d44c94317941c1cd3d41325a0128010fe5d1331;p=procps-ng

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>
---

diff --git a/doc/procps_pids.3 b/doc/procps_pids.3
index c7b874d2..2308da68 100644
--- a/doc/procps_pids.3
+++ b/doc/procps_pids.3
@@ -152,6 +152,10 @@ As such, the \fIinfo\fR parameter would be NULL and the
 If, however, some items are desired for the issuing program (a
 \fIreturn_self\fR other than zero) then the \fBnew\fR call must precede
 it to identify the \fIitems\fR and obtain the required \fIinfo\fR pointer.
+\fBfatal_proc_unmounted\fR function used in this way will only return a
+subset of values found in /proc/self/stat file. Check the \fIpids_item\fR
+enum in <procps/pids.h> for items with origin of \fIstat:\fR to see what
+are the available values.
 
 .SH RETURN VALUE
 .SS Functions Returning an `int'