docs: Start documenting the pids API

Started with procps_pids_new() and documenting this function
as well as the enum used in this function.
This commit is contained in:
Craig Small 2016-04-18 22:57:01 +10:00
parent b4d21c74ac
commit 4217eddf47
3 changed files with 397 additions and 0 deletions

View File

@ -54,7 +54,9 @@ dist_man_MANS = \
vmstat.8 \
w.1 \
ps/ps.1 \
doc/libproc.3 \
doc/procps_linux_version.3 \
doc/procps_pids_new.3 \
doc/procps_uptime.3 \
doc/procps_uptime_sprint.3 \
doc/procps_uptime_sprint_short.3

323
doc/libproc.3 Normal file
View File

@ -0,0 +1,323 @@
.\" (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 LIBPROC 3 2016-04-18 "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 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:
.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.
.SH SEE ALSO
.BR proc (5),
.BR sched (7),
.BR user_namespaces (7).

72
doc/procps_pids_new.3 Normal file
View File

@ -0,0 +1,72 @@
.\" (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_NEW 3 2016-04-18 "libproc-2"
.\" Please adjust this date whenever revising the manpage.
.\"
.SH NAME
procps_pids_new \-
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 ");"
.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_reset (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
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
.BR libproc (3).
Once the structure is no longer required,
.BR procps_pids_unref (3)
should be used to free it.
.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 structure.
.SH VERSIONS
.B procps_pids_new()
first appeared in libproc-2 version 0.0.
.SH SEE ALSO
.BR libproc (3),
.BR procps_pids_read_open (3),
.BR procps_pids_reset (3),
.BR procps_pids_sort (3),
.BR procps_pids_unref (3),
.BR proc (5).