PROCPS(3) Library Functions Manual PROCPS(3)
NAME
procps - API to access system level information in the /proc filesystem
SYNOPSIS
Five distinct interfaces are represented in this synopsis and named
after the files they access in the /proc pseudo filesystem: diskstats,
meminfo, slabinfo, stat and vmstat.
#include <libproc2/named_interface.h>
int procps_new (struct info **info);
int procps_ref (struct info *info);
int procps_unref (struct info **info);
struct result *procps_get (
struct info *info,
[ const char *name, ] diskstats api only
enum item item);
struct stack *procps_select (
struct info *info,
[ const char *name, ] diskstats api only
enum item *items,
int numitems);
struct reaped *procps_reap (
struct info *info,
[ enum reap_type what, ] stat api only
enum item *items,
int numitems);
struct stack **procps_sort (
struct info *info,
struct stack *stacks[],
int numstacked,
enum item sortitem,
enum sort_order order);
The above functions and structures are generic but the specific
named_interface would also be part of any identifiers. For
example, `procps_new' would actually be `procps_meminfo_new' and
`info' would really be `diskstats_info', etc.
The same named_interface is used in each header file name with an
appended `.h' suffix.
Link with -lproc2.
DESCRIPTION
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 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 named_interface 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.
Usage
The following would be a typical sequence of calls to these interfaces.
1. procps_new()
2. procps_get(), procps_select() or procps_reap()
3. procps_unref()
The get function is used to retrieve a `result' structure for a single
`item'. Alternatively, a GET macro is available when only the return
value is of interest.
The select function can retrieve multiple `result' structures in a
single `stack'.
For unpredictable variable outcomes, the diskstats, slabinfo and stat
interfaces export a reap function. It is used to retrieve multiple
`stacks' each containing multiple `result' structures. Optionally, a
user may choose to sort those results.
To exploit any `stack', and access individual `result' structures, a
relative_enum is required as shown in the VAL 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.
Caveats
The new, ref, unref, get and select functions are available in all five
interfaces.
For the new and unref functions, the address of an info struct pointer
must be supplied. With new it must have been initialized to NULL.
With unref it will be reset to NULL if the reference count reaches
zero.
In the case of the diskstats interface, a name parameter on the get and
select functions identifies a disk or partition name
For the stat interface, a what parameter on the reap function
identifies whether data for just CPUs or both CPUs and NUMA nodes is to
be gathered.
When using the sort function, the parameters stacks and numstacked
would normally be those returned in the `reaped' structure.
RETURN VALUE
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 ref and
unref functions return the current info structure reference count.
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.
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 written to stderr.
1) Add CFLAGS='-DXTRA_PROCPS_DEBUG' to any other ./configure options
employed.
2) Add #include <procps/xtra-procps-debug.h> to any program after the
named interface includes.
This verification feature incurs substantial overhead. Therefore, it
is important that it not be activated for a production/release build.
SEE ALSO
procps_misc(3), procps_pids(3), proc(5).
libproc2 August 2022 PROCPS(3)
Generated by dwww version 1.15 on Sun Jun 23 16:46:44 CEST 2024.