docs: Additional flags in man pages

More PIDS defintions

2 files changed, 229 insertions, 279 deletions

diff --git a/doc/libproc.3 b/doc/libproc.3
index d325c97..3e04626 100644
--- a/doc/libproc.3
+++ b/doc/libproc.3
@@ -1,3 +1,4 @@
+.\" t
 .\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
 .\"
 .\" %%%LICENSE_START(LGPL_2.1+)
@@ -16,7 +17,7 @@
 .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 .\" %%%LICENSE_END
 .\"
-.TH LIBPROC 3 2016-04-18 "libproc-2"
+.TH LIBPROC 3 2016-04-19 "libproc-2"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .SH NAME
@@ -38,285 +39,147 @@ The enum \fIpids_item\fR is used by the functions
 .BR procps_pids_reset "(3) and"
 .BR procps_pids_sort (3).
 The following items can be fetched for a process:
-.TP
-.B PROCPS_PIDS_ADDR_END_CODE
-?
-.TP
-.B PROCPS_PIDS_ADDR_KSTK_EIP
-Instruction pointer.
-.TP
-.B PROCPS_PIDS_ADDR_KSTK_ESP
-Stack pointer.
-.TP
-.B PROCPS_PIDS_ADDR_START_CODE
-?
-.TP
-.B PROCPS_PIDS_ADDR_START_STACK
-Address of the start (bottom) of the stack.
-.TP
-.B PROCPS_PIDS_ALARM
-?
-.TP
-.B PROCPS_PIDS_CGNAME
-The name of the control group for the process.
-.TP
-.B PROCPS_PIDS_CGROUP, PROCPS_PIDS_CGROUP_V
-List of control groups the process belongs to as a string or string vector.
-.TP
-.B PROCPS_PIDS_CMD
-Command name (only the executable name).
-.TP
-.B PROCPS_PIDS_CMDLINE, PROCPS_PIDS_CMDLINE_V
-Full command line as a string or string vector.
-.TP
-.B PROCPS_PIDS_ENVIRON, PROCPS_PIDS_ENVIRON_V
-The processes environment as a string or string vector.
-.TP
-.B PROCPS_PIDS_EXIT_SIGNAL
-?
-.TP
-.B PROCPS_PIDS_FLAGS
-Process flags.
-.TP
-.B PROCPS_PIDS_FLT_MAJ
-Number of major page faults.
-.TP
-.B PROCPS_PIDS_FLT_MAJ_C
-Cumulative major page faults.
-.TP
-.B PROCPS_PIDS_FLT_MAJ_DELTA
-Number of major page faults since last fetch.
-.TP
-.B PROCPS_PIDS_FLT_MIN
-Number of minor page faults.
-.TP
-.B PROCPS_PIDS_FLT_MIN_C
-Culmative minor page faults.
-.TP
-.B PROCPS_PIDS_FLT_MIN_DELTA
-Number of minor page faults since last fetch.
-.TP
-.B PROCPS_PIDS_ID_EGID, PROCPS_PIDS_ID_EGROUP
-Effective group as a ID number or name.
-.TP
-.B PROCPS_PIDS_ID_EUID, PROCPS_PIDS_ID_EUSER
-Effective user ID number or name.
-.TP
-.B PROCPS_PIDS_ID_FGID, PROCPS_PIDS_ID_FGROUP
-File system access group ID number or name.
-.TP
-.B PROCPS_PIDS_ID_FUID, PROCPS_PIDS_ID_FUSER
-File sytem access user ID number or name.
-.TP
-.B PROCPS_PIDS_ID_PGRP
-Process group ID, or process ID of group leader.
-.TP
-.B PROCPS_PIDS_ID_PID
-Proccess ID number.
-.TP
-.B PROCPS_PIDS_ID_PPID
-Process ID number of parent.
-.TP
-.B PROCPS_PIDS_ID_RGID, PROCPS_PIDS_ID_RGROUP
-Real group ID number or name.
-.TP
-.B PROCPS_PIDS_ID_RUID, PROCPS_PIDS_ID_RUSER
-Real user ID number or name.
-.TP
-.B PROCPS_PIDS_ID_SESSION
-Session ID number, or process ID of session leader.
-.TP
-.B PROCPS_PIDS_ID_SGID, PROCPS_PIDS_ID_SGROUP
-Saved group ID number or name.
-.TP
-.B PROCPS_PIDS_ID_SUID, PROCPS_PIDS_ID_SUSER
-Saved user ID number or name.
-.TP
-.B PROCPS_PIDS_ID_TGID
-Thread group ID number, or process ID of thread group leader.
-.TP
-.B PROCPS_PIDS_ID_TPGID
-Process ID of foreground process group on the tty.
-.TP
-.B PROCPS_PIDS_LXCNAME
-Linux container name.
-.TP
-.B PROCPS_PIDS_MEM_CODE
-?
-.TP
-.B PROCPS_PIDS_MEM_CODE_KIB
-?
-.TP
-.B PROCPS_PIDS_MEM_DATA
-?
-.TP
-.B PROCPS_PIDS_MEM_DATA_KIB
-?
-.TP
-.B PROCPS_PIDS_MEM_DT
-?
-.TP
-.B PROCPS_PIDS_MEM_LRS
-?
-.TP
-.B PROCPS_PIDS_MEM_RES
-Resident set size
-.TP
-.B PROCPS_PIDS_MEM_RES_KIB
-Resident set size
-.TP
-.B PROCPS_PIDS_MEM_SHR
-Shared memory
-.TP
-.B PROCPS_PIDS_MEM_SHR_KIB
-Shared memory
-.TP
-.B PROCPS_PIDS_MEM_VIRT
-Virtual memory.
-.TP
-.B PROCPS_PIDS_MEM_VIRT_KIB
-Virtual memory.
-.TP
-.B PROCPS_PIDS_NICE
-Nice value.
-.TP
-.B PROCPS_PIDS_NLWP
-Number of lwps (threads) in the process.
-.TP
-.B PROCPS_PIDS_NS_IPC, PROCPS_PIDS_NS_MNT, PROCPS_PIDS_NS_NET, PROCPS_PIDS_NS_PID, PROCPS_PIDS_NS_USER, PROCPS_PIDS_NS_UTS
-IDs of the current namespaces for IPC, mount, network, PID, user or UTS.
-See 
-.B user_namespaces (7)
-for further information on these items.
-.TP
-.B PROCPS_PIDS_OOM_ADJ
-?
-.TP
-.B PROCPS_PIDS_OOM_SCORE
-?
-.TP
-.B PROCPS_PIDS_PRIORITY
-Kernel scheduling priority.
-.TP
-.B PROCPS_PIDS_PROCESSOR
-Current CPU the process is running on.
-.TP
-.B PROCPS_PIDS_RSS
-Resident set size.
-.TP
-.B PROCPS_PIDS_RSS_RLIM
-?
-.TP
-.B PROCPS_PIDS_RTPRIO
-Realtime priority.
-.TP
-.B PROCPS_PIDS_SCHED_CLASS
-Scheduling class, see
-.BR sched (7).
-.TP
-.B PROCPS_PIDS_SD_MACH, PROCPS_PIDS_SD_OUID, PROCPS_PIDS_SD_SEAT, PROCPS_PIDS_SD_SESS, PROCPS_PIDS_SD_SLICE, PROCPS_PIDS_SD_UNIT, PROCPS_PIDS_SD_UUNIT
-The systemd machine name, owner user ID, seat, session, slice, unit or user unit; see
-.BR sd_pid_get_session (3).
-.TP
-.B PROCPS_PIDS_SIGBLOCKED
-?
-.TP
-.B PROCPS_PIDS_SIGCATCH
-?
-.TP
-.B PROCPS_PIDS_SIGIGNORE
-?
-.TP
-.B PROCPS_PIDS_SIGNALS
-?
-.TP
-.B PROCPS_PIDS_SIGPENDING
-?
-.TP
-.B PROCPS_PIDS_STATE
-Process state codes.
-.TP
-.B PROCPS_PIDS_SUPGIDS, PROCPS_PIDS_SUPGROUPS
-IDs or names of the supplementary groups.
-.TP
-.B PROCPS_PIDS_TICS_ALL
-Sum of user and system time.
-.TP
-.B PROCPS_PIDS_TICS_ALL_C
-Cumulative sum of user and system time.
-.TP
-.B PROCPS_PIDS_TICS_DELTA
-Difference of sum of user and system time since last fetch.
-.TP
-.B PROCPS_PIDS_TICS_SYSTEM
-?
-.TP
-.B PROCPS_PIDS_TICS_SYSTEM_C
-?
-.TP
-.B PROCPS_PIDS_TICS_USER
-?
-.TP
-.B PROCPS_PIDS_TICS_USER_C
-?
-.TP
-.B PROCPS_PIDS_TIME_ALL
-?
-.TP
-.B PROCPS_PIDS_TIME_ELAPSED
-Total seconds since process started.
-.TP
-.B PROCPS_PIDS_TIME_START
-Time the process started.
-.TP
-.B PROCPS_PIDS_TTY, PROCPS_PIDS_TTY_NAME, PROCPS_PIDS_TTY_NUMBER
-Controlling terminal as a ID, name or number
-.TP
-.B PROCPS_PIDS_VM_DATA
-?
-.TP
-.B PROCPS_PIDS_VM_EXE
-?
-.TP
-.B PROCPS_PIDS_VM_LIB
-?
-.TP
-.B PROCPS_PIDS_VM_LOCK
-?
-.TP
-.B PROCPS_PIDS_VM_RSS
-?
-.TP
-.B PROCPS_PIDS_VM_RSS_ANON
-?
-.TP
-.B PROCPS_PIDS_VM_RSS_FILE
-?
-.TP
-.B PROCPS_PIDS_VM_RSS_LOCKED
-?
-.TP
-.B PROCPS_PIDS_VM_RSS_SHARED
-?
-.TP
-.B PROCPS_PIDS_VM_SIZE
-?
-.TP
-.B PROCPS_PIDS_VM_STACK
-?
-.TP
-.B PROCPS_PIDS_VM_SWAP
-?
-.TP
-.B PROCPS_PIDS_VM_USED
-?
-.TP
-.B PROCPS_PIDS_VSIZE_PGS
-?
-.TP
-.B PROCPS_PIDS_WCHAN_ADDR, PROCPS_PIDS_WCHAN_NAME
-Address or name of the kernel function in which the process is sleeping.
+.TS
+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.
+.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
+macro \fBPROCPS_PIDS_VAL\fR is used the following way
+.PP
+.RI \fBPROCPS_PIDS_VAL\fR( index , type , stack )
+where:
+.TP
+.I index
+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)
+.TP
+.I stack
+is the stack returned by \fBprocps_pids_read_next()\fR.
 .SH SEE ALSO
 .BR proc (5),
 .BR sched (7),
diff --git a/doc/procps_pids_read_open.3 b/doc/procps_pids_read_open.3
new file mode 100644
index 0000000..376dda2
--- /dev/null
+++ b/doc/procps_pids_read_open.3
@@ -0,0 +1,87 @@
+.\" (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).