docs: Additional flags in man pages

More PIDS defintions
This commit is contained in:
Craig Small 2016-04-19 23:28:53 +10:00
parent aa16ab0dc1
commit d48c54f679
2 changed files with 229 additions and 279 deletions

View File

@ -1,3 +1,4 @@
.\" t
.\" (C) Copyright 2016 Craig Small <csmall@enc.com.au> .\" (C) Copyright 2016 Craig Small <csmall@enc.com.au>
.\" .\"
.\" %%%LICENSE_START(LGPL_2.1+) .\" %%%LICENSE_START(LGPL_2.1+)
@ -16,7 +17,7 @@
.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA .\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
.\" %%%LICENSE_END .\" %%%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. .\" Please adjust this date whenever revising the manpage.
.\" .\"
.SH NAME .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_reset "(3) and"
.BR procps_pids_sort (3). .BR procps_pids_sort (3).
The following items can be fetched for a process: The following items can be fetched for a process:
.TP .TS
.B PROCPS_PIDS_ADDR_END_CODE l l l
? ---
.TP lB l l.
.B PROCPS_PIDS_ADDR_KSTK_EIP Item Type Description
Instruction pointer. PROCPS_PIDS_ADDR_END_CODE ul_int The address below which program text can run
.TP PROCPS_PIDS_ADDR_KSTK_EIP ul_int Instruction pointer
.B PROCPS_PIDS_ADDR_KSTK_ESP PROCPS_PIDS_ADDR_KSTK_ESP ul_int Stack pointer
Stack pointer. PROCPS_PIDS_ADDR_START_CODE ul_int The address above which program text can run
.TP PROCPS_PIDS_ADDR_START_STACK ul_int Address of the start (bottom) of the stack
.B PROCPS_PIDS_ADDR_START_CODE PROCPS_PIDS_ALARM sl_int ??
? PROCPS_PIDS_CGNAME str The name of the control group for the process
.TP PROCPS_PIDS_CGROUP str List of control groups
.B PROCPS_PIDS_ADDR_START_STACK PROCPS_PIDS_CGROUP_V strv List of control groups
Address of the start (bottom) of the stack. PROCPS_PIDS_CMD str Command name (only the executable name)
.TP PROCPS_PIDS_CMDLINE str Full command line
.B PROCPS_PIDS_ALARM PROCPS_PIDS_CMDLINE_V strv Full command line
? PROCPS_PIDS_ENVIRON str The process environment
.TP PROCPS_PIDS_ENVIRON_V strv The process environment
.B PROCPS_PIDS_CGNAME PROCPS_PIDS_EXIT_SIGNAL s_int Signal sent to parent when this process dies
The name of the control group for the process. PROCPS_PIDS_FLAGS ul_int Process flags
.TP PROCPS_PIDS_FLT_MAJ ul_int Number of major page faults
.B PROCPS_PIDS_CGROUP, PROCPS_PIDS_CGROUP_V PROCPS_PIDS_FLT_MAJ_C ul_int Cumulative major page faults
List of control groups the process belongs to as a string or string vector. PROCPS_PIDS_FLT_MAJ_DELTA ul_int Number of major page faults since last fetch
.TP PROCPS_PIDS_FLT_MIN ul_int Number of minor page faults
.B PROCPS_PIDS_CMD PROCPS_PIDS_FLT_MIN_C ul_int Culmative minor page faults
Command name (only the executable name). PROCPS_PIDS_FLT_MIN_DELTA ul_int Number of minor page faults since last fetch
.TP PROCPS_PIDS_ID_EGID u_int Effective group ID number
.B PROCPS_PIDS_CMDLINE, PROCPS_PIDS_CMDLINE_V PROCPS_PIDS_ID_EGROUP str Effective group name
Full command line as a string or string vector. PROCPS_PIDS_ID_EUID u_int Effective user ID number
.TP PROCPS_PIDS_ID_EUSER str Effective user name
.B PROCPS_PIDS_ENVIRON, PROCPS_PIDS_ENVIRON_V PROCPS_PIDS_ID_FGID u_int File system access group ID number
The processes environment as a string or string vector. PROCPS_PIDS_ID_FGROUP str File system access group name
.TP PROCPS_PIDS_ID_FUID u_int File system access user ID number
.B PROCPS_PIDS_EXIT_SIGNAL 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
.TP PROCPS_PIDS_ID_PID s_int Proccess ID number
.B PROCPS_PIDS_FLAGS PROCPS_PIDS_ID_PPID s_int Process ID number of parent
Process flags. PROCPS_PIDS_ID_RGID u_int Real group ID number
.TP PROCPS_PIDS_ID_RGROUP str Real group name
.B PROCPS_PIDS_FLT_MAJ PROCPS_PIDS_ID_RUID u_int Real user ID number
Number of major page faults. PROCPS_PIDS_ID_RUSER str Real user name
.TP PROCPS_PIDS_ID_SESSION s_int Session ID number, or process ID of session leader
.B PROCPS_PIDS_FLT_MAJ_C PROCPS_PIDS_ID_SGID u_int Saved group ID number
Cumulative major page faults. PROCPS_PIDS_ID_SGROUP str Saved group name
.TP PROCPS_PIDS_ID_SUID u_int Saved user ID number
.B PROCPS_PIDS_FLT_MAJ_DELTA PROCPS_PIDS_ID_SUSER str Saved user nameSaved user name
Number of major page faults since last fetch. PROCPS_PIDS_ID_TGID s_int Thread group ID number, or process ID of thread group leader
.TP PROCPS_PIDS_ID_TPGID s_int Process ID of foreground process group on the tty
.B PROCPS_PIDS_FLT_MIN PROCPS_PIDS_LXCNAME str Linux container name
Number of minor page faults. PROCPS_PIDS_MEM_CODE sl_int ??
.TP PROCPS_PIDS_MEM_CODE_KIB ul_int ??
.B PROCPS_PIDS_FLT_MIN_C PROCPS_PIDS_MEM_DATA sl_int ??
Culmative minor page faults. PROCPS_PIDS_MEM_DATA_KIB ul_int ??
.TP PROCPS_PIDS_MEM_DT sl_int ??
.B PROCPS_PIDS_FLT_MIN_DELTA PROCPS_PIDS_MEM_LRS sl_int ??
Number of minor page faults since last fetch. PROCPS_PIDS_MEM_RES sl_int Resident set size
.TP PROCPS_PIDS_MEM_RES_KIB ul_int Resident set size
.B PROCPS_PIDS_ID_EGID, PROCPS_PIDS_ID_EGROUP PROCPS_PIDS_MEM_SHR sl_int Shared memory
Effective group as a ID number or name. PROCPS_PIDS_MEM_SHR_KIB ul_int Shared memory
.TP PROCPS_PIDS_MEM_VIRT sl_int Virtual memory
.B PROCPS_PIDS_ID_EUID, PROCPS_PIDS_ID_EUSER PROCPS_PIDS_MEM_VIRT_KIB ul_int Virtual memory
Effective user ID number or name. PROCPS_PIDS_NICE sl_int Nice value
.TP PROCPS_PIDS_NLWP s_int Number of lwps (threads) in the process
.B PROCPS_PIDS_ID_FGID, PROCPS_PIDS_ID_FGROUP PROCPS_PIDS_NS_IPC ul_int Current IPC namespace
File system access group ID number or name. PROCPS_PIDS_NS_MNT ul_int Current mount namespace
.TP PROCPS_PIDS_NS_NET ul_int Current network namespace
.B PROCPS_PIDS_ID_FUID, PROCPS_PIDS_ID_FUSER PROCPS_PIDS_NS_PID ul_int Current PID namespace
File sytem access user ID number or name. PROCPS_PIDS_NS_USER ul_int Current user namespace
.TP PROCPS_PIDS_NS_UTS ul_int Current UTC namespace
.B PROCPS_PIDS_ID_PGRP PROCPS_PIDS_OOM_ADJ s_int Out Of Memory Adjust
Process group ID, or process ID of group leader. PROCPS_PIDS_OOM_SCORE s_int Process Out Of Memory Score
.TP PROCPS_PIDS_PRIORITY s_int Kernel scheduling priority
.B PROCPS_PIDS_ID_PID PROCPS_PIDS_PROCESSOR u_int Current CPU the process is running on
Proccess ID number. PROCPS_PIDS_RSS sl_int Resident set size
.TP PROCPS_PIDS_RSS_RLIM ul_int Soft limit of RSS in bytes
.B PROCPS_PIDS_ID_PPID PROCPS_PIDS_RTPRIO ul_int Realtime priority
Process ID number of parent. PROCPS_PIDS_SCHED_CLASS ul_int Scheduling class, see \fBsched\fR(7)
.TP PROCPS_PIDS_SD_MACH str Systemd machine name
.B PROCPS_PIDS_ID_RGID, PROCPS_PIDS_ID_RGROUP PROCPS_PIDS_SD_OUID str Systemd owner user ID
Real group ID number or name. PROCPS_PIDS_SD_SEAT str Systemd seat
.TP PROCPS_PIDS_SD_SESS str Systemd session
.B PROCPS_PIDS_ID_RUID, PROCPS_PIDS_ID_RUSER PROCPS_PIDS_SD_SLICE str Systemd slice
Real user ID number or name. PROCPS_PIDS_SD_UNIT str Systemd unit
.TP PROCPS_PIDS_SD_UUNIT str Systemd user unit
.B PROCPS_PIDS_ID_SESSION PROCPS_PIDS_SIGBLOCKED str Bitmap of blocked signals
Session ID number, or process ID of session leader. PROCPS_PIDS_SIGCATCH str Bitmap of caught signals
.TP PROCPS_PIDS_SIGIGNORE str Bitmap of ignored signals
.B PROCPS_PIDS_ID_SGID, PROCPS_PIDS_ID_SGROUP PROCPS_PIDS_SIGNALS str Bitmap of pending signals
Saved group ID number or name. PROCPS_PIDS_SIGPENDING str Bitmap of pending signals
.TP PROCPS_PIDS_STATE s_ch Process state codes
.B PROCPS_PIDS_ID_SUID, PROCPS_PIDS_ID_SUSER PROCPS_PIDS_SUPGIDS str IDs of the supplementary groups
Saved user ID number or name. PROCPS_PIDS_SUPGROUPS str Name of the supplementary groups
.TP PROCPS_PIDS_TICS_ALL ull_int Sum of user and system time
.B PROCPS_PIDS_ID_TGID PROCPS_PIDS_TICS_ALL_C ull_int Cumulative sum of user and system time
Thread group ID number, or process ID of thread group leader. PROCPS_PIDS_TICS_DELTA u_int Difference of sum of user and system time since last fetch
.TP PROCPS_PIDS_TICS_SYSTEM ull_int Amount of time process has been in system mode in ticks
.B PROCPS_PIDS_ID_TPGID PROCPS_PIDS_TICS_SYSTEM_C ull_int ??
Process ID of foreground process group on the tty. PROCPS_PIDS_TICS_USER ull_int Amount of time process has been scheduled in user mode in ticks
.TP PROCPS_PIDS_TICS_USER_C ull_int ??
.B PROCPS_PIDS_LXCNAME PROCPS_PIDS_TIME_ALL ull_int ??
Linux container name. PROCPS_PIDS_TIME_ELAPSED ull_int Total seconds since process started
.TP PROCPS_PIDS_TIME_START ull_int Time the process started
.B PROCPS_PIDS_MEM_CODE PROCPS_PIDS_TTY s_int Controlling terminal ID number
? PROCPS_PIDS_TTY_NAME str Controlling terminal name
.TP PROCPS_PIDS_TTY_NUMBER str Controlling terminal number
.B PROCPS_PIDS_MEM_CODE_KIB PROCPS_PIDS_VM_DATA ul_int ??
? PROCPS_PIDS_VM_EXE ul_int ??
.TP PROCPS_PIDS_VM_LIB ul_int ??
.B PROCPS_PIDS_MEM_DATA PROCPS_PIDS_VM_LOCK ul_int ??
? PROCPS_PIDS_VM_RSS ul_int ??
.TP PROCPS_PIDS_VM_RSS_ANON ul_int ??
.B PROCPS_PIDS_MEM_DATA_KIB PROCPS_PIDS_VM_RSS_FILE ul_int ??
? PROCPS_PIDS_VM_RSS_LOCKED ul_int ??
.TP PROCPS_PIDS_VM_RSS_SHARED ul_int ??
.B PROCPS_PIDS_MEM_DT PROCPS_PIDS_VM_SIZE ul_int ??
? PROCPS_PIDS_VM_STACK ul_int ??
.TP PROCPS_PIDS_VM_SWAP ul_int ??
.B PROCPS_PIDS_MEM_LRS PROCPS_PIDS_VM_USED ul_int ??
? PROCPS_PIDS_VSIZE_PGS ul_int ??
.TP PROCPS_PIDS_WCHAN_ADDR ul_int Address of the kernel function in which the process is sleeping.
.B PROCPS_PIDS_MEM_RES PROCPS_PIDS_WCHAN_NAME str Name of the kernel function in which the process is sleeping.
Resident set size .TE
.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.
.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 .SH SEE ALSO
.BR proc (5), .BR proc (5),
.BR sched (7), .BR sched (7),

View File

@ -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).