From fc4fb85e7bb5ab9f65e067ce2776f6b8fef24507 Mon Sep 17 00:00:00 2001 From: Jim Warner Date: Sun, 21 Jun 2020 00:00:00 -0500 Subject: [PATCH] docs: replace 'procps_pids' stuff with revised version The original approach contained a fatal flaw. In order to use those man pages, users would have been required to already know how to use the library. Or alternately one could randomly search each of them while trying to ascertain which function call satisfies their need and what exactly was the proper compliment/order required. So, this revised approach tries to simplify things and document only what is not apparent in the header file. Along the way, the following assumptions were germane. 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header file serves as an essential reference in successful exploitation of this new library interface. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 5) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. The following references represent a history for those man documents this new version is intended to replace. Reference(s): . 04/18/16, create libproc.3 + procps_pids_new.3 commit 4217eddf474debe55a7651757ccce1e86aeb04a5 . 04/19/16, create procps_pids_read_open.3 commit d48c54f6793d5faf44e420df43a75e04372d5945 . 01/05/17, create many procps_pids_... docs commit 2598e9f2ce39c93ebf55f664454d3bea919ed4e0 Signed-off-by: Jim Warner --- doc/libproc.3 | 256 --------------------------------------- doc/procps_pids.3 | 180 +++++++++++++++++++++++++++ doc/procps_pids_new.3 | 75 ------------ doc/procps_pids_reap.3 | 58 --------- doc/procps_pids_ref.3 | 56 --------- doc/procps_pids_reset.3 | 70 ----------- doc/procps_pids_select.3 | 65 ---------- doc/procps_pids_sort.3 | 59 --------- doc/procps_pids_unref.3 | 58 --------- 9 files changed, 180 insertions(+), 697 deletions(-) delete mode 100644 doc/libproc.3 create mode 100644 doc/procps_pids.3 delete mode 100644 doc/procps_pids_new.3 delete mode 100644 doc/procps_pids_reap.3 delete mode 100644 doc/procps_pids_ref.3 delete mode 100644 doc/procps_pids_reset.3 delete mode 100644 doc/procps_pids_select.3 delete mode 100644 doc/procps_pids_sort.3 delete mode 100644 doc/procps_pids_unref.3 diff --git a/doc/libproc.3 b/doc/libproc.3 deleted file mode 100644 index 5ced8df9..00000000 --- a/doc/libproc.3 +++ /dev/null @@ -1,256 +0,0 @@ -.\" t -.\" (C) Copyright 2016-2017 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 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 - -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). diff --git a/doc/procps_pids.3 b/doc/procps_pids.3 new file mode 100644 index 00000000..99a4e5ba --- /dev/null +++ b/doc/procps_pids.3 @@ -0,0 +1,180 @@ +.\" (C) Copyright 2020 Jim Warner +.\" +.\" %%%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 + +.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 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 to any program +\fIafter\fR the #include . + +.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). diff --git a/doc/procps_pids_new.3 b/doc/procps_pids_new.3 deleted file mode 100644 index 4c811c55..00000000 --- a/doc/procps_pids_new.3 +++ /dev/null @@ -1,75 +0,0 @@ -.\" (C) Copyright 2016-2017 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_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 -.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). diff --git a/doc/procps_pids_reap.3 b/doc/procps_pids_reap.3 deleted file mode 100644 index cab3aca3..00000000 --- a/doc/procps_pids_reap.3 +++ /dev/null @@ -1,58 +0,0 @@ -.\" (C) Copyright 2016-2017 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_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 -.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). diff --git a/doc/procps_pids_ref.3 b/doc/procps_pids_ref.3 deleted file mode 100644 index 01fdddd9..00000000 --- a/doc/procps_pids_ref.3 +++ /dev/null @@ -1,56 +0,0 @@ -.\" (C) Copyright 2017 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_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 -.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). diff --git a/doc/procps_pids_reset.3 b/doc/procps_pids_reset.3 deleted file mode 100644 index 7e77c26f..00000000 --- a/doc/procps_pids_reset.3 +++ /dev/null @@ -1,70 +0,0 @@ -.\" (C) Copyright 2017 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_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 -.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). diff --git a/doc/procps_pids_select.3 b/doc/procps_pids_select.3 deleted file mode 100644 index 642e158d..00000000 --- a/doc/procps_pids_select.3 +++ /dev/null @@ -1,65 +0,0 @@ -.\" (C) Copyright 2017 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_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 -.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). diff --git a/doc/procps_pids_sort.3 b/doc/procps_pids_sort.3 deleted file mode 100644 index 3cce1d87..00000000 --- a/doc/procps_pids_sort.3 +++ /dev/null @@ -1,59 +0,0 @@ -.\" (C) Copyright 2017 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_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 -.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). diff --git a/doc/procps_pids_unref.3 b/doc/procps_pids_unref.3 deleted file mode 100644 index 2839f320..00000000 --- a/doc/procps_pids_unref.3 +++ /dev/null @@ -1,58 +0,0 @@ -.\" (C) Copyright 2017 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_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 -.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).