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 c7b874d213b548e6bc29ad58823cbdd03b8fb265..2308da68d6148cfd5c3256edb3fecca8397b30c1 100644 (file)
--- 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'