Adding upstream version 2:4.0.4.upstream/2%4.0.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 210 insertions, 0 deletions

diff --git a/man/procps_pids.3 b/man/procps_pids.3
new file mode 100644
index 0000000..9ead691
--- /dev/null
+++ b/man/procps_pids.3
@@ -0,0 +1,210 @@
+.\"
+.\" Copyright (c) 2020-2023 Jim Warner <james.warner@comcast.net>
+.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz>
+.\"
+.\" This manual is free software; you can redistribute it and/or
+.\" modify it under the terms of the GNU Lesser General Public
+.\" License as published by the Free Software Foundation; either
+.\" version 2.1 of the License, or (at your option) any later version.
+.\"
+.\"
+.TH PROCPS_PIDS 3 "August 2022" "libproc2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.nh
+.SH NAME
+procps_pids \- API to access process information in the /proc filesystem
+
+.SH SYNOPSIS
+.nf
+#include <libproc2/pids.h>
+
+.RI "int\fB procps_pids_new  \fR (struct pids_info **" info ", enum pids_item *" items ", int " numitems );
+.RI "int\fB procps_pids_ref  \fR (struct pids_info  *" info );
+.RI "int\fB procps_pids_unref\fR (struct pids_info **" info );
+
+
+.RB "struct pids_stack *" procps_pids_get " ("
+.RI "    struct pids_info *" info ,
+.RI "    enum pids_fetch_type " which );
+
+.RB "struct pids_fetch *" procps_pids_reap " ("
+.RI "    struct pids_info *" info ,
+.RI "    enum pids_fetch_type " which );
+
+.RB "struct pids_fetch *" procps_pids_select " ("
+.RI "    struct pids_info *" info ,
+.RI "    unsigned *" these ,
+.RI "    int " numthese ,
+.RI "    enum pids_select_type " which );
+
+.RB "struct pids_stack **" procps_pids_sort " ("
+.RI "    struct pids_info *" info ,
+.RI "    struct pids_stack *" stacks [],
+.RI "    int " numstacked ,
+.RI "    enum pids_item " sortitem ,
+.RI "    enum pids_sort_order " order );
+
+.RB "int " procps_pids_reset " ("
+.RI "    struct pids_info *" info ,
+.RI "    enum pids_item *" newitems ,
+.RI "    int " newnumitems );
+
+.RB "struct pids_stack *" fatal_proc_unmounted " ("
+.RI "    struct pids_info *" info ,
+.RI "    int " return_self );
+
+.fi
+
+Link with \fI\-lproc2\fP.
+
+.SH DESCRIPTION
+.SS Overview
+Central to this interface is a simple `result'
+structure reflecting an `item' plus its value (in a union
+with standard C language types as members).
+All `result' structures are automatically allocated and
+provided by the library.
+
+By specifying an array of `items', these structures can be
+organized as a `stack', potentially yielding many results
+with a single function call.
+Thus, a `stack' can be viewed as a variable length record
+whose content and order is determined solely by the user.
+
+As part of this interface there are two unique enumerators.
+The `noop' and `extra' items exist to hold user values.
+They are never set by the library, but the `extra'
+result will be zeroed with each library interaction.
+
+The pids.h file will be an essential document during
+user program development.
+There you will find available items, their return type
+(the `result' struct member name) and the source for such values.
+Additional enumerators and structures are also documented there.
+
+.SS Usage
+The following would be a typical sequence of calls to
+this interface.
+
+.nf
+.RB "1. " fatal_proc_unmounted()
+.RB "2. " procps_pids_new()
+.RB "3. " procps_pids_get() ", " procps_pids_reap() " or " procps_pids_select()
+.RB "4. " procps_pids_unref()
+.fi
+
+The \fBget\fR function is an iterator for successive PIDs/TIDs,
+returning those `items' previously identified via \fBnew\fR
+or \fBreset\fR.
+
+Two functions support unpredictable variable outcomes.
+The \fBreap\fR function gathers data for all processes while
+the \fBselect\fR function deals with specific PIDs or UIDs.
+Both can return multiple `stacks' each containing multiple `result'
+structures.
+Optionally, a user may choose to \fBsort\fR such results
+
+To exploit any `stack', and access individual `result' structures,
+a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro
+defined in the header file.
+Such values could be hard coded as: 0 through numitems-1.
+However, this need is typically satisfied by creating your own
+enumerators corresponding to the order of the `items' array.
+
+.SS Caveats
+The <pids> API differs from others in that those items
+of interest must be provided at \fBnew\fR or \fBreset\fR time,
+the latter being unique to this API.
+If either the \fIitems\fR or \fInumitems\fR parameter is zero at
+\fBnew\fR time, then \fBreset\fR becomes mandatory before
+issuing any other call.
+
+For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR
+struct pointer must be supplied.
+With \fBnew\fR it must have been initialized to NULL.
+With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
+
+The \fBget\fR and \fBreap\fR functions use the \fIwhich\fR parameter
+to specify whether just tasks or both tasks and threads are to be fetched.
+
+The \fBselect\fR function requires an array of PIDs or UIDs as
+\fIthese\fR along with \fInumthese\fR to identify which processes
+are to be fetched.
+This function then operates as a subset of \fBreap\fR.
+
+When using the \fBsort\fR function, the parameters \fIstacks\fR and
+\fInumstacked\fR would normally be those returned in the `pids_fetch'
+structure.
+
+Lastly, a \fBfatal_proc_unmounted\fR function may be called before
+any other function to ensure that the /proc/ directory is mounted.
+As such, the \fIinfo\fR parameter would be NULL and the
+\fIreturn_self\fR parameter zero.
+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.
+
+.SH RETURN VALUE
+.SS Functions Returning an `int'
+An error will be indicated by a negative number that
+is always the inverse of some well known errno.h value.
+
+Success is indicated by a zero return value.
+However, the \fBref\fR and \fBunref\fR functions return
+the current \fIinfo\fR structure reference count.
+
+.SS Functions Returning an `address'
+An error will be indicated by a NULL return pointer
+with the reason found in the formal errno value.
+
+Success is indicated by a pointer to the named structure.
+However, if one survives the \fBfatal_proc_unmounted\fR call,
+NULL is always returned when \fIreturn_self\fR is zero.
+
+.SH DEBUGGING
+To aid in program development, there are two procps-ng provisions
+that can be exploited.
+
+The first is a supplied file named `libproc.supp' which may be
+useful when developing a \fImulti-threaded\fR application.
+When used with the valgrind `--suppressions=' option, warnings
+associated with the procps library itself are avoided.
+
+Such warnings arise because the library handles heap based
+allocations in a thread-safe manner.
+A \fIsingle-threaded\fR application will not receive those warnings.
+
+The second provision can help ensure `result' member references
+agree with library expectations.
+It assumes that a supplied macro in the header file is
+used to access the `result' value.
+
+This feature can be activated through either of the following
+methods and any discrepancies will be written to \fBstderr\fR.
+
+.IP 1) 3
+Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
+options your project may employ.
+
+.IP 2) 3
+Add #include <procps/xtra-procps-debug.h> to any program
+\fIafter\fR the #include <procps/pids.h>.
+
+.PP
+This verification feature incurs substantial overhead.
+Therefore, it is important that it \fInot\fR be activated
+for a production/release build.
+
+.SH ENVIRONMENT VARIABLE(S)
+The value set for the following is unimportant, just its presence.
+
+.IP LIBPROC_HIDE_KERNEL
+This will hide kernel threads which would otherwise be returned with a
+.BR procps_pids_get ", " procps_pids_select " or " procps_pids_reap
+call.
+
+.SH SEE ALSO
+.BR procps (3),
+.BR procps_misc (3),
+.BR proc (5).