library/pids.c - master - githubmirror/procps

library/pids.c
1 778 строк69 KB
Jim Warner
library: correct header #include for mergesort_r users
23 апр 2026, 14:44
23 апр 2026, 14:4444d01a9
/*
 * pids.c - process related definitions for libproc2
 *
 * Copyright © 2015-2026 Jim Warner <james.warner@comcast.net>
 * Copyright © 2015-2024 Craig Small <csmall@dropbear.xyz>
 *
 * This library 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.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 */

#include <ctype.h>
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <unistd.h>

#include <sys/stat.h>
#include <sys/types.h>

#include "devname.h"
#include "numa.h"
#include "readproc.h"
#include "sort.h"
#include "wchan.h"

#include "procps-private.h"
#include "pids.h"


//#define UNREF_RPTHASH                // report hash details at uref() time

#define STACKS_INIT  1024              // amount of initial stack allocation
#define STACKS_GROW  128               // amount reap stack allocations grow
#define NEWOLD_INIT  1024              // amount for initial hist allocation
#define NEWOLD_GROW  128               // amt by which hist allocations grow

/* ------------------------------------------------------------------------- +
   this provision can be used to ensure that our Item_table was synchronized |
   with those enumerators found in the associated header file. It's intended |
   to only be used locally (& temporarily) at some point prior to a release! | */
// #define ITEMTABLE_DEBUG //----------------------------------------------- |
// ------------------------------------------------------------------------- +


struct stacks_extent {
    int ext_numstacks;
    struct stacks_extent *next;
    struct pids_stack **stacks;
};

struct fetch_support {
    struct pids_stack **anchor;        // reap/select consolidated extents
    int n_alloc;                       // number of above pointers allocated
    int n_inuse;                       // number of above pointers occupied
    int n_alloc_save;                  // last known results.stacks allocation
    struct pids_fetch results;         // counts + stacks for return to caller
    struct pids_counts counts;         // actual counts pointed to by 'results'
};

typedef void (*SET_t)(struct pids_info *, struct pids_result *, proc_t *);

struct pids_info {
    int refcount;
    int maxitems;                      // includes 'logical_end' delimiter
    enum pids_item *items;             // includes 'logical_end' delimiter
    struct stacks_extent *extents;     // anchor for all resettable extents
    struct stacks_extent *otherexts;   // anchor for invariant extents // <=== currently unused
    struct fetch_support fetch;        // support for procps_pids_reap, select, fatal
    int history_yes;                   // need historical data
    struct history_info *hist;         // pointer to historical support data
    proc_t*(*read_something)(PROCTAB*, proc_t*); // readproc/readeither via which
    unsigned pgs2k_shift;              // to convert some proc values
    unsigned oldflags;                 // the old library PROC_FILL flagss
    PROCTAB *fetch_PT;                 // oldlib interface for 'select' & 'reap'
    unsigned long hertz;               // for the 'TIME' & 'UTILIZATION' calculations
    unsigned long long boot_tics;      // for TIME_ELAPSED & 'UTILIZATION' calculations
    PROCTAB *get_PT;                   // oldlib interface for active 'get'
    struct stacks_extent *get_ext;     // for active 'get' (also within 'extents')
    enum pids_fetch_type get_type;     // last known type of 'get' request
    int seterr;                        // an ENOMEM encountered during assign
    proc_t get_proc;                   // the proc_t used by procps_pids_get
    proc_t fetch_proc;                 // the proc_t used by pids_stacks_fetch
    SET_t *func_array;                 // extracted Item_table 'setsfunc' pointers
    int containers_yes;                // need to call pids_containers_check
    unsigned *select_ids;              // copy of user 'these' (pids/uids)
};


// ___ Free Storage Support |||||||||||||||||||||||||||||||||||||||||||||||||||

extern char *str_none;

#define freNAME(t) free_pids_ ## t

static void freNAME(str) (struct pids_result *R) {
    if (R->result.str && R->result.str != str_none) free(R->result.str);
}

static void freNAME(strv) (struct pids_result *R) {
    if (R->result.strv && *R->result.strv) free(*R->result.strv);
}


// ___ Special Suppott Function(s) ||||||||||||||||||||||||||||||||||||||||||||

static const char *pids_sched_to_classstr (
//  struct pids_info *,
//  struct pids_result *r,
    proc_t *p)
{
    switch (p->sched) {
        case -1: return "-";   // not reported
        case  0: return "TS";  // SCHED_OTHER SCHED_NORMAL
        case  1: return "FF";  // SCHED_FIFO
        case  2: return "RR";  // SCHED_RR
        case  3: return "B";   // SCHED_BATCH
        case  4: return "ISO"; // reserved for SCHED_ISO (Con Kolivas)
        case  5: return "IDL"; // SCHED_IDLE
        case  6: return "DLN"; // SCHED_DEADLINE
        case  7: return "#7";  //
        case  8: return "#8";  //
        case  9: return "#9";  //
    }
    return "?";
} // end: pids_sched_to_classstr


// ___ Results 'Set' Support ||||||||||||||||||||||||||||||||||||||||||||||||||

#define setNAME(e) set_pids_ ## e
#define setDECL(e) static void setNAME(e) \
    (struct pids_info *I, struct pids_result *R, proc_t *P)

/* convert pages to kib */
#define CVT_set(e,t,x) setDECL(e) { \
    R->result. t = (long)(P-> x) << I -> pgs2k_shift; }
/* strdup of a static char array */
#define DUP_set(e,x) setDECL(e) { \
    freNAME(str)(R); \
    if (!(R->result.str = strdup(P-> x))) I->seterr = 1; }
/* regular assignment copy */
#define REG_set(e,t,x) setDECL(e) { \
    (void)I; R->result. t = P-> x; }
/* take ownership of a normal single string if possible, else return
   some sort of hint that they duplicated this char * item ... */
#define STR_set(e,x) setDECL(e) { \
    freNAME(str)(R); \
    if (NULL != P-> x) { R->result.str = P-> x; P-> x = NULL; } \
    else { R->result.str = strdup("[ duplicate " STRINGIFY(e) " ]"); \
      if (!R->result.str) I->seterr = 1; } }
/* take ownership of true vectorized strings if possible, else return
   some sort of hint that they duplicated this char ** item ... */
#define VEC_set(e,x) setDECL(e) { \
    freNAME(strv)(R); \
    if (NULL != P-> x) { R->result.strv = P-> x;  P-> x = NULL; } \
    else { R->result.strv = vectorize_this_str("[ duplicate " STRINGIFY(e) " ]"); \
      if (!R->result.strv) I->seterr = 1; } }


setDECL(noop)  { (void)I; (void)R; (void)P; }
setDECL(extra) { (void)I; (void)P; R->result.ull_int = 0; }

REG_set(ADDR_CODE_END,    ul_int,  end_code)
REG_set(ADDR_CODE_START,  ul_int,  start_code)
REG_set(ADDR_CURR_EIP,    ul_int,  kstk_eip)
REG_set(ADDR_CURR_ESP,    ul_int,  kstk_esp)
REG_set(ADDR_STACK_START, ul_int,  start_stack)
REG_set(AUTOGRP_ID,       s_int,   autogrp_id)
REG_set(AUTOGRP_NICE,     s_int,   autogrp_nice)
DUP_set(CAPS_PERMITTED,            capprm)
STR_set(CGNAME,                    cgname)
STR_set(CGROUP,                    cgroup)
VEC_set(CGROUP_V,                  cgroup_v)
STR_set(CMD,                       cmd)
STR_set(CMDLINE,                   cmdline)
VEC_set(CMDLINE_V,                 cmdline_v)
REG_set(DOCKER_ID,        str,     dockerid)
REG_set(DOCKER_ID_64,     str,     dockerid_64)
STR_set(ENVIRON,                   environ)
VEC_set(ENVIRON_V,                 environ_v)
STR_set(EXE,                       exe)
REG_set(EXIT_SIGNAL,      s_int,   exit_signal)
REG_set(FLAGS,            ul_int,  flags)
REG_set(FLT_MAJ,          ul_int,  maj_flt)
setDECL(FLT_MAJ_C)      { (void)I; R->result.ul_int = P->maj_flt + P->cmaj_flt; }
REG_set(FLT_MAJ_DELTA,    s_int,   maj_delta)
REG_set(FLT_MIN,          ul_int,  min_flt)
setDECL(FLT_MIN_C)      { (void)I; R->result.ul_int = P->min_flt + P->cmin_flt; }
REG_set(FLT_MIN_DELTA,    s_int,   min_delta)
REG_set(ID_EGID,          u_int,   egid)
REG_set(ID_EGROUP,        str,     egroup)
REG_set(ID_EUID,          u_int,   euid)
REG_set(ID_EUSER,         str,     euser)
REG_set(ID_FGID,          u_int,   fgid)
REG_set(ID_FGROUP,        str,     fgroup)
REG_set(ID_FUID,          u_int,   fuid)
REG_set(ID_FUSER,         str,     fuser)
REG_set(ID_LOGIN,         s_int,   luid)
REG_set(ID_PGRP,          s_int,   pgrp)
REG_set(ID_PID,           s_int,   tid)
REG_set(ID_PPID,          s_int,   ppid)
REG_set(ID_RGID,          u_int,   rgid)
REG_set(ID_RGROUP,        str,     rgroup)
REG_set(ID_RUID,          u_int,   ruid)
REG_set(ID_RUSER,         str,     ruser)
REG_set(ID_SESSION,       s_int,   session)
REG_set(ID_SGID,          u_int,   sgid)
REG_set(ID_SGROUP,        str,     sgroup)
REG_set(ID_SUID,          u_int,   suid)
REG_set(ID_SUSER,         str,     suser)
REG_set(ID_TGID,          s_int,   tgid)
REG_set(ID_TID,           s_int,   tid)
REG_set(ID_TPGID,         s_int,   tpgid)
REG_set(IO_READ_BYTES,    ul_int,  read_bytes)
REG_set(IO_READ_CHARS,    ul_int,  rchar)
REG_set(IO_READ_OPS,      ul_int,  syscr)
REG_set(IO_WRITE_BYTES,   ul_int,  write_bytes)
REG_set(IO_WRITE_CBYTES,  ul_int,  cancelled_write_bytes)
REG_set(IO_WRITE_CHARS,   ul_int,  wchar)
REG_set(IO_WRITE_OPS,     ul_int,  syscw)
REG_set(LXCNAME,          str,     lxcname)
CVT_set(MEM_CODE,         ul_int,  trs)
REG_set(MEM_CODE_PGS,     ul_int,  trs)
CVT_set(MEM_DATA,         ul_int,  drs)
REG_set(MEM_DATA_PGS,     ul_int,  drs)
CVT_set(MEM_RES,          ul_int,  resident)
REG_set(MEM_RES_PGS,      ul_int,  resident)
CVT_set(MEM_SHR,          ul_int,  share)
REG_set(MEM_SHR_PGS,      ul_int,  share)
CVT_set(MEM_VIRT,         ul_int,  size)
REG_set(MEM_VIRT_PGS,     ul_int,  size)
REG_set(NICE,             s_int,   nice)
REG_set(NLWP,             s_int,   nlwp)
REG_set(NS_CGROUP,        ul_int,  ns.ns[0])
REG_set(NS_IPC,           ul_int,  ns.ns[1])
REG_set(NS_MNT,           ul_int,  ns.ns[2])
REG_set(NS_NET,           ul_int,  ns.ns[3])
REG_set(NS_PID,           ul_int,  ns.ns[4])
REG_set(NS_TIME,          ul_int,  ns.ns[5])
REG_set(NS_USER,          ul_int,  ns.ns[6])
REG_set(NS_UTS,           ul_int,  ns.ns[7])
REG_set(OOM_ADJ,          s_int,   oom_adj)
REG_set(OOM_SCORE,        s_int,   oom_score)
REG_set(OPEN_FILES,       s_int,   fds)
REG_set(PRIORITY,         s_int,   priority)
REG_set(PRIORITY_RT,      s_int,   rtprio)
REG_set(PROCESSOR,        s_int,   processor)
setDECL(PROCESSOR_NODE) { (void)I; R->result.s_int = numa_node_of_cpu(P->processor); }
REG_set(RSS,              ul_int,  rss)
REG_set(RSS_RLIM,         ul_int,  rss_rlim)
REG_set(SCHED_CLASS,      s_int,   sched)
setDECL(SCHED_CLASSSTR) { (void)I; R->result.str = (char *)pids_sched_to_classstr(P); }
STR_set(SD_MACH,                   sd_mach)
STR_set(SD_OUID,                   sd_ouid)
STR_set(SD_SEAT,                   sd_seat)
STR_set(SD_SESS,                   sd_sess)
STR_set(SD_SLICE,                  sd_slice)
STR_set(SD_UNIT,                   sd_unit)
STR_set(SD_UUNIT,                  sd_uunit)
DUP_set(SIGBLOCKED,                blocked)
DUP_set(SIGCATCH,                  sigcatch)
DUP_set(SIGIGNORE,                 sigignore)
DUP_set(SIGNALS,                   signal)
DUP_set(SIGPENDING,                _sigpnd)
REG_set(SMAP_ANONYMOUS,   ul_int,  smap_Anonymous)
REG_set(SMAP_HUGE_ANON,   ul_int,  smap_AnonHugePages)
REG_set(SMAP_HUGE_FILE,   ul_int,  smap_FilePmdMapped)
REG_set(SMAP_HUGE_SHMEM,  ul_int,  smap_ShmemPmdMapped)
REG_set(SMAP_HUGE_TLBPRV, ul_int,  smap_Private_Hugetlb)
REG_set(SMAP_HUGE_TLBSHR, ul_int,  smap_Shared_Hugetlb)
REG_set(SMAP_LAZY_FREE,   ul_int,  smap_LazyFree)
REG_set(SMAP_LOCKED,      ul_int,  smap_Locked)
REG_set(SMAP_PRV_CLEAN,   ul_int,  smap_Private_Clean)
REG_set(SMAP_PRV_DIRTY,   ul_int,  smap_Private_Dirty)
setDECL(SMAP_PRV_TOTAL) { (void)I; R->result.ul_int = P->smap_Private_Clean + P->smap_Private_Dirty; }
REG_set(SMAP_PSS,         ul_int,  smap_Pss)
REG_set(SMAP_PSS_ANON,    ul_int,  smap_Pss_Anon)
REG_set(SMAP_PSS_FILE,    ul_int,  smap_Pss_File)
REG_set(SMAP_PSS_SHMEM,   ul_int,  smap_Pss_Shmem)
REG_set(SMAP_REFERENCED,  ul_int,  smap_Referenced)
REG_set(SMAP_RSS,         ul_int,  smap_Rss)
REG_set(SMAP_SHR_CLEAN,   ul_int,  smap_Shared_Clean)
REG_set(SMAP_SHR_DIRTY,   ul_int,  smap_Shared_Dirty)
REG_set(SMAP_SWAP,        ul_int,  smap_Swap)
REG_set(SMAP_SWAP_PSS,    ul_int,  smap_SwapPss)
REG_set(STATE,            s_ch,    state)
STR_set(SUPGIDS,                   supgid)
STR_set(SUPGROUPS,                 supgrp)
setDECL(TICS_ALL)       { (void)I; R->result.ull_int = P->utime + P->stime; }
setDECL(TICS_ALL_C)     { (void)I; R->result.ull_int = P->utime + P->stime + P->cutime + P->cstime; }
REG_set(TICS_ALL_DELTA,   u_int,   pcpu)
REG_set(TICS_BEGAN,       ull_int, start_time)
REG_set(TICS_BLKIO,       ull_int, blkio_tics)
REG_set(TICS_GUEST,       ull_int, gtime)
setDECL(TICS_GUEST_C)   { (void)I; R->result.ull_int = P->gtime + P->cgtime; }
REG_set(TICS_SYSTEM,      ull_int, stime)
setDECL(TICS_SYSTEM_C)  { (void)I; R->result.ull_int = P->stime + P->cstime; }
REG_set(TICS_USER,        ull_int, utime)
setDECL(TICS_USER_C)    { (void)I; R->result.ull_int = P->utime + P->cutime; }
setDECL(TIME_ALL)       { R->result.real = ((double)P->utime + P->stime) / I->hertz; }
setDECL(TIME_ALL_C)     { R->result.real = ((double)P->utime + P->stime + P->cutime + P->cstime) / I->hertz; }
setDECL(TIME_ELAPSED)   { double t = (double)I->boot_tics - P->start_time; if (t > 0) R->result.real = t / I->hertz; }
setDECL(TIME_START)     { R->result.real = (double)P->start_time / I->hertz; }
REG_set(TTY,              s_int,   tty)
setDECL(TTY_NAME)       { char buf[64]; freNAME(str)(R); dev_to_tty(buf, sizeof(buf), P->tty, P->tid, ABBREV_DEV); if (!(R->result.str = strdup(buf))) I->seterr = 1; }
setDECL(TTY_NUMBER)     { char buf[64]; freNAME(str)(R); dev_to_tty(buf, sizeof(buf), P->tty, P->tid, ABBREV_DEV|ABBREV_TTY|ABBREV_PTS); if (!(R->result.str = strdup(buf))) I->seterr = 1; }
setDECL(UTILIZATION)    { double t = (double)I->boot_tics - P->start_time; if (t > 0) R->result.real = ((P->utime + P->stime) * 100.0f) / t; }
setDECL(UTILIZATION_C)  { double t = (double)I->boot_tics - P->start_time; if (t > 0) R->result.real = ((P->utime + P->stime + P->cutime + P->cstime) * 100.0f) / t; }
REG_set(VM_DATA,          ul_int,  vm_data)
REG_set(VM_EXE,           ul_int,  vm_exe)
REG_set(VM_LIB,           ul_int,  vm_lib)
REG_set(VM_RSS,           ul_int,  vm_rss)
REG_set(VM_RSS_ANON,      ul_int,  vm_rss_anon)
REG_set(VM_RSS_FILE,      ul_int,  vm_rss_file)
REG_set(VM_RSS_LOCKED,    ul_int,  vm_lock)
REG_set(VM_RSS_SHARED,    ul_int,  vm_rss_shared)
REG_set(VM_SIZE,          ul_int,  vm_size)
REG_set(VM_STACK,         ul_int,  vm_stack)
REG_set(VM_SWAP,          ul_int,  vm_swap)
setDECL(VM_USED)        { (void)I; R->result.ul_int = P->vm_swap + P->vm_rss; }
REG_set(VSIZE_BYTES,      ul_int,  vsize)
setDECL(WCHAN_NAME)     { freNAME(str)(R); if (!(R->result.str = strdup(lookup_wchan(P->tid)))) I->seterr = 1; }

#undef setDECL
#undef CVT_set
#undef DUP_set
#undef REG_set
#undef STR_set
#undef VEC_set


// ___ Sorting Support ||||||||||||||||||||||||||||||||||||||||||||||||||||||||

struct sort_parms {
    int offset;
    enum pids_sort_order order;
};

#define srtNAME(t) sort_pids_ ## t
#define srtDECL(t) static int srtNAME(t) \
    (const struct pids_stack **A, const struct pids_stack **B, struct sort_parms *P)

#define NUM_srt(T) srtDECL(T) { \
    const struct pids_result *a = (*A)->head + P->offset; \
    const struct pids_result *b = (*B)->head + P->offset; \
    return P->order * (a->result. T - b->result. T); }

#define REG_srt(T) srtDECL(T) { \
    const struct pids_result *a = (*A)->head + P->offset; \
    const struct pids_result *b = (*B)->head + P->offset; \
    if ( a->result. T > b->result. T ) return P->order > 0 ?  1 : -1; \
    if ( a->result. T < b->result. T ) return P->order > 0 ? -1 :  1; \
    return 0; }

NUM_srt(s_ch)
NUM_srt(s_int)

REG_srt(u_int)
REG_srt(ul_int)
REG_srt(ull_int)

REG_srt(real)

srtDECL(str) {
    const struct pids_result *a = (*A)->head + P->offset;
    const struct pids_result *b = (*B)->head + P->offset;
    return P->order * strcoll(a->result.str, b->result.str);
}

srtDECL(strv) {
    const struct pids_result *a = (*A)->head + P->offset;
    const struct pids_result *b = (*B)->head + P->offset;
    if (!a->result.strv || !b->result.strv) return 0;
    return P->order * strcoll((*a->result.strv), (*b->result.strv));
}

srtDECL(strvers) {
    const struct pids_result *a = (*A)->head + P->offset;
    const struct pids_result *b = (*B)->head + P->offset;
    return P->order * strverscmp(a->result.str, b->result.str);
}

srtDECL(noop) {
    (void)A; (void)B; (void)P;
    return 0;
}

#undef srtDECL
#undef NUM_srt
#undef REG_srt


// ___ Controlling Table ||||||||||||||||||||||||||||||||||||||||||||||||||||||

#define f_either   PROC_SPARE_1        // either status or stat (favor stat)
#define f_exe      PROC_FILL_EXE
#define f_fds      PROC_FILL_FDS
#define f_grp      PROC_FILLGRP
#define f_io       PROC_FILLIO
#define f_login    PROC_FILL_LUID
#define f_lxc      PROC_FILL_LXC
#define f_ns       PROC_FILLNS
#define f_oom      PROC_FILLOOM
#define f_smaps    PROC_FILLSMAPS
#define f_stat     PROC_FILLSTAT
#define f_statm    PROC_FILLMEM
#define f_status   PROC_FILLSTATUS
#define f_systemd  PROC_FILLSYSTEMD
#define f_usr      PROC_FILLUSR
   // these next three will yield true verctorized strings
#define v_arg      PROC_FILLARG
#define v_cgroup   PROC_FILLCGROUP
#define v_env      PROC_FILLENV
   // these next three will yield a single string (never vectorized)
#define x_cgroup   PROC_EDITCGRPCVT
#define x_cmdline  PROC_EDITCMDLCVT
#define x_environ  PROC_EDITENVRCVT
   // these next three will also force PROC_FILLSTATUS
#define x_ogroup   PROC_FILL_OGROUPS
#define x_ouser    PROC_FILL_OUSERS
#define x_supgrp   PROC_FILL_SUPGRP
   // placed here so an 'f' prefix wouldn't put at/near 1st
#define z_autogrp  PROC_FILLAUTOGRP
#define z_docker   PROC_FILL_DOCKER

typedef void (*FRE_t)(struct pids_result *);
typedef int  (*QSR_t)(const void *, const void *, void *);

#ifdef ITEMTABLE_DEBUG
#define RS(e) (SET_t)setNAME(e), PIDS_ ## e, STRINGIFY(PIDS_ ## e)
#else
#define RS(e) (SET_t)setNAME(e)
#endif
#define FF(t) (FRE_t)freNAME(t)
#define QS(t) (QSR_t)srtNAME(t)
#define TS(t) STRINGIFY(t)
#define TS_noop ""

        /*
         * Need it be said?
         * This table must be kept in the exact same order as
         * those 'enum pids_item' guys ! */
static struct {
    SET_t    setsfunc;            // the actual result setting routine
#ifdef ITEMTABLE_DEBUG
    int      enumnumb;            // enumerator (must match position!)
    char    *enum2str;            // enumerator name as a char* string
#endif
    unsigned oldflags;            // PROC_FILLxxxx flags for this item
    FRE_t    freefunc;            // free function for strings storage
    QSR_t    sortfunc;            // sort cmp func for a specific type
    int      needhist;            // a result requires history support
    char    *type2str;            // the result type as a string value
} Item_table[] = {
/*    setsfunc               oldflags    freefunc   sortfunc       needhist  type2str
      ---------------------  ----------  ---------  -------------  --------  ----------- */
    { RS(noop),              0,          NULL,      QS(noop),      0,        TS_noop     }, // user only, never altered
    { RS(extra),             0,          NULL,      QS(ull_int),   0,        TS_noop     }, // user only, reset to zero

    { RS(ADDR_CODE_END),     f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(ADDR_CODE_START),   f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(ADDR_CURR_EIP),     f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(ADDR_CURR_ESP),     f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(ADDR_STACK_START),  f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(AUTOGRP_ID),        z_autogrp,  NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(AUTOGRP_NICE),      z_autogrp,  NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(CAPS_PERMITTED),    f_status,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(CGNAME),            x_cgroup,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(CGROUP),            x_cgroup,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(CGROUP_V),          v_cgroup,   FF(strv),  QS(strv),      0,        TS(strv)    },
    { RS(CMD),               f_either,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(CMDLINE),           x_cmdline,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(CMDLINE_V),         v_arg,      FF(strv),  QS(strv),      0,        TS(strv)    },
    { RS(DOCKER_ID),         z_docker,   NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(DOCKER_ID_64),      z_docker,   NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(ENVIRON),           x_environ,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(ENVIRON_V),         v_env,      FF(strv),  QS(strv),      0,        TS(strv)    },
    { RS(EXE),               f_exe,      FF(str),   QS(str),       0,        TS(str)     },
    { RS(EXIT_SIGNAL),       f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(FLAGS),             f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(FLT_MAJ),           f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(FLT_MAJ_C),         f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(FLT_MAJ_DELTA),     f_stat,     NULL,      QS(s_int),     +1,       TS(s_int)   },
    { RS(FLT_MIN),           f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(FLT_MIN_C),         f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(FLT_MIN_DELTA),     f_stat,     NULL,      QS(s_int),     +1,       TS(s_int)   },
    { RS(ID_EGID),           0,          NULL,      QS(u_int),     0,        TS(u_int)   }, // oldflags: free w/ simple_read
    { RS(ID_EGROUP),         f_grp,      NULL,      QS(str),       0,        TS(str)     },
    { RS(ID_EUID),           0,          NULL,      QS(u_int),     0,        TS(u_int)   }, // oldflags: free w/ simple_read
    { RS(ID_EUSER),          f_usr,      NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(ID_FGID),           f_status,   NULL,      QS(u_int),     0,        TS(u_int)   },
    { RS(ID_FGROUP),         x_ogroup,   NULL,      QS(str),       0,        TS(str)     },
    { RS(ID_FUID),           f_status,   NULL,      QS(u_int),     0,        TS(u_int)   },
    { RS(ID_FUSER),          x_ouser,    NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(ID_LOGIN),          f_login,    NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(ID_PGRP),           f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(ID_PID),            0,          NULL,      QS(s_int),     0,        TS(s_int)   }, // oldflags: free w/ simple_nextpid
    { RS(ID_PPID),           f_either,   NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(ID_RGID),           f_status,   NULL,      QS(u_int),     0,        TS(u_int)   },
    { RS(ID_RGROUP),         x_ogroup,   NULL,      QS(str),       0,        TS(str)     },
    { RS(ID_RUID),           f_status,   NULL,      QS(u_int),     0,        TS(u_int)   },
    { RS(ID_RUSER),          x_ouser,    NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(ID_SESSION),        f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(ID_SGID),           f_status,   NULL,      QS(u_int),     0,        TS(u_int)   },
    { RS(ID_SGROUP),         x_ogroup,   NULL,      QS(str),       0,        TS(str)     },
    { RS(ID_SUID),           f_status,   NULL,      QS(u_int),     0,        TS(u_int)   },
    { RS(ID_SUSER),          x_ouser,    NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(ID_TGID),           0,          NULL,      QS(s_int),     0,        TS(s_int)   }, // oldflags: free w/ simple_nextpid
    { RS(ID_TID),            0,          NULL,      QS(s_int),     0,        TS(s_int)   }, // oldflags: free w/ simple_nexttid
    { RS(ID_TPGID),          f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(IO_READ_BYTES),     f_io,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(IO_READ_CHARS),     f_io,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(IO_READ_OPS),       f_io,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(IO_WRITE_BYTES),    f_io,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(IO_WRITE_CBYTES),   f_io,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(IO_WRITE_CHARS),    f_io,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(IO_WRITE_OPS),      f_io,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(LXCNAME),           f_lxc,      NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(MEM_CODE),          f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_CODE_PGS),      f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_DATA),          f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_DATA_PGS),      f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_RES),           f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_RES_PGS),       f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_SHR),           f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_SHR_PGS),       f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_VIRT),          f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(MEM_VIRT_PGS),      f_statm,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NICE),              f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(NLWP),              f_either,   NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(NS_CGROUP),         f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NS_IPC),            f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NS_MNT),            f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NS_NET),            f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NS_PID),            f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NS_TIME),           f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NS_USER),           f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(NS_UTS),            f_ns,       NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(OOM_ADJ),           f_oom,      NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(OOM_SCORE),         f_oom,      NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(OPEN_FILES),        f_fds,      NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(PRIORITY),          f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(PRIORITY_RT),       f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(PROCESSOR),         f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(PROCESSOR_NODE),    f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(RSS),               f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(RSS_RLIM),          f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SCHED_CLASS),       f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(SCHED_CLASSSTR),    f_stat,     NULL,      QS(str),       0,        TS(str)     }, // freefunc NULL w/ cached string
    { RS(SD_MACH),           f_systemd,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(SD_OUID),           f_systemd,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(SD_SEAT),           f_systemd,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(SD_SESS),           f_systemd,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(SD_SLICE),          f_systemd,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(SD_UNIT),           f_systemd,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(SD_UUNIT),          f_systemd,  FF(str),   QS(str),       0,        TS(str)     },
    { RS(SIGBLOCKED),        f_status,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(SIGCATCH),          f_status,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(SIGIGNORE),         f_status,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(SIGNALS),           f_status,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(SIGPENDING),        f_status,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(SMAP_ANONYMOUS),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_HUGE_ANON),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_HUGE_FILE),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_HUGE_SHMEM),   f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_HUGE_TLBPRV),  f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_HUGE_TLBSHR),  f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_LAZY_FREE),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_LOCKED),       f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_PRV_CLEAN),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_PRV_DIRTY),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_PRV_TOTAL),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_PSS),          f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_PSS_ANON),     f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_PSS_FILE),     f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_PSS_SHMEM),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_REFERENCED),   f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_RSS),          f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_SHR_CLEAN),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_SHR_DIRTY),    f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_SWAP),         f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(SMAP_SWAP_PSS),     f_smaps,    NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(STATE),             f_either,   NULL,      QS(s_ch),      0,        TS(s_ch)    },
    { RS(SUPGIDS),           f_status,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(SUPGROUPS),         x_supgrp,   FF(str),   QS(str),       0,        TS(str)     },
    { RS(TICS_ALL),          f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_ALL_C),        f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_ALL_DELTA),    f_stat,     NULL,      QS(u_int),     +1,       TS(u_int)   },
    { RS(TICS_BEGAN),        f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_BLKIO),        f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_GUEST),        f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_GUEST_C),      f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_SYSTEM),       f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_SYSTEM_C),     f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_USER),         f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TICS_USER_C),       f_stat,     NULL,      QS(ull_int),   0,        TS(ull_int) },
    { RS(TIME_ALL),          f_stat,     NULL,      QS(real),      0,        TS(real)    },
    { RS(TIME_ALL_C),        f_stat,     NULL,      QS(real),      0,        TS(real)    },
    { RS(TIME_ELAPSED),      f_stat,     NULL,      QS(real),      0,        TS(real)    },
    { RS(TIME_START),        f_stat,     NULL,      QS(real),      0,        TS(real)    },
    { RS(TTY),               f_stat,     NULL,      QS(s_int),     0,        TS(s_int)   },
    { RS(TTY_NAME),          f_stat,     FF(str),   QS(strvers),   0,        TS(str)     },
    { RS(TTY_NUMBER),        f_stat,     FF(str),   QS(strvers),   0,        TS(str)     },
    { RS(UTILIZATION),       f_stat,     NULL,      QS(real),      0,        TS(real)    },
    { RS(UTILIZATION_C),     f_stat,     NULL,      QS(real),      0,        TS(real)    },
    { RS(VM_DATA),           f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_EXE),            f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_LIB),            f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_RSS),            f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_RSS_ANON),       f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_RSS_FILE),       f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_RSS_LOCKED),     f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_RSS_SHARED),     f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_SIZE),           f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_STACK),          f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_SWAP),           f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VM_USED),           f_status,   NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(VSIZE_BYTES),       f_stat,     NULL,      QS(ul_int),    0,        TS(ul_int)  },
    { RS(WCHAN_NAME),        0,          FF(str),   QS(str),       0,        TS(str)     }, // oldflags: tid already free
};

    /* please note,
     * this enum MUST be 1 greater than the highest value of any enum */
enum pids_item PIDS_logical_end = MAXTABLE(Item_table);

#undef setNAME
#undef freNAME
#undef srtNAME
#undef RS
#undef FF
#undef QS

//#undef f_either                 // needed later
#undef f_exe
#undef f_fds
#undef f_grp
#undef f_io
#undef f_login
//#undef f_lxc                    // needed later
#undef f_ns
#undef f_oom
#undef f_smaps
//#undef f_stat                   // needed later
#undef f_statm
//#undef f_status                 // needed later
#undef f_systemd
#undef f_usr
#undef v_arg
#undef v_cgroup
#undef v_env
#undef x_cgroup
#undef x_cmdline
#undef x_environ
#undef x_ogroup
#undef x_ouser
#undef x_supgrp
#undef z_autogrp
//#undef z_docker                 // needed later


// ___ History Support Private Functions ||||||||||||||||||||||||||||||||||||||
//   ( stolen from top when he wasn't looking ) -------------------------------

#define HHASH_SIZE  4096
#define _HASH_PID_(K) (K & (HHASH_SIZE - 1))

#define Hr(x)  info->hist->x           // 'hist ref', minimize stolen impact

typedef unsigned long long TIC_t;

typedef struct HST_t {
    TIC_t tics;                        // last frame's tics count
    unsigned long maj, min;            // last frame's maj/min_flt counts
    int pid;                           // record 'key'
    int lnk;                           // next on hash chain
} HST_t;


struct history_info {
    int    num_tasks;                  // used as index (tasks tallied)
    int    HHist_siz;                  // max number of HST_t structs
    HST_t *PHist_sav;                  // alternating 'old/new' HST_t anchors
    HST_t *PHist_new;
    int    HHash_one [HHASH_SIZE];     // the actual hash tables
    int    HHash_two [HHASH_SIZE];     // (accessed via PHash_sav/PHash_new)
    int    HHash_nul [HHASH_SIZE];     // an 'empty' hash table image
    int   *PHash_sav;                  // alternating 'old/new' hash tables
    int   *PHash_new;                  // (aka. the 'one/two' actual tables)
};


static void pids_config_history (
        struct pids_info *info)
{
    int i;

    for (i = 0; i < HHASH_SIZE; i++)   // make the 'empty' table image
        Hr(HHash_nul[i]) = -1;
    memcpy(Hr(HHash_one), Hr(HHash_nul), sizeof(Hr(HHash_nul)));
    memcpy(Hr(HHash_two), Hr(HHash_nul), sizeof(Hr(HHash_nul)));
    Hr(PHash_sav) = Hr(HHash_one);     // alternating 'old/new' hash tables
    Hr(PHash_new) = Hr(HHash_two);
} // end: pids_config_history


static inline HST_t *pids_histget (
        struct pids_info *info,
        int pid)
{
    int V = Hr(PHash_sav[_HASH_PID_(pid)]);

    while (-1 < V) {
        if (Hr(PHist_sav[V].pid) == pid)
            return &Hr(PHist_sav[V]);
        V = Hr(PHist_sav[V].lnk);
    }
    return NULL;
} // end: pids_histget


static inline void pids_histput (
        struct pids_info *info,
        unsigned this)
{
    int V = _HASH_PID_(Hr(PHist_new[this].pid));

    Hr(PHist_new[this].lnk) = Hr(PHash_new[V]);
    Hr(PHash_new[V] = this);
} // end: pids_histput

#undef _HASH_PID_


static inline int pids_make_hist (
        struct pids_info *info,
        proc_t *p)
{
    TIC_t tics;
    HST_t *h;
    int slot = info->hist->num_tasks;

    if (slot + 1 >= Hr(HHist_siz)) {
        Hr(HHist_siz) += NEWOLD_GROW;
        Hr(PHist_sav) = realloc(Hr(PHist_sav), sizeof(HST_t) * Hr(HHist_siz));
        Hr(PHist_new) = realloc(Hr(PHist_new), sizeof(HST_t) * Hr(HHist_siz));
        if (!Hr(PHist_sav) || !Hr(PHist_new))
            return 0;
    }
    Hr(PHist_new[slot].pid)  = p->tid;
    Hr(PHist_new[slot].maj)  = p->maj_flt;
    Hr(PHist_new[slot].min)  = p->min_flt;
    Hr(PHist_new[slot].tics) = tics = (p->utime + p->stime);

    pids_histput(info, slot);

    if ((h = pids_histget(info, p->tid))) {
        tics -= h->tics;
        p->maj_delta = p->maj_flt - h->maj;
        p->min_delta = p->min_flt - h->min;
    }
    /* here we're saving elapsed tics, which will include any
       tasks not previously seen via that pids_histget() guy! */
    p->pcpu = tics;

    info->hist->num_tasks++;
    return 1;
} // end: pids_make_hist


static inline void pids_toggle_history (
        struct pids_info *info)
{
    void *v;

    v = Hr(PHist_sav);
    Hr(PHist_sav) = Hr(PHist_new);
    Hr(PHist_new) = v;

    v = Hr(PHash_sav);
    Hr(PHash_sav) = Hr(PHash_new);
    Hr(PHash_new) = v;
    memcpy(Hr(PHash_new), Hr(HHash_nul), sizeof(Hr(HHash_nul)));

    info->hist->num_tasks = 0;
} // end: pids_toggle_history


#ifdef UNREF_RPTHASH
static void pids_unref_rpthash (
        struct pids_info *info)
{
    int i, j, pop, total_occupied, maxdepth, maxdepth_sav, numdepth
        , cross_foot, sz = HHASH_SIZE * (int)sizeof(int)
        , hsz = (int)sizeof(HST_t) * Hr(HHist_siz);
    int depths[HHASH_SIZE];

    for (i = 0, total_occupied = 0, maxdepth = 0; i < HHASH_SIZE; i++) {
        int V = Hr(PHash_new[i]);
        j = 0;
        if (-1 < V) {
            ++total_occupied;
            while (-1 < V) {
                V = Hr(PHist_new[V].lnk);
                if (-1 < V) j++;
            }
        }
        depths[i] = j;
        if (maxdepth < j) maxdepth = j;
    }
    maxdepth_sav = maxdepth;

    fprintf(stderr,
        "\n    History Memory Costs:"
        "\n\tHST_t size = %d, total allocated = %d,"
        "\n\tthus PHist_new & PHist_sav consumed %dk (%d) total bytes."
        "\n"
        "\n\tTwo hash tables provide for %d entries each + 1 extra 'empty' image,"
        "\n\tthus %dk (%d) bytes per table for %dk (%d) total bytes."
        "\n"
        "\n\tGrand total = %dk (%d) bytes."
        "\n"
        "\n    Hash Results Report:"
        "\n\tTotal hashed = %d"
        "\n\tLevel-0 hash entries = %d (%d%% occupied)"
        "\n\tMax Depth = %d"
        "\n\n"
        , (int)sizeof(HST_t),  Hr(HHist_siz)
        , hsz / 1024, hsz
        , HHASH_SIZE
        , sz / 1024, sz, (sz * 3) / 1024, sz * 3
        , (hsz + (sz * 3)) / 1024, hsz + (sz * 3)
        , info->hist->num_tasks
        , total_occupied, (total_occupied * 100) / HHASH_SIZE
        , maxdepth);

    if (total_occupied) {
        for (pop = total_occupied, cross_foot = 0; maxdepth; maxdepth--) {
            for (i = 0, numdepth = 0; i < HHASH_SIZE; i++)
                if (depths[i] == maxdepth) ++numdepth;
            if (numdepth) fprintf(stderr,
                "\t %5d (%3d%%) hash table entries at depth %d\n"
                , numdepth, (numdepth * 100) / total_occupied, maxdepth);
            pop -= numdepth;
            cross_foot += numdepth;
            if (0 == pop && cross_foot == total_occupied) break;
        }
        if (pop) {
            fprintf(stderr, "\t %5d (%3d%%) unchained entries (at depth 0)\n"
                , pop, (pop * 100) / total_occupied);
            cross_foot += pop;
        }
        fprintf(stderr,
            "\t -----\n"
            "\t %5d total entries occupied\n", cross_foot);

        if (maxdepth_sav > 1) {
            fprintf(stderr, "\n    PIDs at max depth: ");
            for (i = 0; i < HHASH_SIZE; i++)
                if (depths[i] == maxdepth_sav) {
                    j = Hr(PHash_new[i]);
                    fprintf(stderr, "\n\tpos %4d:  %05d", i, Hr(PHist_new[j].pid));
                    while (-1 < j) {
                        j = Hr(PHist_new[j].lnk);
                        if (-1 < j) fprintf(stderr, ", %05d", Hr(PHist_new[j].pid));
                    }
                }
            fprintf(stderr, "\n");
        }
    }
} // end: pids_unref_rpthash
#endif // UNREF_RPTHASH

#undef Hr
#undef HHASH_SIZE


// ___ Unique/Specialized Private Function(s) |||||||||||||||||||||||||||||||||

        /*
         * This routine periodically invokes the garbage collection services
         * embedded in 'lxc' and 'docker' container extraction functions. It
         * exists in case a library caller (like top) is kept running for an
         * extended period of time (perhaps weeks or months). In such a case
         * containers long since disappeared would otherwise be tracked thus
         * consuming ever more memory while needlessly slowing the searches. */
static void pids_containers_check (void) {
 #define oneDAY (60 * 60 * 24)
    static __thread time_t sav_secs;
    time_t cur_secs = time(NULL);

    if (!sav_secs)
       sav_secs = cur_secs;
    else if (oneDAY <= (cur_secs - sav_secs)) {
        lxc_containers(NULL);
        docker_containers(NULL);
        sav_secs = cur_secs;
    }
    return;
 #undef oneDAY
} // pids_containers_check



// ___ Standard Private Functions |||||||||||||||||||||||||||||||||||||||||||||

static inline int pids_assign_results (
        struct pids_info *info,
        struct pids_stack *stack,
        proc_t *p)
{
    struct pids_result *this = stack->head;
    SET_t *that = &info->func_array[0];

    info->seterr = 0;
    while (*that) {
        (*that)(info, this, p);
        ++this;
        ++that;
    }
    return !info->seterr;
} // end: pids_assign_results


static inline void pids_cleanup_stack (
        struct pids_result *this)
{
    for (;;) {
        enum pids_item item = this->item;
        if (item >= PIDS_logical_end)
            break;
        if (Item_table[item].freefunc)
            Item_table[item].freefunc(this);
        this->result.ull_int = 0;
        ++this;
    }
} // end: pids_cleanup_stack


static inline void pids_cleanup_stacks_all (
        struct pids_info *info)
{
    struct stacks_extent *ext = info->extents;
    int i;

    while (ext) {
        for (i = 0; ext->stacks[i]; i++)
            pids_cleanup_stack(ext->stacks[i]->head);
        ext = ext->next;
    };
} // end: pids_cleanup_stacks_all


#if 0   // not currently needed after 'fatal_proc_unmounted' was refactored
        /*
         * This routine exists in case we ever want to offer something like
         * 'static' or 'invarient' results stacks.  By unsplicing an extent
         * from the info anchor it will be isolated from future reset/free. */
static struct stacks_extent *pids_extent_cut (
        struct pids_info *info,
        struct stacks_extent *ext)
{
    struct stacks_extent *p = info->extents;

    if (ext) {
        if (ext == p) {
            info->extents = p->next;
            return ext;
        }
        do {
            if (ext == p->next) {
                p->next = p->next->next;
                return ext;
            }
            p = p->next;
        } while (p);
    }
    return NULL;
} // end: pids_extent_cut
#endif  // ----------------------------------------------------------------


static inline struct pids_result *pids_itemize_stack (
        struct pids_result *p,
        int depth,
        enum pids_item *items)
{
    struct pids_result *p_sav = p;
    int i;

    for (i = 0; i < depth; i++) {
        p->item = items[i];
        ++p;
    }
    return p_sav;
} // end: pids_itemize_stack


static void pids_itemize_stacks_all (
        struct pids_info *info)
{
    struct stacks_extent *ext = info->extents;

    while (ext) {
        int i;
        for (i = 0; ext->stacks[i]; i++)
            pids_itemize_stack(ext->stacks[i]->head, info->maxitems, info->items);
        ext = ext->next;
    };
} // end: pids_itemize_stacks_all


static inline int pids_items_check_failed (
        enum pids_item *items,
        int numitems)
{
    int i;

    /* if an enum is passed instead of an address of one or more enums, ol' gcc
     * will silently convert it to an address (possibly NULL).  only clang will
     * offer any sort of warning like the following:
     *
     * warning: incompatible integer to pointer conversion passing 'int' to parameter of type 'enum pids_item *'
     * if (procps_pids_new(&info, PIDS_noop, 3) < 0)
     *                            ^~~~~~~~~~~~~~~~
     */
    if (numitems < 1
    || (void *)items < (void *)0x8000)      // twice as big as our largest enum
        return 1;

    for (i = 0; i < numitems; i++) {
        // a pids_item is currently unsigned, but we'll protect our future
        if (items[i] < 0)
            return 1;
        if (items[i] >= PIDS_logical_end) {
            return 1;
        }
    }
    return 0;
} // end: pids_items_check_failed


static inline void pids_libflags_set (
        struct pids_info *info)
{
    enum pids_item e;
    int i;

    info->oldflags = info->history_yes = 0;
    for (i = 0; i < info->maxitems; i++) {
        if (((e = info->items[i])) >= PIDS_logical_end)
            break;
        info->oldflags |= Item_table[e].oldflags;
        info->history_yes |= Item_table[e].needhist;
    }
//  note: the read of f_stat has been made unconditional in readproc.c
//        so this logic is no longer useful ...
//  if (info->oldflags & f_either) {
//      if (!(info->oldflags & (f_stat | f_status)))
//          info->oldflags |= f_stat;
//  }
    info->containers_yes = info->oldflags & (f_lxc | z_docker);
    return;
} // end: pids_libflags_set


static inline void pids_oldproc_close (
        PROCTAB **this)
{
    if (*this != NULL) {
        int errsav = errno;
        closeproc(*this);
        *this = NULL;
        errno = errsav;
    }
} // end: pids_oldproc_close


static inline int pids_oldproc_open (
        PROCTAB **this,
        unsigned flags,
        ...)
{
    va_list vl;
    int *ids;
    int num = 0;

    if (*this == NULL) {
        va_start(vl, flags);
        ids = va_arg(vl, int*);
        if (flags & PROC_UID) num = va_arg(vl, int);
        va_end(vl);
        if (NULL == (*this = openproc(flags, ids, num)))
            return 0;
    }
    return 1;
} // end: pids_oldproc_open


static int pids_prep_func_array (
        struct pids_info *info)
{
    int i;

    if (!(info->func_array = realloc(info->func_array, sizeof(SET_t) * info->maxitems)))
        return 0;
    for (i = 0; i < info->maxitems -1; i++)
        info->func_array[i] = Item_table[info->items[i]].setsfunc;
    info->func_array[i] = NULL;
    return 1;
} // end: pids_prep_func_array


static inline int pids_proc_tally (
        struct pids_info *info,
        struct pids_counts *counts,
        proc_t *p)
{
    switch (p->state) {
        case 'R':
            ++counts->running;
            break;
        case 'D':
            ++counts->disk_sleep;
            break;
        case 'S':
            ++counts->sleeping;
            break;
        case 't':      // 't' (tracing stop)
        case 'T':
            ++counts->stopped;
            break;
        case 'Z':
            ++counts->zombied;
            break;
        default:
            /* currently: 'I' (idle),
                          'P' (parked),
                          'X' (dead - actually 'dying' & probably never seen)
            */
            ++counts->other;
            break;
    }
    ++counts->total;

    if (info->history_yes)
        return pids_make_hist(info, p);
    return 1;
} // end: pids_proc_tally


/*
 * pids_stacks_alloc():
 *
 * Allocate and initialize one or more stacks each of which is anchored in an
 * associated context structure.
 *
 * All such stacks will will have their result structures properly primed with
 * 'items', while the result itself will be zeroed.
 *
 * Returns an array of pointers representing the 'heads' of each new stack.
 */
static struct stacks_extent *pids_stacks_alloc (
        struct pids_info *info,
        int maxstacks)
{
    struct stacks_extent *p_blob;
    struct pids_stack **p_vect;
    struct pids_stack *p_head;
    size_t vect_size, head_size, list_size, blob_size;
    void *v_head, *v_list;
    int i;

    vect_size  = sizeof(void *) * maxstacks;                   // size of the addr vectors |
    vect_size += sizeof(void *);                               // plus NULL addr delimiter |
    head_size  = sizeof(struct pids_stack);                    // size of that head struct |
    list_size  = sizeof(struct pids_result) * info->maxitems;  // any single results stack |
    blob_size  = sizeof(struct stacks_extent);                 // the extent anchor itself |
    blob_size += vect_size;                                    // plus room for addr vects |
    blob_size += head_size * maxstacks;                        // plus room for head thing |
    blob_size += list_size * maxstacks;                        // plus room for our stacks |

    /* note: all of our memory is allocated in a single blob, facilitating a later free(). |
             as a minimum, it is important that the result structures themselves always be |
             contiguous for every stack since they are accessed through relative position. | */
    if (NULL == (p_blob = calloc(1, blob_size)))
        return NULL;

    p_blob->next = info->extents;                              // push this extent onto... |
    info->extents = p_blob;                                    // ...some existing extents |
    p_vect = (void *)p_blob + sizeof(struct stacks_extent);    // prime our vector pointer |
    p_blob->stacks = p_vect;                                   // set actual vectors start |
    v_head = (void *)p_vect + vect_size;                       // prime head pointer start |
    v_list = v_head + (head_size * maxstacks);                 // prime our stacks pointer |

    for (i = 0; i < maxstacks; i++) {
        p_head = (struct pids_stack *)v_head;
        p_head->head = pids_itemize_stack((struct pids_result *)v_list, info->maxitems, info->items);
        p_blob->stacks[i] = p_head;
        v_list += list_size;
        v_head += head_size;
    }
    p_blob->ext_numstacks = maxstacks;
    return p_blob;
} // end: pids_stacks_alloc


static int pids_stacks_fetch (
        struct pids_info *info)
{
 #define n_alloc  info->fetch.n_alloc
 #define n_inuse  info->fetch.n_inuse
 #define n_saved  info->fetch.n_alloc_save
    struct stacks_extent *ext;

    // initialize stuff -----------------------------------
    if (!info->fetch.anchor) {
        if (!(info->fetch.anchor = calloc(STACKS_INIT, sizeof(void *))))
            return -1;
        if (!(ext = pids_stacks_alloc(info, STACKS_INIT)))
            return -1;       // here, errno was set to ENOMEM
        memcpy(info->fetch.anchor, ext->stacks, sizeof(void *) * STACKS_INIT);
        n_alloc = STACKS_INIT;
    }
    pids_toggle_history(info);
    memset(&info->fetch.counts, 0, sizeof(struct pids_counts));

    // iterate stuff --------------------------------------
    n_inuse = 0;
    while (info->read_something(info->fetch_PT, &info->fetch_proc)) {
        if (!(n_inuse < n_alloc)) {
            n_alloc += STACKS_GROW;
            if (!(info->fetch.anchor = realloc(info->fetch.anchor, sizeof(void *) * n_alloc))
            || (!(ext = pids_stacks_alloc(info, STACKS_GROW))))
                return -1;   // here, errno was set to ENOMEM
            memcpy(info->fetch.anchor + n_inuse, ext->stacks, sizeof(void *) * STACKS_GROW);
        }
        if (!pids_proc_tally(info, &info->fetch.counts, &info->fetch_proc))
            return -1;       // here, errno was set to ENOMEM
        if (!pids_assign_results(info, info->fetch.anchor[n_inuse++], &info->fetch_proc))
            return -1;       // here, errno was set to ENOMEM
    }
    /* while the possibility is extremely remote, the readproc.c (read_something) |
       simple_readproc and simple_readtask guys could have encountered this error |
       in which case they would have returned a NULL, thus ending our while loop. | */
    if (errno == ENOMEM)
        return -1;

    // finalize stuff -------------------------------------
    /* note: we go to this trouble of maintaining a duplicate of the consolidated |
             extent stacks addresses represented as our 'anchor' since these ptrs |
             are exposed to a user (um, not that we don't trust 'em or anything). |
             plus, we can NULL delimit these ptrs which we couldn't do otherwise. | */
    if (n_saved < n_inuse + 1) {
        n_saved = n_inuse + 1;
        if (!(info->fetch.results.stacks = realloc(info->fetch.results.stacks, sizeof(void *) * n_saved)))
            return -1;
    }
    memcpy(info->fetch.results.stacks, info->fetch.anchor, sizeof(void *) * n_inuse);
    info->fetch.results.stacks[n_inuse] = NULL;

    return n_inuse;     // callers beware, this might be zero !
 #undef n_alloc
 #undef n_inuse
 #undef n_saved
} // end: pids_stacks_fetch


// ___ Public Functions |||||||||||||||||||||||||||||||||||||||||||||||||||||||

// --- standard required functions --------------------------------------------

/*
 * procps_pids_new():
 *
 * @info: location of returned new structure
 *
 * Returns: < 0 on failure, 0 on success along with
 *          a pointer to a new context struct
 */
PROCPS_EXPORT int procps_pids_new (
        struct pids_info **info,
        enum pids_item *items,
        int numitems)
{
    struct pids_info *p;
    int pgsz;

#ifdef ITEMTABLE_DEBUG
    int i, failed = 0;
    for (i = 0; i < MAXTABLE(Item_table); i++) {
        if (i != Item_table[i].enumnumb) {
            fprintf(stderr, "%s: enum/table error: Item_table[%d] was %s, but its value is %d\n"
                , __FILE__, i, Item_table[i].enum2str, Item_table[i].enumnumb);
            failed = 1;
        }
    }
    if (PIDS_SELECT_PID != PROC_PID) {
        fprintf(stderr, "%s: header error: PIDS_SELECT_PID = 0x%04x, PROC_PID = 0x%04x\n"
            , __FILE__, PIDS_SELECT_PID, PROC_PID);
        failed = 1;
    }
    if (PIDS_SELECT_PID_THREADS != PIDS_SELECT_PID + 1) {
        fprintf(stderr, "%s: header error: PIDS_SELECT_PID_THREADS = 0x%04x, should be 0x%04x\n"
            , __FILE__, PIDS_SELECT_PID_THREADS, PIDS_SELECT_PID + 1);
        failed = 1;
    }
    if (PIDS_SELECT_UID != PROC_UID) {
        fprintf(stderr, "%s: header error: PIDS_SELECT_UID = 0x%04x, PROC_UID = 0x%04x\n"
            , __FILE__, PIDS_SELECT_UID, PROC_UID);
        failed = 1;
    }
    if (PIDS_SELECT_UID_THREADS != PIDS_SELECT_UID + 1) {
        fprintf(stderr, "%s: header error: PIDS_SELECT_UID_THREADS = 0x%04x, should be 0x%04x\n"
            , __FILE__, PIDS_SELECT_UID_THREADS, PIDS_SELECT_UID + 1);
        failed = 1;
    }
    // our select() function & select enumerators assume the following ...
    if (PIDS_FETCH_THREADS_TOO != 1) {
        fprintf(stderr, "%s: header error: PIDS_FETCH_THREADS_TOO = %d, should be 1\n"
            , __FILE__, PIDS_FETCH_THREADS_TOO);
        failed = 1;
    }
    if (failed) _Exit(EXIT_FAILURE);
#endif

    if (info == NULL || *info != NULL)
        return -EINVAL;
    if (!(p = calloc(1, sizeof(struct pids_info))))
        return -ENOMEM;

    /* if we're without items or numitems, a later call to
       procps_pids_reset() will become mandatory */
    if (items && numitems) {
        if (pids_items_check_failed(items, numitems)) {
            free(p);
            return -EINVAL;
        }
        // allow for our PIDS_logical_end
        p->maxitems = numitems + 1;
        if (!(p->items = calloc(p->maxitems, sizeof(enum pids_item)))) {
            free(p);
            return -ENOMEM;
        }
        memcpy(p->items, items, sizeof(enum pids_item) * numitems);
        p->items[numitems] = PIDS_logical_end;
        pids_libflags_set(p);
        if (!pids_prep_func_array(p))
            return -ENOMEM;
    }

    if (!(p->hist = calloc(1, sizeof(struct history_info)))
    || (!(p->hist->PHist_new = calloc(NEWOLD_INIT, sizeof(HST_t))))
    || (!(p->hist->PHist_sav = calloc(NEWOLD_INIT, sizeof(HST_t))))) {
        free(p->items);
        if (p->hist) {
            free(p->hist->PHist_sav);  // this & next might be NULL ...
            free(p->hist->PHist_new);
            free(p->hist);
        }
        free(p);
        return -ENOMEM;
    }
    p->hist->HHist_siz = NEWOLD_INIT;
    pids_config_history(p);

    pgsz = getpagesize();
    while (pgsz > 1024) { pgsz >>= 1; p->pgs2k_shift++; }
    p->hertz = procps_hertz_get();

    numa_init();

    p->fetch.results.counts = &p->fetch.counts;

    p->refcount = 1;
    *info = p;
    return 0;
} // end: procps_pids_new


PROCPS_EXPORT int procps_pids_ref (
        struct pids_info *info)
{
    if (info == NULL)
        return -EINVAL;

    info->refcount++;
    return info->refcount;
} // end: procps_pids_ref


PROCPS_EXPORT int procps_pids_unref (
        struct pids_info **info)
{
    if (info == NULL || *info == NULL)
        return -EINVAL;

    (*info)->refcount--;

    if ((*info)->refcount < 1) {
#ifdef UNREF_RPTHASH
        pids_unref_rpthash(*info);
#endif
        if ((*info)->extents) {
            pids_cleanup_stacks_all(*info);
            do {
                struct stacks_extent *p = (*info)->extents;
                (*info)->extents = (*info)->extents->next;
                free(p);
            } while ((*info)->extents);
        }
        if ((*info)->otherexts) {
            struct stacks_extent *nextext, *ext = (*info)->otherexts;
            while (ext) {
                nextext = ext->next;
                pids_cleanup_stack(ext->stacks[0]->head);
                free(ext);
                ext = nextext;
            };
        }
        if ((*info)->fetch.anchor)
            free((*info)->fetch.anchor);
        if ((*info)->fetch.results.stacks)
            free((*info)->fetch.results.stacks);

        if ((*info)->items)
            free((*info)->items);
        if ((*info)->hist) {
            free((*info)->hist->PHist_sav);
            free((*info)->hist->PHist_new);
            free((*info)->hist);
        }

        if ((*info)->get_ext)
           pids_oldproc_close(&(*info)->get_PT);

        if ((*info)->func_array)
            free((*info)->func_array);

        if ((*info)->select_ids)
            free((*info)->select_ids);

        numa_uninit();

        free(*info);
        *info = NULL;
        return 0;
    }
    return (*info)->refcount;
} // end: procps_pids_unref


// --- variable interface functions -------------------------------------------

PROCPS_EXPORT struct pids_stack *fatal_proc_unmounted (
        struct pids_info *info,
        int return_self)
{
    struct pids_fetch *fetched;
    unsigned tid;

    /* this is very likely the *only* newlib function where the
       context (pids_info) of NULL will ever be permitted */
    if (!look_up_our_self()
    || (!return_self))
        return NULL;

    tid = getpid();
    if (!(fetched = procps_pids_select(info, &tid, 1, PIDS_SELECT_PID)))
        return NULL;
    return fetched->stacks[0];
} // end: fatal_proc_unmounted


PROCPS_EXPORT struct pids_stack *procps_pids_get (
        struct pids_info *info,
        enum pids_fetch_type which)
{
    struct timespec ts;

    errno = EINVAL;
    if (info == NULL)
        return NULL;
    if (which != PIDS_FETCH_TASKS_ONLY && which != PIDS_FETCH_THREADS_TOO)
        return NULL;
    /* with items & numitems technically optional at 'new' time, it's
       expected 'reset' will have been called -- but just in case ... */
    if (!info->maxitems)
        return NULL;

    if (!info->get_ext) {
        if (!(info->get_ext = pids_stacks_alloc(info, 1)))
            return NULL;     // here, errno was overridden with ENOMEM
fresh_start:
        if (!pids_oldproc_open(&info->get_PT, info->oldflags))
            return NULL;     // here, errno was overridden with ENOMEM/others
        info->get_type = which;
        info->read_something = which ? readeither : readproc;
    }

    if (info->get_type != which) {
        pids_oldproc_close(&info->get_PT);
        goto fresh_start;
    }
    errno = 0;

    if (info->containers_yes)
        pids_containers_check();

    info->boot_tics = 0;
    if (0 >= clock_gettime(CLOCK_BOOTTIME, &ts))
        info->boot_tics = (ts.tv_sec + ts.tv_nsec * 1.0e-9) * info->hertz;

    if (NULL == info->read_something(info->get_PT, &info->get_proc))
        return NULL;
    if (!pids_assign_results(info, info->get_ext->stacks[0], &info->get_proc))
        return NULL;
    return info->get_ext->stacks[0];
} // end: procps_pids_get


/* procps_pids_reap():
 *
 * Harvest all the available tasks/threads and provide the result
 * stacks along with a summary of the information gathered.
 *
 * Returns: pointer to a pids_fetch struct on success, NULL on error.
 */
PROCPS_EXPORT struct pids_fetch *procps_pids_reap (
        struct pids_info *info,
        enum pids_fetch_type which)
{
    struct timespec ts;
    int rc;

    errno = EINVAL;
    if (info == NULL)
        return NULL;
    if (which != PIDS_FETCH_TASKS_ONLY && which != PIDS_FETCH_THREADS_TOO)
        return NULL;
    /* with items & numitems technically optional at 'new' time, it's
       expected 'reset' will have been called -- but just in case ... */
    if (!info->maxitems)
        return NULL;
    errno = 0;

    if (info->containers_yes)
        pids_containers_check();

    if (!pids_oldproc_open(&info->fetch_PT, info->oldflags))
        return NULL;
    info->read_something = which ? readeither : readproc;

    info->boot_tics = 0;
    if (0 >= clock_gettime(CLOCK_BOOTTIME, &ts))
        info->boot_tics = (ts.tv_sec + ts.tv_nsec * 1.0e-9) * info->hertz;

    rc = pids_stacks_fetch(info);

    pids_oldproc_close(&info->fetch_PT);
    // we better have found at least 1 pid
    return (rc > 0) ? &info->fetch.results : NULL;
} // end: procps_pids_reap


PROCPS_EXPORT int procps_pids_reset (
        struct pids_info *info,
        enum pids_item *newitems,
        int newnumitems)
{
    if (info == NULL || newitems == NULL)
        return -EINVAL;
    if (pids_items_check_failed(newitems, newnumitems))
        return -EINVAL;

    pids_cleanup_stacks_all(info);

    /* shame on this caller, they didn't change anything. and unless they have
       altered the depth of the stacks we're not gonna change anything either! */
    if (info->maxitems == newnumitems + 1
    && !memcmp(info->items, newitems, sizeof(enum pids_item) * newnumitems))
        return 0;

    if (info->maxitems < newnumitems + 1) {
        while (info->extents) {
            struct stacks_extent *p = info->extents;
            info->extents = p->next;
            free(p);
        };
        if (info->get_ext) {
           pids_oldproc_close(&info->get_PT);
           info->get_ext = NULL;
        }
        if (info->fetch.anchor) {
            free(info->fetch.anchor);
            info->fetch.anchor = NULL;
        }
        // allow for our PIDS_logical_end
        info->maxitems = newnumitems + 1;
        if (!(info->items = realloc(info->items, sizeof(enum pids_item) * info->maxitems)))
            return -ENOMEM;
    }

    memcpy(info->items, newitems, sizeof(enum pids_item) * newnumitems);
    info->items[newnumitems] = PIDS_logical_end;
    // account for above PIDS_logical_end
    info->maxitems = newnumitems + 1;

    // if extents were freed above, this next guy will have no effect
    // so we'll rely on pids_stacks_alloc() to itemize ...
    pids_itemize_stacks_all(info);
    pids_libflags_set(info);
    if (!pids_prep_func_array(info))
        return -ENOMEM;

    return 0;
} // end: procps_pids_reset


/* procps_pids_select():
 *
 * Harvest any processes matching the specified PID or UID and provide the
 * result stacks along with a summary of the information gathered.
 *
 * Returns: pointer to a pids_fetch struct on success, NULL on error.
 */
PROCPS_EXPORT struct pids_fetch *procps_pids_select (
        struct pids_info *info,
        unsigned *these,
        int numthese,
        enum pids_select_type which)
{
    struct timespec ts;
    int rc;

    errno = EINVAL;
    if (info == NULL || these == NULL)
        return NULL;
    if (numthese < 1)
        return NULL;
    if ((which != PIDS_SELECT_PID && which != PIDS_SELECT_UID)
    && ((which != PIDS_SELECT_PID_THREADS && which != PIDS_SELECT_UID_THREADS)))
        return NULL;
    /* with items & numitems technically optional at 'new' time, it's
       expected 'reset' will have been called -- but just in case ... */
    if (!info->maxitems)
        return NULL;
    errno = 0;

    if (info->containers_yes)
        pids_containers_check();

    // the zero delimiter is really only needed with PIDS_SELECT_PID
    if (!(info->select_ids = realloc(info->select_ids, sizeof(unsigned) * (numthese + 1))))
        return NULL;
    memcpy(info->select_ids, these, sizeof(unsigned) * numthese);
    info->select_ids[numthese] = 0;

    if (!pids_oldproc_open(&info->fetch_PT, (info->oldflags | which), info->select_ids, numthese))
        return NULL;
    info->read_something = (which & PIDS_FETCH_THREADS_TOO) ? readeither : readproc;

    info->boot_tics = 0;
    if (0 >= clock_gettime(CLOCK_BOOTTIME, &ts))
        info->boot_tics = (ts.tv_sec + ts.tv_nsec * 1.0e-9) * info->hertz;

    rc = pids_stacks_fetch(info);

    pids_oldproc_close(&info->fetch_PT);
    // no guarantee any pids/uids were found
    return (rc >= 0) ? &info->fetch.results : NULL;
} // end: procps_pids_select


/*
 * procps_pids_sort():
 *
 * Sort stacks anchored in the passed stack pointers array
 * based on the designated sort enumerator and specified order.
 *
 * Returns those same addresses sorted.
 *
 * Note: all of the stacks must be homogeneous (of equal length and content).
 */
PROCPS_EXPORT struct pids_stack **procps_pids_sort (
        struct pids_info *info,
        struct pids_stack *stacks[],
        int numstacked,
        enum pids_item sortitem,
        enum pids_sort_order order)
{
    struct sort_parms parms;
    struct pids_result *p;
    int offset;

    errno = EINVAL;
    if (info == NULL || stacks == NULL)
        return NULL;
    // a pids_item is currently unsigned, but we'll protect our future
    if (sortitem < 0  || sortitem >= PIDS_logical_end)
        return NULL;
    if (order != PIDS_SORT_ASCEND && order != PIDS_SORT_DESCEND)
        return NULL;
    if (numstacked < 2)
        return stacks;

    offset = 0;
    p = stacks[0]->head;
    for (;;) {
        if (p->item == sortitem)
            break;
        ++offset;
        if (offset >= info->maxitems)
            return NULL;
        if (p->item >= PIDS_logical_end)
            return NULL;
        ++p;
    }
    errno = 0;

    parms.offset = offset;
    parms.order = order;

    if (!mergesort_r(stacks, numstacked, (QSR_t)Item_table[p->item].sortfunc, &parms))
        return NULL;
    return stacks;
} // end: procps_pids_sort


// --- special debugging function(s) ------------------------------------------
/*
 *  The following isn't part of the normal programming interface.  Rather,
 *  it exists to validate result types referenced in application programs.
 *
 *  It's used only when:
 *      1) the 'XTRA_PROCPS_DEBUG' has been defined, or
 *      2) an #include of 'xtra-procps-debug.h' is used
 */

PROCPS_EXPORT struct pids_result *xtra_pids_val (
        int relative_enum,
        const char *typestr,
        const struct pids_stack *stack,
        const char *file,
        int lineno)
{
    char *str;
    int i;

    for (i = 0; stack->head[i].item < PIDS_logical_end; i++)
        ;
    if (relative_enum < 0 || relative_enum >= i) {
        fprintf(stderr, "%s line %d: invalid relative_enum = %d, valid range = 0-%d\n"
            , file, lineno, relative_enum, i-1);
        return NULL;
    }
    str = Item_table[stack->head[relative_enum].item].type2str;
    if (str[0]
    && (strcmp(typestr, str))) {
        fprintf(stderr, "%s line %d: was %s, expected %s\n", file, lineno, typestr, str);
    }
    return &stack->head[relative_enum];
} // end: xtra_pids_val