.\" t
.\" (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 LIBPROC 3 2016-01-05 "libproc-2"
.\" Please adjust this date whenever revising the manpage.
.\"
.SH NAME
libproc \-
Miscelleanous information about libproc

.SH SYNOPSIS
.B #include <proc/procps.h>

Link with \fI\-lprocps\fR.

.SH DESCRIPTION
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),
.BR procps_pids_reset "(3) and"
.BR procps_pids_sort (3).
The following items can be fetched for a process:
.TS
l l l
---
lB l l.
Item	Type	Description
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 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 )
where:
.TP
.I index
is the index of the \fIitems\fR defined with the function
.BR procps_pids_new (3)
.TP
.I type
type for returned value, see type column in \fBPID ITEMS\fR table.
.TP
.I stack
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).