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