diff options
Diffstat (limited to 'man/procps_pids.3')
| -rw-r--r-- | man/procps_pids.3 | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/man/procps_pids.3 b/man/procps_pids.3 new file mode 100644 index 0000000..9ead691 --- /dev/null +++ b/man/procps_pids.3 @@ -0,0 +1,210 @@ +.\" +.\" Copyright (c) 2020-2023 Jim Warner <james.warner@comcast.net> +.\" Copyright (c) 2020-2023 Craig Small <csmall@dropbear.xyz> +.\" +.\" 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. +.\" +.\" +.TH PROCPS_PIDS 3 "August 2022" "libproc2" +.\" Please adjust this date whenever revising the manpage. +.\" +.nh +.SH NAME +procps_pids \- API to access process information in the /proc filesystem + +.SH SYNOPSIS +.nf +#include <libproc2/pids.h> + +.RI "int\fB procps_pids_new \fR (struct pids_info **" info ", enum pids_item *" items ", int " numitems ); +.RI "int\fB procps_pids_ref \fR (struct pids_info *" info ); +.RI "int\fB procps_pids_unref\fR (struct pids_info **" info ); + + +.RB "struct pids_stack *" procps_pids_get " (" +.RI " struct pids_info *" info , +.RI " enum pids_fetch_type " which ); + +.RB "struct pids_fetch *" procps_pids_reap " (" +.RI " struct pids_info *" info , +.RI " enum pids_fetch_type " which ); + +.RB "struct pids_fetch *" procps_pids_select " (" +.RI " struct pids_info *" info , +.RI " unsigned *" these , +.RI " int " numthese , +.RI " enum pids_select_type " which ); + +.RB "struct pids_stack **" procps_pids_sort " (" +.RI " struct pids_info *" info , +.RI " struct pids_stack *" stacks [], +.RI " int " numstacked , +.RI " enum pids_item " sortitem , +.RI " enum pids_sort_order " order ); + +.RB "int " procps_pids_reset " (" +.RI " struct pids_info *" info , +.RI " enum pids_item *" newitems , +.RI " int " newnumitems ); + +.RB "struct pids_stack *" fatal_proc_unmounted " (" +.RI " struct pids_info *" info , +.RI " int " return_self ); + +.fi + +Link with \fI\-lproc2\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 this interface there are two unique enumerators. +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. " fatal_proc_unmounted() +.RB "2. " procps_pids_new() +.RB "3. " procps_pids_get() ", " procps_pids_reap() " or " procps_pids_select() +.RB "4. " procps_pids_unref() +.fi + +The \fBget\fR function is an iterator for successive PIDs/TIDs, +returning those `items' previously identified via \fBnew\fR +or \fBreset\fR. + +Two functions support unpredictable variable outcomes. +The \fBreap\fR function gathers data for all processes while +the \fBselect\fR function deals with specific PIDs or UIDs. +Both can return multiple `stacks' each containing multiple `result' +structures. +Optionally, a user may choose to \fBsort\fR such results + +To exploit any `stack', and access individual `result' structures, +a \fIrelative_enum\fR is required as shown in the \fBVAL\fR macro +defined in the header file. +Such values could be hard coded as: 0 through numitems-1. +However, this need is typically satisfied by creating your own +enumerators corresponding to the order of the `items' array. + +.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 and \fBreap\fR functions use the \fIwhich\fR parameter +to specify whether just tasks or both tasks and threads are to be fetched. + +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. + +When using the \fBsort\fR function, the parameters \fIstacks\fR and +\fInumstacked\fR would normally be those returned in the `pids_fetch' +structure. + +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 \fIinfo\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 identify the \fIitems\fR and 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. +However, if one survives the \fBfatal_proc_unmounted\fR call, +NULL is always returned when \fIreturn_self\fR is zero. + +.SH DEBUGGING +To aid in program development, there are two procps-ng provisions +that can be exploited. + +The first is a supplied file named `libproc.supp' which may be +useful when developing a \fImulti-threaded\fR application. +When used with the valgrind `--suppressions=' option, warnings +associated with the procps library itself are avoided. + +Such warnings arise because the library handles heap based +allocations in a thread-safe manner. +A \fIsingle-threaded\fR application will not receive those warnings. + +The second provision can help ensure `result' member references +agree with library expectations. +It assumes that a supplied macro in the header file is +used to access the `result' value. + +This feature can be activated through either of the following +methods and any discrepancies will be written to \fBstderr\fR. + +.IP 1) 3 +Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure +options your project may employ. + +.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 ENVIRONMENT VARIABLE(S) +The value set for the following is unimportant, just its presence. + +.IP LIBPROC_HIDE_KERNEL +This will hide kernel threads which would otherwise be returned with a +.BR procps_pids_get ", " procps_pids_select " or " procps_pids_reap +call. + +.SH SEE ALSO +.BR procps (3), +.BR procps_misc (3), +.BR proc (5). |