9b3436e0e4
An important fact was omitted in the DEBUGGING section for the two newest man documents. Users must utilize a macro in the header files before verification happens. So, this commit will sneak in such mention and in that way reduce future liability if the feature won't work. Signed-off-by: Jim Warner <james.warner@comcast.net>
177 lines
5.9 KiB
Groff
177 lines
5.9 KiB
Groff
.\" (C) Copyright 2020 Jim Warner <warnerjc@comcast.net>
|
|
.\"
|
|
.\" %%%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 \- API to access system level information in the /proc filesystem
|
|
|
|
.SH SYNOPSIS
|
|
Five distinct interfaces are represented in this synopsis and named after
|
|
the files they access in the /proc pseudo filesystem:
|
|
.BR diskstats ", " meminfo ", " slabinfo ", " stat " and " vmstat .
|
|
|
|
.nf
|
|
.RS +4
|
|
#include <procps/\fBnamed_interface\fR.h>
|
|
|
|
.BI "int procps_new (struct info **" info );
|
|
.BI "int procps_ref (struct info *" info );
|
|
.BI "int procps_unref (struct info **" info );
|
|
|
|
.BI "struct result *procps_get ("
|
|
.BI " struct info *" info ,
|
|
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
|
|
.BI " enum item " item );
|
|
|
|
.BI "struct stack *procps_select ("
|
|
.BI " struct info *" info ,
|
|
.RI "[ const char *" name ", ] \fBdiskstats\fR api only"
|
|
.BI " enum item *" items ,
|
|
.BI " int " numitems );
|
|
|
|
.BI "struct reaped *procps_reap ("
|
|
.BI " struct info *" info ,
|
|
.RI "[ enum reap_type " what ", ] \fBstat\fR api only"
|
|
.BI " enum item *" items ,
|
|
.BI " int " numitems );
|
|
|
|
.BI "struct stack **procps_sort ("
|
|
.BI " struct info *" info ,
|
|
.BI " struct stack *" stacks[] ,
|
|
.BI " int " numstacked ,
|
|
.BI " enum item " sortitem ,
|
|
.BI " enum sort_order " order );
|
|
.RE
|
|
.fi
|
|
|
|
The above functions and structures are generic but the specific
|
|
\fBnamed_interface\fR would also be part of any identifiers.
|
|
For example, `procps_new' would actually be `procps_\fBmeminfo\fR_new'
|
|
and `info' would really be `\fBdiskstats\fR_info', etc.
|
|
|
|
The same \fBnamed_interface\fR is used in each header file name with
|
|
an appended `.h' suffix.
|
|
|
|
Link with \fI\-lprocps\fP.
|
|
|
|
.SH DESCRIPTION
|
|
.SS Overview
|
|
Central to these interfaces 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 \fBnamed_interface\fR header 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
|
|
these interfaces.
|
|
|
|
.nf
|
|
.RB "1. " procps_new()
|
|
.RB "2. " procps_get() ", " procps_select() " or " procps_reap()
|
|
.RB "3. " procps_unref()
|
|
.fi
|
|
|
|
Optionally, a user may choose to sort results returned from
|
|
a \fBreap\fR function call.
|
|
|
|
.SS Caveats
|
|
The \fBnew\fR, \fBref\fR, \fBunref\fR, \fBget\fR and \fBselect\fR
|
|
functions are available in all five interfaces.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
Those same interfaces also offer a \fBsort\fR function whose
|
|
parameters \fIstacks\fR and \fInumstacked\fR would normally be those
|
|
returned in the `reaped' structure.
|
|
|
|
.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.
|
|
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 wrtten to \fBstderr\fR.
|
|
|
|
.IP 1) 3
|
|
Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure
|
|
options employed.
|
|
|
|
.IP 2) 3
|
|
Add #include <procps/xtra-procps-debug.h> to any program
|
|
\fIafter\fR the named interface includes.
|
|
|
|
.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_misc (3)
|
|
.BR procps_pids (3)
|
|
.BR proc (5).
|