+++ /dev/null
-.\" 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).
--- /dev/null
+.\" (C) Copyright 2020 Jim Warner <warnerjc@comcast.net>
+.\"
+.\" %%%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_LINUX_VERSION 3 "June 2020" "libproc-2"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.nh
+.SH NAME
+procps_pids \- API to access task/thread information in the /proc filesystem
+
+.SH SYNOPSIS
+.nf
+#include <procps/pids.h>
+
+.BI "int procps_pids_new (struct pids_info **" info ", enum pids_item *" items ", int " numitems );
+.BI "int procps_pids_ref (struct pids_info *" info );
+.BI "int procps_pids_unref (struct pids_info **" info );
+
+
+.BI "struct pids_stack *procps_pids_get ("
+.BI " struct pids_info *" info ,
+.BI " enum pids_fetch_type " which );
+
+.BI "struct pids_fetch *procps_pids_reap ("
+.BI " struct pids_info *" info ,
+.BI " enum pids_fetch_type " which );
+
+.BI "struct pids_fetch *procps_pids_select ("
+.BI " struct pids_info *" info ,
+.BI " unsigned *" these ,
+.BI " int " numthese ,
+.BI " enum pids_select_type " which );
+
+.BI "struct pids_stack **procps_pids_sort ("
+.BI " struct pids_info *" info ,
+.BI " struct pids_stack *" stacks[] ,
+.BI " int " numstacked ,
+.BI " enum pids_item " sortitem ,
+.BI " enum pids_sort_order " order );
+
+
+.BI "int procps_pids_reset ("
+.BI " struct pids_info *" info ,
+.BI " enum pids_item *" newitems ,
+.BI " int " newnumitems );
+
+.BI "struct pids_stack *fatal_proc_unmounted ("
+.BI " struct pids_info *" info ,
+.BI " int " return_self );
+
+.fi
+
+Link with \fI\-lprocps\fP.
+
+.SH DESCRIPTION
+.SS Overview
+Central to this interface is a simple `result'
+structure reflecting an `item' plus its value (in a union
+with standard C language types as members).
+All `result' structures are automatically allocated and
+provided by the library.
+
+By specifying an array of `items', these structures can be
+organized as a `stack', potentially yielding many results
+with a single function call.
+Thus, a `stack' can be viewed as a variable length record
+whose content and order is determined solely by the user.
+
+As part of each interface there are two unique items.
+The `noop' and `extra' items exist to hold user values.
+They are never set by the library, but the `extra'
+result will be zeroed with each library interaction.
+
+The pids.h file will be an essential document during
+user program development.
+There you will find available items, their return type
+(the `result' struct member name) and the source for such values.
+Additional enumerators and structures are also documented there.
+
+.SS Usage
+The following would be a typical sequence of calls to
+this interface.
+
+.nf
+.RB "1. " procps_pids_new()
+.RB "2. " procps_pids_get() ", " procps_pids_reap() " or " procps_pids_select()
+.RB "3. " procps_pids_unref()
+.fi
+
+Optionally, a user may choose to sort results returned from
+\fBreap\fR or \fBselect\fR.
+The \fBsort\fR function parameters \fIstacks\fR and \fInumstacked\fR
+would normally be those returned in the `pids_fetch' structure.
+
+.SS Caveats
+The <pids> API differs from others in that those items
+of interest must be provided at \fBnew\fR or \fBreset\fR time,
+the latter being unique to this API.
+If either the \fIitems\fR or \fInumitems\fR parameter is zero at
+\fBnew\fR time, then \fBreset\fR becomes mandatory before
+issuing any other call.
+
+For the \fBnew\fR and \fBunref\fR functions, the address of an \fIinfo\fR
+struct pointer must be supplied.
+With \fBnew\fR it must have been initialized to NULL.
+With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
+
+The \fBget\fR function is an iterator, for successive
+PIDs/TIDs, returning those items previously identified
+via \fBnew\fR or \fBreset\fR.
+
+The \fBselect\fR function requires an array of PIDs or UIDs as
+\fIthese\fR along with \fInumthese\fR to identify which processes
+are to be fetched.
+This function then operates as a subset of \fBreap\fR
+while returning those items previously identified via \fBnew\fR
+or \fBreset\fR.
+
+Lastly, a \fBfatal_proc_unmounted\fR function may be called before
+any other function to ensure that the /proc/ directory is mounted.
+As such, the \fIitem\fR parameter would be NULL and the
+\fIreturn_self\fR parameter zero.
+If, however, some items are desired for the issuing program (a
+\fIreturn_self\fR other than zero) then the \fBnew\fR call must precede
+it to obtain the required \fIinfo\fR pointer.
+
+.SH RETURN VALUE
+.SS Functions Returning an `int'
+An error will be indicated by a negative number that
+is always the inverse of some well known errno.h value.
+
+Success is indicated by a zero return value.
+However, the \fBref\fR and \fBunref\fR functions return
+the current \fIinfo\fR structure reference count.
+
+.SS Functions Returning an `address'
+An error will be indicated by a NULL return pointer
+with the reason found in the formal errno value.
+
+Success is indicated by a pointer to the named structure.
+
+.SH DEBUGGING
+To aid in program development, there is a provision that can
+help ensure `result' member references agree with library
+expectations.
+This feature can be activated through either of the following
+methods and any discrepancies will be wrtten to \fBstderr\fR.
+
+.IP 1) 3
+Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
+options employed.
+
+.IP 2) 3
+Add #include <procps/xtra-procps-debug.h> to any program
+\fIafter\fR the #include <procps/pids.h>.
+
+.PP
+This verification feature incurs substantial overhead.
+Therefore, it is important that it \fInot\fR be activated
+for a production/release build.
+
+.SH SEE ALSO
+.BR procps (3)
+.BR procps_misc (3)
+.BR proc (5).
+++ /dev/null
-.\" (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 PROCPS_PIDS_NEW 3 2017-01-05 "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 pids_info **" info ", enum pids_item *" items ", int " numitems ");"
-.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_get (3),
-.BR procps_pids_reap (3),
-.BR procps_pids_reset (3),
-.BR procps_pids_select (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 \fInumitems\fR long that selects what
-information about the processed will be stored. \fInumitems\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_reap (3),
-.BR procps_pids_reset (3),
-.BR procps_pids_select (3),
-.BR procps_pids_sort (3),
-.BR procps_pids_unref (3),
-.BR proc (5).
+++ /dev/null
-.\" (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 PROCPS_PIDS_REAP 3 2017-01-05 "libproc-2"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.SH NAME
-procps_pids_reap \- Harvest all the PIDS information structure.
-.SH SYNOPSIS
-.B #include <proc/procps.h>
-.sp
-.BI "struct pids_fetch * procps_pids_reap(struct pids_info *" info ", enum pids_fetch_type " which ");"
-.sp
-Link with \fI\-lprocps\fP.
-
-.SH DESCRIPTION
-\fBprocps_pids_reap()\fR is the function that will load the various
-files in the
-.BR proc (5)
-filesystem and fill the returned structure with the parsed values as
-well as a summary of the information gathered.
-The function is able to parse only processes or also include threads, the
-option \fIwhich\fR can be set to \fBPIDS_FETCH_TASKS_ONLY\fR or
-\fBPIDS_FETCH_THREADS_TOO\fR to determine what is collected.
-
-The info structure first needs to be initialised by
-.BR procps_pids_new (3).
-if \fBprocps_pids_reap()\fR returns successfully, a program can
-then iterate through a loop using the accessor methods described in
-.BR libproc (3).
-
-.SH RETURN VALUE
-\fBprocps_pids_reap()\fR returns a pointer to struct pids_fetch
-on success and NULL on failure.
-
-.SH VERSIONS
-\fBprocps_pids_reap()\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).
+++ /dev/null
-.\" (C) Copyright 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 PROCPS_PIDS_REF 3 2017-01-05 "libproc-2"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.SH NAME
-procps_pids_ref \-
-Increment reference count for pids structure.
-.SH SYNOPSIS
-.B #include <proc/procps.h>
-.sp
-.BI "int procps_pids_ref(struct pids_info *" info ");"
-.sp
-Link with \fI\-lprocps\fP.
-
-.SH DESCRIPTION
-.BR procps_pids_ref ()
-Will increment the reference count for the \fBpids_info\fR structure that was
-created with
-.BR procps_pids_new (3).
-The reference count is used by
-.BR procps_pids_unref (3)
-to determine when to de-allocate memort used by this structure.
-
-.SH RETURN VALUE
-The function returns the updated reference count on success
-and one of negative values below on failure.
-.TP
-.B -EINVAL
-One of the given parameters is incorrect.
-
-.SH VERSIONS
-.B procps_pids_ref()
-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).
+++ /dev/null
-.\" (C) Copyright 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 PROCPS_PIDS_reset 3 2017-01-05 "libproc-2"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.SH NAME
-procps_pids_reset \-
-Change what information is collected for a process
-.SH SYNOPSIS
-.B #include <proc/procps.h>
-.sp
-.BI "int procps_pids_reset(struct pids_info **" info ", enum pids_item *" items ", int " numitems ");"
-.sp
-Link with \fI\-lprocps\fP.
-
-.SH DESCRIPTION
-During the initial call to \fBprocps_pids_new\fR(3), the information structure
-is allocated and the information items are specified.
-\fBprocps_pids_reset\fR allows you to change what items for a process are collected
-without having to unreference and create a new \fIpids_info\fR structure.
-
-The changed PID information structure can then be used in subsequent calls to
-.BR procps_pids_get (3),
-.BR procps_pids_reap (3),
-.BR procps_pids_reset (3),
-.BR procps_pids_select (3),
-.BR procps_pids_sort (3)
-or even to further calls to \fBprocps_pids_reset\fR itself.
-
-The \fIitems\fR and \fInumitems\fR parameters are identical to the parameters
-used in \fBprocps_pids_new\fR.
-
-.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 changed structure.
-
-.SH VERSIONS
-.B procps_pids_reset()
-first appeared in libproc-2 version 0.0.
-
-.SH SEE ALSO
-.BR libproc (3),
-.BR procps_pids_new (3),
-.BR procps_pids_reap (3),
-.BR procps_pids_select (3),
-.BR procps_pids_sort (3),
-.BR procps_pids_unref (3),
-.BR proc (5).
+++ /dev/null
-.\" (C) Copyright 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 PROCPS_PIDS_select 3 2017-01-05 "libproc-2"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.SH NAME
-procps_pids_select \- Harvest process information that matches PID or UID
-.SH SYNOPSIS
-.B #include <proc/procps.h>
-.sp
-.BI "struct pids_fetch * procps_pids_select(struct pids_info *" info ", unsigned *" these ", int "numthese ", enum pids_select_type " which ");"
-.sp
-Link with \fI\-lprocps\fP.
-
-.SH DESCRIPTION
-\fBprocps_pids_select()\fR provides the same functionality as
-\fBprocps_pids_reap()\fR except it will only fetch information for the
-processes that have the process ID (PID) or User ID (UID) found in the
-array \fIthese\fR.
-
-\fIthese\fR is an array of process IDs (PIDs) or User IDs that the
-function will use to match against.
-
-\fInumthese\fR the length of the \fIthese\fR array.
-
-The \fIwhich\fR parameter tells the funtion what type of information is
-contained in \fIthese\fR and can be either \fBPIDS_SELECT_PID\fR if
-\fIthese\fR is an array of PIDs or \fBPIDS_SELECT_UID\fR if \fIthese\fR
-is an array of UIDs.
-
-The info structure first needs to be initialised by
-.BR procps_pids_new (3).
-if \fBprocps_pids_select()\fR returns successfully, a program can
-then iterate through a loop using the accessor methods described in
-.BR libproc (3).
-
-.SH RETURN VALUE
-\fBprocps_pids_select()\fR returns a pointer to struct pids_fetch
-on success and NULL on failure.
-
-.SH VERSIONS
-\fBprocps_pids_select()\fR first appeared in libproc-2 version 0.0.
-
-.SH SEE ALSO
-.BR libproc (3),
-.BR procps_pids_new (3),
-.BR procps_pids_reap (3),
-.BR procps_pids_unref (3),
-.BR proc (5).
+++ /dev/null
-.\" (C) Copyright 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 PROCPS_PIDS_SORT 3 2017-01-05 "libproc-2"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.SH NAME
-procps_pids_sort \-
-Sort process information
-.SH SYNOPSIS
-.B #include <proc/procps.h>
-.sp
-.BI "pids_stack **procps_pids_sort(struct pids_info *" info ", struct pids_stack *" stacks "[], int " numstacked ", enum pids_item " sortitem ", enum pids_sort_order " order ");"
-
-.sp
-Link with \fI\-lprocps\fP.
-
-.SH DESCRIPTION
-\fBprocps_pids_sort\fR sorts the given \fIstacks\fR stack of process
-information and sorts it by the given \fIsortitem\fR. \fInumstacked\fR
-must be the length of the \fIstacks\fR array and all the stacks in the
-list must be homogenous (of equal length and content).
-
-The stacks value can be obtained by a previous call of
-.BR procps_pids_reap (3)
-or
-.BR procps_pids_select (3)
-and then accessing the \fIstacks\fR member from that structure.
-
-\fIorder\fR can be either PIDS_SORT_ASCEND or PIDS_SORT_DESCEND.
-
-.SH RETURN VALUE
-The function returns the sorted stack on success or NULL on failure.
-
-.SH VERSIONS
-.B procps_pids_sort()
-first appeared in libproc-2 version 0.0.
-
-.SH SEE ALSO
-.BR libproc (3),
-.BR procps_pids_new (3),
-.BR procps_pids_reap (3),
-.BR procps_pids_select (3),
-.BR proc (5).
+++ /dev/null
-.\" (C) Copyright 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 PROCPS_PIDS_UREF 3 2017-01-05 "libproc-2"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.SH NAME
-procps_pids_refg \-
-Clear memory of pids structure, if no longer used
-.SH SYNOPSIS
-.B #include <proc/procps.h>
-.sp
-.BI "int procps_pids_refg(struct pids_info **" info ");"
-.sp
-Link with \fI\-lprocps\fP.
-
-.SH DESCRIPTION
-.BR procps_pids_refg ()
-will note that one less reference is used for the specified structure. If
-this was the last reference, the function returns the memory for the
-PID information structure that was created with
-.BR procps_pids_new (3).
-
-.SH RETURN VALUE
-The function returns 0 if the structure was freed or a positive
-integer of the current references if there were others. It will
-return one of negative values below on failure.
-.TP
-.B -EINVAL
-One of the given parameters is incorrect.
-
-.SH VERSIONS
-.B procps_pids_refg()
-first appeared in libproc-2 version 0.0.
-
-.SH SEE ALSO
-.BR libproc (3),
-.BR procps_pids_new (3),
-.BR procps_pids_reap (3),
-.BR procps_pids_reset (3),
-.BR procps_pids_select (3),
-.BR procps_pids_sort (3),
-.BR proc (5).
projects / procps-ng / commitdiff