library: standardize portions of interface, <PIDS> api

This represents a rather major interface redesign. The
following highlights most of the changes/enhancements.

. The 'read' interface (employed by pgrep & pidof) saw
the biggest change. The 'open', 'next' and 'shut' guys
all went bye-bye, replaced by a single 'get' function.

. The items specified at 'new' time no longer serve as
the maximum. In fact, items & numitems are now treated
as optional, should callers prefer to wait until later
when the 'reset' function would then become mandatory.

. Even at 'reset' time, the stacks are not tied to any
sort of maximum. They will grow dynamically as needed.

. The order of some parameters was changed to parallel
that found in our other APIs. Specifically, when items
& numitems are needed they're specified in that order.

. A user will no longer be prevented from concurrently
employing any accessor functions. In other words, that
'get' (old 'read') won't preclude 'reap' and 'select'.

. A duplicate enumerator was found dealing with locked
resident pages. So, the name VM_LOCK was eliminated in
favor of VM_RSS_LOCKED, which is way more descriptive.

. The struct address returned to callers following any
reap() or select() is now more sharable as pids_fetch.

. Some input parameter names were changed to make them
more descriptive of the intended purpose/requirements.

------------------------------------------------------
Internally, there were numerous implementation changes
made that did not directly impact any potential users.

. That #define FPRINT_STACKS was eliminated along with
the associated supporting function and its invocation.

. Addresses returned following 'reap' or 'select' will
now be NULL delimited, so one has the option of stacks
access via the total count or this new NULL fencepost.

. Input params were simplified and generalized in both
oldproc_open() & close() to enable more than 1 PROCTAB
to be open simultaneously, which was required for get.

. The PROCPS_PIDS_logical_end enum was relocated after
the Item_table making the need to keep it synchronized
more apparent (if the table expands it's right there).

. The 'Public function' section of the source file was
subdivided into 1) the three basic required functions;
and 2) functions that can sometimes vary between APIs.

Signed-off-by: Jim Warner <james.warner@comcast.net>

1 files changed, 19 insertions, 32 deletions

diff --git a/proc/pids.h b/proc/pids.h
index 9ebaf00..e057bcf 100644
--- a/proc/pids.h
+++ b/proc/pids.h
@@ -133,7 +133,6 @@ enum pids_item {
     PROCPS_PIDS_VM_DATA,               // ul_int
     PROCPS_PIDS_VM_EXE,                // ul_int
     PROCPS_PIDS_VM_LIB,                // ul_int
-    PROCPS_PIDS_VM_LOCK,               // ul_int
     PROCPS_PIDS_VM_RSS,                // ul_int
     PROCPS_PIDS_VM_RSS_ANON,           // ul_int
     PROCPS_PIDS_VM_RSS_FILE,           // ul_int
@@ -148,16 +147,16 @@ enum pids_item {
     PROCPS_PIDS_WCHAN_NAME,            // str
 };
 
+enum pids_fetch_type {
+    PROCPS_FETCH_TASKS_ONLY,
+    PROCPS_FETCH_THREADS_TOO
+};
+
 enum pids_select_type {
     PROCPS_SELECT_PID  = 0x1000,
     PROCPS_SELECT_UID  = 0x4000
 };
 
-enum pids_reap_type {
-    PROCPS_REAP_TASKS_ONLY   = 0,
-    PROCPS_REAP_THREADS_TOO  = 1
-};
-
 enum pids_sort_order {
     PROCPS_SORT_ASCEND   = +1,
     PROCPS_SORT_DESCEND  = -1
@@ -189,7 +188,7 @@ struct pids_counts {
     int running, sleeping, stopped, zombied;
 };
 
-struct pids_reap {
+struct pids_fetch {
     struct pids_stack **stacks;
     struct pids_counts counts;
 };
@@ -199,52 +198,40 @@ struct pids_reap {
     stack -> head [ rel_enum ] . result . type
 
 
+int procps_pids_new   (struct procps_pidsinfo **info, enum pids_item *items, int numitems);
+int procps_pids_ref   (struct procps_pidsinfo  *info);
+int procps_pids_unref (struct procps_pidsinfo **info);
+
 struct pids_stack *fatal_proc_unmounted (
     struct procps_pidsinfo *info,
     int return_self);
 
-int procps_pids_new (
-    struct procps_pidsinfo **info,
-    int maxitems,
-    enum pids_item *items);
-
-struct pids_stack *procps_pids_read_next (
-    struct procps_pidsinfo *info);
-
-int procps_pids_read_open (
+struct pids_stack *procps_pids_get (
     struct procps_pidsinfo *info,
-    enum pids_reap_type which);
+    enum pids_fetch_type which);
 
-int procps_pids_read_shut (
-    struct procps_pidsinfo *info);
-
-struct pids_reap *procps_pids_reap (
+struct pids_fetch *procps_pids_reap (
     struct procps_pidsinfo *info,
-    enum pids_reap_type which);
-
-int procps_pids_ref (
-    struct procps_pidsinfo *info);
+    enum pids_fetch_type which);
 
 int procps_pids_reset (
     struct procps_pidsinfo *info,
-    int newmaxitems,
-    enum pids_item *newitems);
+    enum pids_item *newitems,
+    int newnumitems);
 
-struct pids_reap *procps_pids_select (
+struct pids_fetch *procps_pids_select (
     struct procps_pidsinfo *info,
     unsigned *these,
-    int maxthese,
+    int numthese,
     enum pids_select_type which);
 
 struct pids_stack **procps_pids_sort (
     struct procps_pidsinfo *info,
     struct pids_stack *stacks[],
     int numstacked,
-    enum pids_item sort,
+    enum pids_item sortitem,
     enum pids_sort_order order);
 
-int procps_pids_unref (
-    struct procps_pidsinfo **info);
 
 __END_DECLS