documentation: Update pids manual pages

Updated the full suite of manual pages for the procps_pids_*
functions. The only one missing is procps_pids_get which
may not be required.

10 files changed, 574 insertions, 216 deletions

diff --git a/Makefile.am b/Makefile.am
index bb0f4c5..2c4b8d6 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -60,6 +60,12 @@ dist_man_MANS = \
 	doc/libproc.3 \
 	doc/procps_linux_version.3 \
 	doc/procps_pids_new.3 \
+	doc/procps_pids_reap.3 \
+	doc/procps_pids_ref.3 \
+	doc/procps_pids_reset.3 \
+	doc/procps_pids_select.3 \
+	doc/procps_pids_sort.3 \
+	doc/procps_pids_unref.3 \
 	doc/procps_uptime.3 \
 	doc/procps_uptime_sprint.3 \
 	doc/procps_uptime_sprint_short.3
diff --git a/doc/libproc.3 b/doc/libproc.3
index 3e04626..5ced8df 100644
--- a/doc/libproc.3
+++ b/doc/libproc.3
@@ -1,5 +1,5 @@
 .\" t
-.\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
+.\" (C) Copyright 2016-2017 Craig Small <csmall@enc.com.au>
 .\"
 .\" %%%LICENSE_START(LGPL_2.1+)
 .\" This manual is free software; you can redistribute it and/or
@@ -17,7 +17,7 @@
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 .\" %%%LICENSE_END
 .\"
-.TH LIBPROC 3 2016-04-19 "libproc-2"
+.TH LIBPROC 3 2016-01-05 "libproc-2"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .SH NAME
@@ -33,6 +33,52 @@ Link with \fI\-lprocps\fR.
 This manual describes some of the anciallary information about the
 libproc library.
 
+.SS PID FETCH TYPE
+The enum \fIpids_fetch_type\fR is used by the functions \fBprocps_pids_get\fR
+and \fB procps_pids_reap\fR to determine if the only the process information
+should be collected or the thread information as well.
+.TS
+lB l l.
+PIDS_FETCH_TASKS_ONLY	Only collect task (process) information
+PIDS_FETCH_THREADS_TOO	Collect both task and thread information
+.TE
+
+.SS PIDS COUNT
+The \fBpids_count\fR structure shows some overall count of
+processes in various states. Note that if you use
+.BR procps_pids_select (3)
+then the counts are for the matching processes only.
+The structure is a series of integers and have the following
+members.
+
+The following information is found in the structure:
+.PP
+.in +4n
+.nf
+struct pids_counts {
+    int       total;          /* total number of processes */
+    int       running;        /* processes running in R state */
+    int       sleeping;       /* processes sleeping in S or D state */
+    int       stopped;        /* processes stopped in T state */
+    int       zombied;        /* zombie processes in Z state */
+};
+.fi
+.in
+
+.SS PIDS FETCH
+This is the structure returned by \fBprocps_pids_reap\fR(3) and
+\fBprocps_pids_select\fR(3) and contains a \fBPIDS STACK\fR and
+some count information.
+.PP
+.in +4n
+.nf
+struct pids_fetch {
+    struct pids_counts *counts;      /* Overall process counts */
+    struct pids_stack **stacks;      /* Detailed process information */
+};
+.fi
+.in
+
 .SS PID ITEMS
 The enum \fIpids_item\fR is used by the functions
 .BR procps_pids_new (3),
@@ -44,128 +90,149 @@ l l l
 ---
 lB l l.
 Item	Type	Description
-PROCPS_PIDS_ADDR_END_CODE	ul_int	The address below which program text can run
-PROCPS_PIDS_ADDR_KSTK_EIP	ul_int	Instruction pointer
-PROCPS_PIDS_ADDR_KSTK_ESP	ul_int	Stack pointer
-PROCPS_PIDS_ADDR_START_CODE	ul_int	The address above which program text can run
-PROCPS_PIDS_ADDR_START_STACK	ul_int	Address of the start (bottom) of the stack
-PROCPS_PIDS_ALARM	sl_int	??
-PROCPS_PIDS_CGNAME	str	The name of the control group for the process
-PROCPS_PIDS_CGROUP	str	List of control groups
-PROCPS_PIDS_CGROUP_V	strv	List of control groups
-PROCPS_PIDS_CMD	str	Command name (only the executable name)
-PROCPS_PIDS_CMDLINE	str	Full command line
-PROCPS_PIDS_CMDLINE_V	strv	Full command line
-PROCPS_PIDS_ENVIRON	str	The process environment
-PROCPS_PIDS_ENVIRON_V	strv	The process environment
-PROCPS_PIDS_EXIT_SIGNAL	s_int	Signal sent to parent when this process dies
-PROCPS_PIDS_FLAGS	ul_int	Process flags
-PROCPS_PIDS_FLT_MAJ	ul_int	Number of major page faults
-PROCPS_PIDS_FLT_MAJ_C	ul_int	Cumulative major page faults
-PROCPS_PIDS_FLT_MAJ_DELTA	ul_int	Number of major page faults since last fetch
-PROCPS_PIDS_FLT_MIN	ul_int	Number of minor page faults
-PROCPS_PIDS_FLT_MIN_C	ul_int	Culmative minor page faults
-PROCPS_PIDS_FLT_MIN_DELTA	ul_int	Number of minor page faults since last fetch
-PROCPS_PIDS_ID_EGID	u_int	Effective group ID number
-PROCPS_PIDS_ID_EGROUP	str	Effective group name
-PROCPS_PIDS_ID_EUID	u_int	Effective user ID number
-PROCPS_PIDS_ID_EUSER	str	Effective user name
-PROCPS_PIDS_ID_FGID	u_int	File system access group ID number
-PROCPS_PIDS_ID_FGROUP	str	File system access group name
-PROCPS_PIDS_ID_FUID	u_int	File system access user ID number
-PROCPS_PIDS_ID_FUSER	str	File system access user name
-PROCPS_PIDS_ID_PGRP	s_int	Process group ID, or process ID of group leader
-PROCPS_PIDS_ID_PID	s_int	Proccess ID number
-PROCPS_PIDS_ID_PPID	s_int	Process ID number of parent
-PROCPS_PIDS_ID_RGID	u_int	Real group ID number
-PROCPS_PIDS_ID_RGROUP	str	Real group name
-PROCPS_PIDS_ID_RUID	u_int	Real user ID number
-PROCPS_PIDS_ID_RUSER	str	Real user name
-PROCPS_PIDS_ID_SESSION	s_int	Session ID number, or process ID of session leader
-PROCPS_PIDS_ID_SGID	u_int	Saved group ID number
-PROCPS_PIDS_ID_SGROUP	str	Saved group name
-PROCPS_PIDS_ID_SUID	u_int	Saved user ID number
-PROCPS_PIDS_ID_SUSER	str	Saved user nameSaved user name
-PROCPS_PIDS_ID_TGID	s_int	Thread group ID number, or process ID of thread group leader
-PROCPS_PIDS_ID_TPGID	s_int	Process ID of foreground process group on the tty
-PROCPS_PIDS_LXCNAME	str	Linux container name
-PROCPS_PIDS_MEM_CODE	sl_int	??
-PROCPS_PIDS_MEM_CODE_KIB	ul_int	??
-PROCPS_PIDS_MEM_DATA	sl_int	??
-PROCPS_PIDS_MEM_DATA_KIB	ul_int	??
-PROCPS_PIDS_MEM_DT	sl_int	??
-PROCPS_PIDS_MEM_LRS	sl_int	??
-PROCPS_PIDS_MEM_RES	sl_int	Resident set size
-PROCPS_PIDS_MEM_RES_KIB	ul_int	Resident set size
-PROCPS_PIDS_MEM_SHR	sl_int	Shared memory
-PROCPS_PIDS_MEM_SHR_KIB	ul_int	Shared memory
-PROCPS_PIDS_MEM_VIRT	sl_int	Virtual memory
-PROCPS_PIDS_MEM_VIRT_KIB	ul_int	Virtual memory
-PROCPS_PIDS_NICE	sl_int	Nice value
-PROCPS_PIDS_NLWP	s_int	Number of lwps (threads) in the process
-PROCPS_PIDS_NS_IPC	ul_int	Current IPC namespace
-PROCPS_PIDS_NS_MNT	ul_int	Current mount namespace
-PROCPS_PIDS_NS_NET	ul_int	Current network namespace
-PROCPS_PIDS_NS_PID	ul_int	Current PID namespace
-PROCPS_PIDS_NS_USER	ul_int	Current user namespace
-PROCPS_PIDS_NS_UTS	ul_int	Current UTC namespace
-PROCPS_PIDS_OOM_ADJ	s_int	Out Of Memory Adjust
-PROCPS_PIDS_OOM_SCORE	s_int	Process Out Of Memory Score
-PROCPS_PIDS_PRIORITY	s_int	Kernel scheduling priority
-PROCPS_PIDS_PROCESSOR	u_int	Current CPU the process is running on
-PROCPS_PIDS_RSS		sl_int	Resident set size
-PROCPS_PIDS_RSS_RLIM	ul_int	Soft limit of RSS in bytes
-PROCPS_PIDS_RTPRIO	ul_int	Realtime priority
-PROCPS_PIDS_SCHED_CLASS	ul_int	Scheduling class, see \fBsched\fR(7)
-PROCPS_PIDS_SD_MACH	str	Systemd machine name
-PROCPS_PIDS_SD_OUID	str	Systemd owner user ID
-PROCPS_PIDS_SD_SEAT	str	Systemd seat
-PROCPS_PIDS_SD_SESS	str	Systemd session
-PROCPS_PIDS_SD_SLICE	str	Systemd slice
-PROCPS_PIDS_SD_UNIT	str	Systemd unit
-PROCPS_PIDS_SD_UUNIT	str	Systemd user unit
-PROCPS_PIDS_SIGBLOCKED	str	Bitmap of blocked signals
-PROCPS_PIDS_SIGCATCH	str	Bitmap of caught signals
-PROCPS_PIDS_SIGIGNORE	str	Bitmap of ignored signals
-PROCPS_PIDS_SIGNALS	str	Bitmap of pending signals
-PROCPS_PIDS_SIGPENDING	str	Bitmap of pending signals
-PROCPS_PIDS_STATE	s_ch	Process state codes
-PROCPS_PIDS_SUPGIDS	str	IDs of the supplementary groups
-PROCPS_PIDS_SUPGROUPS	str	Name of the supplementary groups
-PROCPS_PIDS_TICS_ALL	ull_int	Sum of user and system time
-PROCPS_PIDS_TICS_ALL_C	ull_int	Cumulative sum of user and system time
-PROCPS_PIDS_TICS_DELTA	u_int	Difference of sum of user and system time since last fetch
-PROCPS_PIDS_TICS_SYSTEM	ull_int	Amount of time process has been in system mode in ticks
-PROCPS_PIDS_TICS_SYSTEM_C	ull_int	??
-PROCPS_PIDS_TICS_USER	ull_int	Amount of time process has been scheduled in user mode in ticks
-PROCPS_PIDS_TICS_USER_C	ull_int	??
-PROCPS_PIDS_TIME_ALL	ull_int	??
-PROCPS_PIDS_TIME_ELAPSED	ull_int	Total seconds since process started
-PROCPS_PIDS_TIME_START	ull_int	Time the process started
-PROCPS_PIDS_TTY	s_int	Controlling terminal ID number
-PROCPS_PIDS_TTY_NAME	str	Controlling terminal name
-PROCPS_PIDS_TTY_NUMBER	str	Controlling terminal number
-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	??
-PROCPS_PIDS_VM_RSS_LOCKED	ul_int	??
-PROCPS_PIDS_VM_RSS_SHARED	ul_int	??
-PROCPS_PIDS_VM_SIZE	ul_int	??
-PROCPS_PIDS_VM_STACK	ul_int	??
-PROCPS_PIDS_VM_SWAP	ul_int	??
-PROCPS_PIDS_VM_USED	ul_int	??
-PROCPS_PIDS_VSIZE_PGS	ul_int	??
-PROCPS_PIDS_WCHAN_ADDR	ul_int	Address of the kernel function in which the process is sleeping.
-PROCPS_PIDS_WCHAN_NAME	str	Name of the kernel function in which the process is sleeping.
+PIDS_ADDR_END_CODE	ul_int	The address below which program text can run
+PIDS_ADDR_KSTK_EIP	ul_int	Instruction pointer
+PIDS_ADDR_KSTK_ESP	ul_int	Stack pointer
+PIDS_ADDR_START_CODE	ul_int	The address above which program text can run
+PIDS_ADDR_START_STACK	ul_int	Address of the start (bottom) of the stack
+PIDS_ALARM	sl_int	??
+PIDS_CGNAME	str	The name of the control group for the process
+PIDS_CGROUP	str	List of control groups
+PIDS_CGROUP_V	strv	List of control groups
+PIDS_CMD	str	Command name (only the executable name)
+PIDS_CMDLINE	str	Full command line
+PIDS_CMDLINE_V	strv	Full command line
+PIDS_ENVIRON	str	The process environment
+PIDS_ENVIRON_V	strv	The process environment
+PIDS_EXIT_SIGNAL	s_int	Signal sent to parent when this process dies
+PIDS_FLAGS	ul_int	Process flags
+PIDS_FLT_MAJ	ul_int	Number of major page faults
+PIDS_FLT_MAJ_C	ul_int	Cumulative major page faults
+PIDS_FLT_MAJ_DELTA	ul_int	Number of major page faults since last fetch
+PIDS_FLT_MIN	ul_int	Number of minor page faults
+PIDS_FLT_MIN_C	ul_int	Culmative minor page faults
+PIDS_FLT_MIN_DELTA	ul_int	Number of minor page faults since last fetch
+PIDS_ID_EGID	u_int	Effective group ID number
+PIDS_ID_EGROUP	str	Effective group name
+PIDS_ID_EUID	u_int	Effective user ID number
+PIDS_ID_EUSER	str	Effective user name
+PIDS_ID_FGID	u_int	File system access group ID number
+PIDS_ID_FGROUP	str	File system access group name
+PIDS_ID_FUID	u_int	File system access user ID number
+PIDS_ID_FUSER	str	File system access user name
+PIDS_ID_PGRP	s_int	Process group ID, or process ID of group leader
+PIDS_ID_PID	s_int	Proccess ID number
+PIDS_ID_PPID	s_int	Process ID number of parent
+PIDS_ID_RGID	u_int	Real group ID number
+PIDS_ID_RGROUP	str	Real group name
+PIDS_ID_RUID	u_int	Real user ID number
+PIDS_ID_RUSER	str	Real user name
+PIDS_ID_SESSION	s_int	Session ID number, or process ID of session leader
+PIDS_ID_SGID	u_int	Saved group ID number
+PIDS_ID_SGROUP	str	Saved group name
+PIDS_ID_SUID	u_int	Saved user ID number
+PIDS_ID_SUSER	str	Saved user nameSaved user name
+PIDS_ID_TGID	s_int	Thread group ID number, or process ID of thread group leader
+PIDS_ID_TPGID	s_int	Process ID of foreground process group on the tty
+PIDS_LXCNAME	str	Linux container name
+PIDS_MEM_CODE	sl_int	Memory size for code, measured in KiB
+PIDS_MEM_CODE_PGS	ul_int	Memory size for code, measured in pages
+PIDS_MEM_DATA	sl_int	Memory size for data + stack, measued in KiB
+PIDS_MEM_DATA_PGS	ul_int	Memory size for data + stack, measured in pages
+PIDS_MEM_RES	sl_int	Resident set size, measured in KiB
+PIDS_MEM_RES_PGS	ul_int	Resident set size, measured in pages
+PIDS_MEM_SHR	sl_int	Shared memory, measured in KiB
+PIDS_MEM_SHR_PGS	ul_int	Shared memory, measured in pages
+PIDS_MEM_VIRT	sl_int	Virtual memory, measured in KiB
+PIDS_MEM_VIRT_PGS	ul_int	Virtual memory, measured in pages
+PIDS_NICE	sl_int	Nice value
+PIDS_NLWP	s_int	Number of lwps (threads) in the process
+PIDS_NS_IPC	ul_int	Current IPC namespace
+PIDS_NS_MNT	ul_int	Current mount namespace
+PIDS_NS_NET	ul_int	Current network namespace
+PIDS_NS_PID	ul_int	Current PID namespace
+PIDS_NS_USER	ul_int	Current user namespace
+PIDS_NS_UTS	ul_int	Current UTC namespace
+PIDS_OOM_ADJ	s_int	Out Of Memory Adjust
+PIDS_OOM_SCORE	s_int	Process Out Of Memory Score
+PIDS_PRIORITY	s_int	Kernel scheduling priority
+PIDS_PROCESSOR	u_int	Current CPU the process is running on
+PIDS_RSS	ul_int	Resident set size
+PIDS_RSS_RLIM	ul_int	Soft limit of RSS in bytes
+PIDS_RTPRIO	s_int	Realtime priority
+PIDS_SCHED_CLASS	s_int	Scheduling class, see \fBsched\fR(7)
+PIDS_SD_MACH	str	Systemd machine name
+PIDS_SD_OUID	str	Systemd owner user ID
+PIDS_SD_SEAT	str	Systemd seat
+PIDS_SD_SESS	str	Systemd session
+PIDS_SD_SLICE	str	Systemd slice
+PIDS_SD_UNIT	str	Systemd unit
+PIDS_SD_UUNIT	str	Systemd user unit
+PIDS_SIGBLOCKED	str	Bitmap of blocked signals
+PIDS_SIGCATCH	str	Bitmap of caught signals
+PIDS_SIGIGNORE	str	Bitmap of ignored signals
+PIDS_SIGNALS	str	Bitmap of pending signals
+PIDS_SIGPENDING	str	Bitmap of pending signals
+PIDS_STATE	s_ch	Process state codes
+PIDS_SUPGIDS	str	IDs of the supplementary groups
+PIDS_SUPGROUPS	str	Name of the supplementary groups
+PIDS_TICS_ALL	ull_int	Sum of user and system time
+PIDS_TICS_ALL_C	ull_int	Cumulative sum of user and system time
+PIDS_TICS_ALL_DELTA	s_int	Difference of sum of user and system time since last fetch
+PIDS_TICKS_BLKIO	s_int	Aggregated block I/O delays
+PIDS_TICS_GUEST	ull_int	Amount of time process has been in guest mode in ticks
+PIDS_TICS_GUEST_C	ull_int	Guest time of the process's children
+PIDS_TICS_SYSTEM	ull_int	Amount of time process has been in system mode in ticks
+PIDS_TICS_SYSTEM_C	ull_int	System time of the process's children
+PIDS_TICS_USER	ull_int	Amount of time process has been scheduled in user mode in ticks
+PIDS_TICS_USER_C	ull_int	??
+PIDS_TIME_ALL	ull_int	??
+PIDS_TIME_ELAPSED	ull_int	Total seconds since process started
+PIDS_TIME_START	ull_int	Time the process started
+PIDS_TTY	s_int	Controlling terminal ID number
+PIDS_TTY_NAME	str	Controlling terminal name
+PIDS_TTY_NUMBER	str	Controlling terminal number
+PIDS_VM_DATA	ul_int	Size of data segment
+PIDS_VM_EXE	ul_int	Size of text segment
+PIDS_VM_LIB	ul_int	Shared library code size
+PIDS_VM_LOCK	ul_int	Locked memory size, see \fBmlock\fR(3)
+PIDS_VM_RSS	ul_int	Resident set size
+PIDS_VM_RSS_ANON	ul_int	Resident anonymous memory
+PIDS_VM_RSS_FILE	ul_int	Resident file mappings
+PIDS_VM_RSS_LOCKED	ul_int	Locked memory size
+PIDS_VM_RSS_SHARED	ul_int	Resident shared memory
+PIDS_VM_SIZE	ul_int	Virtual memory size
+PIDS_VM_STACK	ul_int	Size of stack segment
+PIDS_VM_SWAP	ul_int	Swapped out virtual memory size by anonymous pages
+PIDS_VM_USED	ul_int	Used memory, sum of PIDS_VM_SWAP and PIDS_VM_RSS
+PIDS_VSIZE_PGS	ul_int	Virtual memory size, measured in pages
+PIDS_WCHAN_NAME	str	Name of the kernel function in which the process is sleeping.
 .TE
 
 .SS PIDS STACK
 The structure \fIstruct pids_stack\fR is a stack or list of information
-about a particular process. To extract the values out of the stack, the
+about a particular process found in another structure \fIpids_result\fR.
+
+The \fIpids_result\fR structure containts the following information:
+.PP
+.in +4n
+.nf
+struct pids_result {
+    enum pids_item item;
+    union {
+        signed char         s_ch;
+        signed int          s_int;
+        unsigned int        u_int;
+        unsigned long       ul_int;
+        unsigned long long  ull_int;
+        char               *str;
+        char              **strv;
+    } result;
+};
+.fi
+.in
+
+To extract the values out of the stack, the
 macro \fBPROCPS_PIDS_VAL\fR is used the following way
 .PP
 .RI \fBPROCPS_PIDS_VAL\fR( index , type , stack )
@@ -176,11 +243,14 @@ is the index of the \fIitems\fR defined with the function
 .BR procps_pids_new (3)
 .TP
 .I type
-is one of the \fIitem_types\fR(see below)
+type for returned value, see type column in \fBPID ITEMS\fR table.
 .TP
 .I stack
-is the stack returned by \fBprocps_pids_read_next()\fR.
+is the stack returned by \fBprocps_pids_get()\fR. It is also can be
+accessed from the \fIpids_fetch\fR structure which is returned by
+\fBprocps_pids_reap\fR.
 .SH SEE ALSO
+.BR mlock (3),
 .BR proc (5),
 .BR sched (7),
 .BR user_namespaces (7).
diff --git a/doc/procps_pids_new.3 b/doc/procps_pids_new.3
index c2ffe10..4c811c5 100644
--- a/doc/procps_pids_new.3
+++ b/doc/procps_pids_new.3
@@ -1,4 +1,4 @@
-.\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
+.\" (C) Copyright 2016-2017 Craig Small <csmall@enc.com.au>
 .\"
 .\" %%%LICENSE_START(LGPL_2.1+)
 .\" This manual is free software; you can redistribute it and/or
@@ -16,7 +16,7 @@
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 .\" %%%LICENSE_END
 .\"
-.TH PROCPS_PIDS_NEW 3 2016-04-18 "libproc-2"
+.TH PROCPS_PIDS_NEW 3 2017-01-05 "libproc-2"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .SH NAME
@@ -25,21 +25,23 @@ Create a PID information structure
 .SH SYNOPSIS
 .B #include <proc/procps.h>
 .sp
-.BI "int procps_pids_new(struct procps_pidsinfo **" info ", int " maxitems ", enum pids_item *" items ");"
+.BI "int procps_pids_new(struct pids_info **" info ", enum pids_item *" items ", int " numitems ");"
 .sp
 Link with \fI\-lprocps\fP.
 
 .SH DESCRIPTION
 .BR procps_pids_new ()
 creates a new PID information structure that be used in subsequent calls to
-.BR procps_pids_read_open (3),
+.BR procps_pids_get (3),
+.BR procps_pids_reap (3),
 .BR procps_pids_reset (3),
+.BR procps_pids_select (3),
 .BR procps_pids_sort (3).
 functions. The pointer to \fIinfo\fR will have memory allocated and a structure
 created.
 
-\fIitems\fR is an array of enums up to \fImaxitems\fR long that selects what
-information about the processed will be stored. \fImaxitems\fR is used to
+\fIitems\fR is an array of enums up to \fInumitems\fR long that selects what
+information about the processed will be stored. \fInumitems\fR is used to
 allocate memory and must be at least the length of \fIitems\fR but can be more.
 For information about what \fIitems\fR can contain, see the \fBPID ITEMS\fR
 section in
@@ -65,8 +67,9 @@ first appeared in libproc-2 version 0.0.
 
 .SH SEE ALSO
 .BR libproc (3),
-.BR procps_pids_read_open (3),
+.BR procps_pids_reap (3),
 .BR procps_pids_reset (3),
+.BR procps_pids_select (3),
 .BR procps_pids_sort (3),
 .BR procps_pids_unref (3),
 .BR proc (5).
diff --git a/doc/procps_pids_read_open.3 b/doc/procps_pids_read_open.3
deleted file mode 100644
index 376dda2..0000000
--- a/doc/procps_pids_read_open.3
+++ /dev/null
@@ -1,87 +0,0 @@
-.\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
-.\"
-.\" %%%LICENSE_START(LGPL_2.1+)
-.\" 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.
-.\"
-.\" This manual 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
-.\" %%%LICENSE_END
-.\"
-.TH PROCPS_PIDS_READ_OPEN 3 2016-04-19 "libproc-2"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.SH NAME
-procps_pids_read_open, procps_pids_read_next \-
-Load and iterate the PIDs information structure.
-.SH SYNOPSIS
-.B #include <proc/procps.h>
-.sp
-.BI "int procps_pids_read_open(struct procps_pidsinfo *" info ", enum pids_reap_type " which ");"
-.sp
-.BI "int procps_pids_read_next(struct procps_pidsinfo *" info ");"
-.sp
-.BI "int procps_pids_read_shut(struct procps_pidsinfo *" info ");"
-.sp
-Link with \fI\-lprocps\fP.
-
-.SH DESCRIPTION
-This trio of functions is one method of reading and iterating through the
-procps PIDS information. The info structure first needs to be initialised by
-.BR procps_pids_new (3).
-
-\fBprocps_pids_read_open()\fR is the function that will load the various
-files in the
-.BR proc (5)
-filesystem and fill the \fIinfo\fR structure with the parsed values.
-The function is able to parse only processes or also include threads, the
-option \fIwhich\fR can be set to \fBPROCPS_REAP_TASKS_ONLY\fR or
-\fBPROCPS_REAP_THREADS_TOO\fR to determine what is collected.
-
-Assuming that \fBprocps_pids_read_open()\fR returns successfully, a program can
-then iterate through a loop using \fBprocps_pids_read_next()\fR
-and using the accessor methods described in
-.BR libproc (3).
-
-One the loop has been completed or the information is no longer
-required, the function \fBprocps_pids_read_shut()\fR is used to
-free the information filled by \fBprocps_pids_read_open\fR.
-Note, the \fIinfo\fR structure is still allocated and requires
-.BR procps_pids_unref (3)
-to free \fIinfo\fR entirely.
-
-.SH RETURN VALUE
-\fBprocps_pids_read_open()\fR and \fBprocps_pids_read_shut()\fR returns 0
-on success and one of the negative values below on failure.
-.PP
-\fBprocps_pids_read_next()\fR returns a pointer to struct pids_stack for
-the next process on success and NULL on failure.
-.TP
-.B -EINVAL
-One of the given parameters is incorrect.
-.TP
-.B -ENOMEM
-Unable to allocate memory for the structure.
-.B -1
-Unable to parse the
-.BR proc (5)
-filesystem.
-
-.SH VERSIONS
-\fBprocps_pids_read_open()\fR, \fBprocps_pids_read_next()\fR and
-\fBprocps_pids_read_shut()\fR
-first appeared in libproc-2 version 0.0.
-
-.SH SEE ALSO
-.BR libproc (3),
-.BR procps_pids_new (3),
-.BR procps_pids_unref (3),
-.BR proc (5).
diff --git a/doc/procps_pids_reap.3 b/doc/procps_pids_reap.3
new file mode 100644
index 0000000..cab3aca
--- /dev/null
+++ b/doc/procps_pids_reap.3
@@ -0,0 +1,58 @@
+.\" (C) Copyright 2016-2017 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" 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.
+.\"
+.\" This manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_PIDS_REAP 3 2017-01-05 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_pids_reap \- Harvest all the PIDS information structure.
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.BI "struct pids_fetch  * procps_pids_reap(struct pids_info *" info ", enum pids_fetch_type " which ");"
+.sp
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+\fBprocps_pids_reap()\fR is the function that will load the various
+files in the
+.BR proc (5)
+filesystem and fill the returned structure with the parsed values as
+well as a summary of the information gathered.
+The function is able to parse only processes or also include threads, the
+option \fIwhich\fR can be set to \fBPIDS_FETCH_TASKS_ONLY\fR or
+\fBPIDS_FETCH_THREADS_TOO\fR to determine what is collected.
+
+The info structure first needs to be initialised by
+.BR procps_pids_new (3).
+if \fBprocps_pids_reap()\fR returns successfully, a program can
+then iterate through a loop using the accessor methods described in
+.BR libproc (3).
+
+.SH RETURN VALUE
+\fBprocps_pids_reap()\fR returns a pointer to struct pids_fetch
+on success and NULL on failure.
+
+.SH VERSIONS
+\fBprocps_pids_reap()\fR first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR libproc (3),
+.BR procps_pids_new (3),
+.BR procps_pids_unref (3),
+.BR proc (5).
diff --git a/doc/procps_pids_ref.3 b/doc/procps_pids_ref.3
new file mode 100644
index 0000000..01fdddd
--- /dev/null
+++ b/doc/procps_pids_ref.3
@@ -0,0 +1,56 @@
+.\" (C) Copyright 2017 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" 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.
+.\"
+.\" This manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_PIDS_REF 3 2017-01-05 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_pids_ref \-
+Increment reference count for pids structure.
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.BI "int procps_pids_ref(struct pids_info *" info ");"
+.sp
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+.BR procps_pids_ref ()
+Will increment the reference count for the \fBpids_info\fR structure that was
+created with
+.BR procps_pids_new (3).
+The reference count is used by
+.BR procps_pids_unref (3)
+to determine when to de-allocate memort used by this structure.
+
+.SH RETURN VALUE
+The function returns the updated reference count on success
+and one of negative values below on failure.
+.TP
+.B -EINVAL
+One of the given parameters is incorrect.
+
+.SH VERSIONS
+.B procps_pids_ref()
+first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR libproc (3),
+.BR procps_pids_new (3),
+.BR procps_pids_unref (3),
+.BR proc (5).
diff --git a/doc/procps_pids_reset.3 b/doc/procps_pids_reset.3
new file mode 100644
index 0000000..7e77c26
--- /dev/null
+++ b/doc/procps_pids_reset.3
@@ -0,0 +1,70 @@
+.\" (C) Copyright 2017 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" 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.
+.\"
+.\" This manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_PIDS_reset 3 2017-01-05 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_pids_reset \-
+Change what information is collected for a process
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.BI "int procps_pids_reset(struct pids_info **" info ", enum pids_item *" items ", int " numitems ");"
+.sp
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+During the initial call to \fBprocps_pids_new\fR(3), the information structure
+is allocated and the information items are specified.
+\fBprocps_pids_reset\fR allows you to change what items for a process are collected
+without having to unreference and create a new \fIpids_info\fR structure.
+
+The changed  PID information structure can then be used in subsequent calls to
+.BR procps_pids_get (3),
+.BR procps_pids_reap (3),
+.BR procps_pids_reset (3),
+.BR procps_pids_select (3),
+.BR procps_pids_sort (3)
+or even to further calls to \fBprocps_pids_reset\fR itself.
+
+The \fIitems\fR and \fInumitems\fR parameters are identical to the parameters
+used in \fBprocps_pids_new\fR.
+
+.SH RETURN VALUE
+The function returns 0 on success and one of negative values below
+on failure.
+.TP
+.B -EINVAL
+One of the given parameters is incorrect.
+.TP
+.B -ENOMEM
+Unable to allocate memory for the changed structure.
+
+.SH VERSIONS
+.B procps_pids_reset()
+first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR libproc (3),
+.BR procps_pids_new (3),
+.BR procps_pids_reap (3),
+.BR procps_pids_select (3),
+.BR procps_pids_sort (3),
+.BR procps_pids_unref (3),
+.BR proc (5).
diff --git a/doc/procps_pids_select.3 b/doc/procps_pids_select.3
new file mode 100644
index 0000000..642e158
--- /dev/null
+++ b/doc/procps_pids_select.3
@@ -0,0 +1,65 @@
+.\" (C) Copyright 2017 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" 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.
+.\"
+.\" This manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_PIDS_select 3 2017-01-05 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_pids_select \- Harvest process information that matches PID or UID
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.BI "struct pids_fetch  * procps_pids_select(struct pids_info *" info ", unsigned *" these ", int "numthese ", enum pids_select_type " which ");"
+.sp
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+\fBprocps_pids_select()\fR provides the same functionality as
+\fBprocps_pids_reap()\fR except it will only fetch information for the
+processes that have the process ID (PID) or User ID (UID) found in the
+array \fIthese\fR.
+
+\fIthese\fR is an array of process IDs (PIDs) or User IDs that the
+function will use to match against.
+
+\fInumthese\fR the length of the \fIthese\fR array.
+
+The \fIwhich\fR parameter tells the funtion what type of information is
+contained in \fIthese\fR and can be either \fBPIDS_SELECT_PID\fR if
+\fIthese\fR is an array of PIDs or \fBPIDS_SELECT_UID\fR if \fIthese\fR
+is an array of UIDs.
+
+The info structure first needs to be initialised by
+.BR procps_pids_new (3).
+if \fBprocps_pids_select()\fR returns successfully, a program can
+then iterate through a loop using the accessor methods described in
+.BR libproc (3).
+
+.SH RETURN VALUE
+\fBprocps_pids_select()\fR returns a pointer to struct pids_fetch
+on success and NULL on failure.
+
+.SH VERSIONS
+\fBprocps_pids_select()\fR first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR libproc (3),
+.BR procps_pids_new (3),
+.BR procps_pids_reap (3),
+.BR procps_pids_unref (3),
+.BR proc (5).
diff --git a/doc/procps_pids_sort.3 b/doc/procps_pids_sort.3
new file mode 100644
index 0000000..3cce1d8
--- /dev/null
+++ b/doc/procps_pids_sort.3
@@ -0,0 +1,59 @@
+.\" (C) Copyright 2017 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" 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.
+.\"
+.\" This manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_PIDS_SORT 3 2017-01-05 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_pids_sort \-
+Sort process information
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.BI "pids_stack **procps_pids_sort(struct pids_info *" info ", struct pids_stack *" stacks "[], int " numstacked ", enum pids_item " sortitem ", enum pids_sort_order " order ");"
+
+.sp
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+\fBprocps_pids_sort\fR sorts the given \fIstacks\fR stack of process
+information and sorts it by the given \fIsortitem\fR. \fInumstacked\fR
+must be the length of the \fIstacks\fR array and all the stacks in the
+list must be homogenous (of equal length and content).
+
+The stacks value can be obtained by a previous call of
+.BR procps_pids_reap (3)
+or
+.BR procps_pids_select (3)
+and then accessing the \fIstacks\fR member from that structure.
+
+\fIorder\fR can be either PIDS_SORT_ASCEND or PIDS_SORT_DESCEND.
+
+.SH RETURN VALUE
+The function returns the sorted stack on success or NULL on failure.
+
+.SH VERSIONS
+.B procps_pids_sort()
+first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR libproc (3),
+.BR procps_pids_new (3),
+.BR procps_pids_reap (3),
+.BR procps_pids_select (3),
+.BR proc (5).
diff --git a/doc/procps_pids_unref.3 b/doc/procps_pids_unref.3
new file mode 100644
index 0000000..2839f32
--- /dev/null
+++ b/doc/procps_pids_unref.3
@@ -0,0 +1,58 @@
+.\" (C) Copyright 2017 Craig Small <csmall@enc.com.au>
+.\"
+.\" %%%LICENSE_START(LGPL_2.1+)
+.\" 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.
+.\"
+.\" This manual 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
+.\" %%%LICENSE_END
+.\"
+.TH PROCPS_PIDS_UREF 3 2017-01-05 "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.SH NAME
+procps_pids_refg \-
+Clear memory of pids structure, if no longer used
+.SH SYNOPSIS
+.B #include <proc/procps.h>
+.sp
+.BI "int procps_pids_refg(struct pids_info **" info ");"
+.sp
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+.BR procps_pids_refg ()
+will note that one less reference is used for the specified structure. If
+this was the last reference, the function returns the memory for the
+PID information structure that was created with
+.BR procps_pids_new (3).
+
+.SH RETURN VALUE
+The function returns 0 if the structure was freed or a positive
+integer of the current references if there were others. It will
+return one of negative values below on failure.
+.TP
+.B -EINVAL
+One of the given parameters is incorrect.
+
+.SH VERSIONS
+.B procps_pids_refg()
+first appeared in libproc-2 version 0.0.
+
+.SH SEE ALSO
+.BR libproc (3),
+.BR procps_pids_new (3),
+.BR procps_pids_reap (3),
+.BR procps_pids_reset (3),
+.BR procps_pids_select (3),
+.BR procps_pids_sort (3),
+.BR proc (5).