PROCPS
Section: C Library Functions (3)
Updated: 202-0-22
Index
Return to Main Contents
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,
[oq]procps_new[cq] would actually be
[oq]procps_meminfo_new[cq] and [oq]info[cq] would really be
[oq]diskstats_info[cq], etc.
The same named_interface is used in each header file name with
an appended [oq].h[cq] suffix.
Link with -lproc2.
DESCRIPTION
Overview
Central to these interfaces is a simple [oq]result[cq]
structure reflecting an [oq]item[cq] plus its value (in a union
with standard C language types as members).
All [oq]result[cq] structures are automatically allocated and
provided by the library.
By specifying an array of [oq]items[cq], these structures can be
organized as a [oq]stack[cq], potentially yielding many results
with a single function call.
Thus, a [oq]stack[cq] 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 [oq]noop[cq] and [oq]extra[cq] items exist to hold user values.
They are never set by the library, but the [oq]extra[cq]
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 [oq]result[cq] 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 [oq]result[cq] structure
for a single [oq]item[cq].
Alternatively, a
GET macro is available when only the return
value is of interest.
The
select function can retrieve multiple [oq]result[cq]
structures in a single [oq]stack[cq].
For unpredictable variable outcomes, the
diskstats,
slabinfo
and
stat interfaces export a
reap function.
It is used to retrieve multiple [oq]stacks[cq] each containing
multiple [oq]result[cq] structures.
Optionally, a user may choose to
sort those results.
To exploit any [oq]stack[cq],
and access individual [oq]result[cq] 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 numitem-1.
However, this need is typically satisfied by creating your own
enumerators corresponding to the order of the [oq]items[cq] 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
[oq]reaped[cq] structure.
RETURN VALUE
Functions Returning an [oq]int[cq]
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 [oq]address[cq]
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 [oq]result[cq] member references agree with library
expectations.
It assumes that a supplied macro in the header file is
used to access the [oq]result[cq] 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 <libproc2/xtr-procp-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).
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- Overview
-
- Usage
-
- Caveats
-
- RETURN VALUE
-
- Functions Returning an [oq]int[cq]
-
- Functions Returning an [oq]address[cq]
-
- DEBUGGING
-
- SEE ALSO
-
|
|
- Running on 
-
:
