eadb9db58f
This represents the 'second cut' at providing a shared man page that supports more than one newlib interface. In this approach, the following assumptions were made: 1) It is the kernel folks' job to document /proc files not to mention fields within those files. And since we don't yet know what some of those fields represent, we shouldn't attempt to document any of those we do know. 2) Our header files serve as an essential reference in successful exploitation of the new library interfaces. 3) The description represents functions as they appear in the header itself making them immediately familiar. 4) Some inconsistencies among the interfaces have been handled more visually rather than in a narrative form. 5) Armed with our header file users can easily see the self-documenting enumerators & structures. There isn't a need to explain them yet again in this man document. 6) Contrary to man guidelines, we shouldn't list error codes. Simple generic guidance serves everyone better. Reference(s): . 05/19/20, procps.3 man page introduced commit fc69028d374ae933b55b05b0f1418ac6a3da87e2 Signed-off-by: Jim Warner <james.warner@comcast.net>
174 lines
5.9 KiB
Groff
174 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.
|
|
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).
|