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 Thus, a `stack' can be viewed as a variable length record
whose content and order is determined solely by the user. 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. The `noop' and `extra' items exist to hold user values.
They are never set by the library, but the `extra' They are never set by the library, but the `extra'
result will be zeroed with each library interaction. result will be zeroed with each library interaction.
@ -107,10 +107,26 @@ these interfaces.
.RB "3. " procps_unref() .RB "3. " procps_unref()
.fi .fi
Optionally, a user may choose to sort results returned from The \fBget\fR function is used to retrieve a `result' structure for
a \fBreap\fR function call. a single `item'.
The \fBsort\fR function parameters \fIstacks\fR and \fInumstacked\fR Alternatively, a \fBGET\fR macro is available when only the return
would normally be those returned in the `reaped' structure. 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 .SS Caveats
The \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR 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 on the \fBget\fR and \fBselect\fR functions identifies a disk or
partition name partition name
The \fBdiskstats\fR, \fBslabinfo\fR and \fBstat\fR interfaces support For the \fBstat\fR interface, a \fIwhat\fR parameter on the \fBreap\fR
unpredictable variable outcomes. function identifies whether data for just CPUs or both CPUs and NUMA
As such, they export a \fBreap\fR function to retrieve multiple `stacks' nodes is to be gathered.
with a single invocation.
These same interfaces also provide a \fBsort\fR function. 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 .SH RETURN VALUE
.SS Functions Returning an `int' .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 Thus, a `stack' can be viewed as a variable length record
whose content and order is determined solely by the user. 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. The `noop' and `extra' items exist to hold user values.
They are never set by the library, but the `extra' They are never set by the library, but the `extra'
result will be zeroed with each library interaction. result will be zeroed with each library interaction.
@ -103,10 +103,23 @@ this interface.
.RB "4. " procps_pids_unref() .RB "4. " procps_pids_unref()
.fi .fi
Optionally, a user may choose to sort results returned from The \fBget\fR function is an iterator for successive PIDs/TIDs,
a \fBreap\fR or \fBselect\fR function call. returning those `items' previously identified via \fBnew\fR
The \fBsort\fR function parameters \fIstacks\fR and \fInumstacked\fR or \fBreset\fR.
would normally be those returned in the `pids_fetch' structure.
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 .SS Caveats
The <pids> API differs from others in that those items 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 \fBnew\fR it must have been initialized to NULL.
With \fBunref\fR it will be reset to NULL if the reference count reaches zero. With \fBunref\fR it will be reset to NULL if the reference count reaches zero.
The \fBget\fR function is an iterator, for successive The \fBget\fR and \fBreap\fR functions use the \fIwhich\fR parameter
PIDs/TIDs, returning those items previously identified to specify whether just tasks or both tasks and threads are to be fetched.
via \fBnew\fR or \fBreset\fR.
The \fBselect\fR function requires an array of PIDs or UIDs as The \fBselect\fR function requires an array of PIDs or UIDs as
\fIthese\fR along with \fInumthese\fR to identify which processes \fIthese\fR along with \fInumthese\fR to identify which processes
are to be fetched. are to be fetched.
This function then operates as a subset of \fBreap\fR This function then operates as a subset of \fBreap\fR.
while returning those items previously identified via \fBnew\fR
or \fBreset\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 Lastly, a \fBfatal_proc_unmounted\fR function may be called before
any other function to ensure that the /proc/ directory is mounted. 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. \fIreturn_self\fR parameter zero.
If, however, some items are desired for the issuing program (a If, however, some items are desired for the issuing program (a
\fIreturn_self\fR other than zero) then the \fBnew\fR call must precede \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 .SH RETURN VALUE
.SS Functions Returning an `int' .SS Functions Returning an `int'