PMAPPING_ITER(3PROC) Process Control Library Functions PMAPPING_ITER(3PROC)

NAME


Pmapping_iter, Pmapping_iter_resolved, Pobject_iter, Pobject_iter_resolved
- iterate over process mappings and objects

LIBRARY


Process Control Library (libproc, -lproc)

SYNOPSIS


#include <libproc.h>

int
Pmapping_iter(struct ps_prochandle *P, proc_map_f *func, void *data);

int
Pmapping_iter_resolved(struct ps_prochandle *P, proc_map_f *func,
void *data);

int
Pobject_iter(struct ps_prochandle *P, proc_map_f *func, void *data);

int
Pobject_iter_resolved(struct ps_prochandle *P, proc_map_f *func,
void *data);

DESCRIPTION


The Pmapping_iter() and Pmapping_iter_resolved() functions iterate over the
memory mappings in the process represented by P.

For each memory mapping, the callback function func will be invoked and it
will be passed the data argument, the prmap_t structure defined from
proc(4), and a name of the mapping. The way that the name is obtained
varies based on whether one calls Pmapping_iter() or
Pmapping_iter_resolved(). In both cases, the dynamic linker is consulted
to determine the file name for the mapping, if it's known. If the name is
unknown, for example an anonymous mapping, then the NULL pointer is passed
in for the name. In the case of the Pmapping_iter_resolved() function the
system tries to resolve it to a complete file system path. If that fails,
it falls back to the information from the dynamic linker, before returning
NULL in the case of not being able to find any name. For more information
on the signature of the proc_map_f, see libproc(3LIB).

The return value of func controls whether or not iteration continues. If
func returns 0 then iteration continues. If func returns non-zero then
iteration will halt and the value will be returned to the caller. Because
-1 indicates internal failure, it is recommended that the callback function
not return -1 to indicate an error itself. This allows the caller to
distinguish between failure of the callback function versus failure of the
Pmapping_iter() and Pmapping_iter_resolved() functions.

The Pobject_iter() and Pobject_iter_resolved() functions are similar to the
Pmapping_iter() and Pmapping_iter_resolved() functions. Except, rather
than iterating over every mapping, they iterate over the objects that the
process has loaded by the dynamic linker. For example, an anonymous
mapping will show up when iterating mappings, but will not show up when
iterating objects. Further, while most dynamic shared objects have
multiple mappings for the text and data sections, there will only be a
single object that is iterated over.

The distinction between the Pobject_iter() and Pobject_iter_resolved()
functions is identical to the difference in name resolution between the
Pmapping_iter() and Pmapping_iter_resolved() functions.

RETURN VALUES


Upon successful completion, the Pmapping_iter(), Pmapping_iter_resolved()
Pobject_iter(), and Pobject_iter_resolved() functions return 0. Otherwise,
if there was an internal error then -1 is returned. Otherwise, if the
callback function func returns non-zero, then its return value will be
returned instead.

INTERFACE STABILITY


Uncommitted

MT-LEVEL
See LOCKING in libproc(3LIB).

SEE ALSO


libproc(3LIB), proc(4)

illumos May 11, 2016 illumos