PROCPS_PIDS
Section: C Library Functions (3)
Updated: 200-0-03
Index
Return to Main Contents
NAME
procps_pids - API to access process information in the /proc filesystem
SYNOPSIS
#include <libproc2/pids.h>
int procps_pids_new (struct pids_info **info, enum pids_item *items, int numitems);
int procps_pids_ref (struct pids_info *info);
int procps_pids_unref (struct pids_info **info);
struct pids_stack *procps_pids_get (
struct pids_info *info,
enum pids_fetch_type which);
struct pids_fetch *procps_pids_reap (
struct pids_info *info,
enum pids_fetch_type which);
struct pids_fetch *procps_pids_select (
struct pids_info *info,
unsigned *these,
int numthese,
enum pids_select_type which);
struct pids_stack **procps_pids_sort (
struct pids_info *info,
struct pids_stack *stacks[],
int numstacked,
enum pids_item sortitem,
enum pids_sort_order order);
int procps_pids_reset (
struct pids_info *info,
enum pids_item *newitems,
int newnumitems);
struct pids_stack *fatal_proc_unmounted (
struct pids_info *info,
int return_self);
Link with
-lproc2.
DESCRIPTION
Overview
Central to this interface 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 this 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 pids.h 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
this interface.
1. fatal_proc_unmounted()
2. procps_pids_new()
3. procps_pids_get(), procps_pids_reap() or procps_pids_select()
4. procps_pids_unref()
The
get function is an iterator for successive PIDs/TIDs,
returning those [oq]items[cq] previously identified via
new
or
reset.
Two functions support unpredictable variable outcomes.
The
reap function gathers data for all processes while
the
select function deals with specific PIDs or UIDs.
Both can return multiple [oq]stacks[cq] each containing multiple
[oq]result[cq] structures.
Optionally, a user may choose to
sort such 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 <pids> API differs from others in that those items
of interest must be provided at
new or
reset time,
the latter being unique to this API.
If either the
items or
numitems parameter is zero at
new time, then
reset becomes mandatory before
issuing any other call.
Otherwise, procps_pids_reset() should only be called when the order or
number of items in your stacks is changed.
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.
The
get and
reap functions use the
which parameter
to specify whether just tasks or both tasks and threads are to be fetched.
The
select function requires an array of PIDs or UIDs as
these along with
numthese to identify which processes
are to be fetched.
This function then operates as a subset of
reap.
When using the
sort function, the parameters
stacks and
numstacked would normally be those returned in the
[oq]pids_fetch[cq] structure.
Lastly, a
fatal_proc_unmounted function may be called before
any other function to ensure that the /proc/ directory is mounted.
As such, the
info parameter would be NULL and the
return_self parameter zero.
If, however, some items are desired for the issuing program (a
return_self other than zero) then the
new call must precede
it to identify the
items and obtain the required
info pointer.
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.
However, if one survives the
fatal_proc_unmounted call,
NULL is always returned when
return_self is zero.
DEBUGGING
To aid in program development, there are two procp-ng provisions
that can be exploited.
The first is a supplied file named [oq]libproc.supp[cq] which may be
useful when developing a
mult-threaded application.
When used with the valgrind [oq-suppressions=[cq] option, warnings
associated with the procps library itself are avoided.
Such warnings arise because the library handles heap based
allocations in a threa-safe manner.
A
singl-threaded application will not receive those warnings.
The second provision 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 your project may employ.
- 2)
-
Add #include <libproc2/xtr-procp-debug.h> to any program
after the #include <libproc2/pids.h>.
This verification feature incurs substantial overhead.
Therefore, it is important that it not be activated
for a production/release build.
ENVIRONMENT VARIABLE(S)
The value set for the following is unimportant, just its presence.
- LIBPROC_HIDE_KERNEL
-
This will hide kernel threads which would otherwise be returned with a
procps_pids_get, procps_pids_select or procps_pids_reap
call.
SEE ALSO
procps(3),
procps_misc(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
-
- ENVIRONMENT VARIABLE(S)
-
- SEE ALSO
-
|
|
- Running on 
-
:
