From d48c54f6793d5faf44e420df43a75e04372d5945 Mon Sep 17 00:00:00 2001 From: Craig Small Date: Tue, 19 Apr 2016 23:28:53 +1000 Subject: [PATCH] docs: Additional flags in man pages More PIDS defintions --- doc/libproc.3 | 421 ++++++++++++------------------------ doc/procps_pids_read_open.3 | 87 ++++++++ 2 files changed, 229 insertions(+), 279 deletions(-) create mode 100644 doc/procps_pids_read_open.3 diff --git a/doc/libproc.3 b/doc/libproc.3 index d325c979..3e046261 100644 --- a/doc/libproc.3 +++ b/doc/libproc.3 @@ -1,3 +1,4 @@ +.\" t .\" (C) Copyright 2016 Craig Small .\" .\" %%%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 00000000..376dda28 --- /dev/null +++ b/doc/procps_pids_read_open.3 @@ -0,0 +1,87 @@ +.\" (C) Copyright 2016 Craig Small +.\" +.\" %%%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 +.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).