emo/procps
1
0
Fork 0
Code Issues Pull Requests Packages Releases Activity

docs: expand 2 man pages 'Usage' to include VAL macros

Browse Source 
Maybe, the biggest obstacle to successfully exploiting
this new library is after those `stacks' are returned.

Unless a user requests all available `items', there is
always a need to translate an actual enumerator into a
relative position within returned stack(s) of results.

So, this patch attempts to bridge that gap by adding a
brief explanation to the existing discussion in Usage.

[ along the way, 'Usage' & 'Caveats' were refactored ]

Signed-off-by: Jim Warner <james.warner@comcast.net>
This commit is contained in:
Jim Warner 2021-02-15 00:00:00 -06:00 committed by Craig Small
parent 333a1bb6b8
commit 9c98179558
2 changed files with 54 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
doc/procps.3
View File

@ -86,7 +86,7 @@ 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.
As part of each 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.
@ -107,10 +107,26 @@ these interfaces.
.RB "3. " procps_unref()
.fi
Optionally, a user may choose to sort results returned from
a \fBreap\fR function call.
The \fBsort\fR function parameters \fIstacks\fR and \fInumstacked\fR
would normally be those returned in the `reaped' structure.
The \fBget\fR function is used to retrieve a `result' structure for
a single `item'.
Alternatively, a \fBGET\fR macro is available when only the return
value is of interest.
The \fBselect\fR function can retrieve multiple `result' structures
in a single `stack'.
For unpredictable variable outcomes, the \fBdiskstats\fR, \fBslabinfo\fR
and \fBstat\fR interfaces export a \fBreap\fR function.
It is used to retrieve multiple `stacks' each containing multiple
`result' structures.
Optionally, a user may choose to \fBsort\fR those 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 \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR
@ -125,11 +141,13 @@ In the case of the \fBdiskstats\fR interface, a \fIname\fR parameter
on the \fBget\fR and \fBselect\fR functions identifies a disk or
partition name
The \fBdiskstats\fR, \fBslabinfo\fR and \fBstat\fR interfaces support
unpredictable variable outcomes.
As such, they export a \fBreap\fR function to retrieve multiple `stacks'
with a single invocation.
These same interfaces also provide a \fBsort\fR function.
For the \fBstat\fR interface, a \fIwhat\fR parameter on the \fBreap\fR
function identifies whether data for just CPUs or both CPUs and NUMA
nodes is to be gathered.
When usng the \fBsort\fR function, the parameters \fIstacks\fR and
\fInumstacked\fR would normally be those returned in the `reaped'
structure.
.SH RETURN VALUE
.SS Functions Returning an `int'

38
doc/procps_pids.3
View File

@ -81,7 +81,7 @@ 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.
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.
@ -103,10 +103,23 @@ this interface.
.RB "4. " procps_pids_unref()
.fi
Optionally, a user may choose to sort results returned from
a \fBreap\fR or \fBselect\fR function call.
The \fBsort\fR function parameters \fIstacks\fR and \fInumstacked\fR
would normally be those returned in the `pids_fetch' structure.
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
@ -121,16 +134,17 @@ 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 \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
while returning those items previously identified via \fBnew\fR
or \fBreset\fR.
This function then operates as a subset of \fBreap\fR.
When usng 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.
@ -138,7 +152,7 @@ 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 obtain the required \fIinfo\fR pointer.
it to identify the \fIitems\fR and obtain the required \fIinfo\fR pointer.
.SH RETURN VALUE
.SS Functions Returning an `int'