usr/src/man/man3proc/Pmapping_iter.3proc

.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2015 Joyent, Inc.
.\"
.Dd May 11, 2016
.Dt PMAPPING_ITER 3PROC
.Os
.Sh NAME
.Nm Pmapping_iter ,
.Nm Pmapping_iter_resolved ,
.Nm Pobject_iter ,
.Nm Pobject_iter_resolved
.Nd iterate over process mappings and objects
.Sh LIBRARY
.Lb libproc
.Sh SYNOPSIS
.In libproc.h
.Ft int
.Fo Pmapping_iter
.Fa "struct ps_prochandle *P"
.Fa "proc_map_f *func"
.Fa "void *data"
.Fc
.Ft int
.Fo Pmapping_iter_resolved
.Fa "struct ps_prochandle *P"
.Fa "proc_map_f *func"
.Fa "void *data"
.Fc
.Ft int
.Fo Pobject_iter
.Fa "struct ps_prochandle *P"
.Fa "proc_map_f *func"
.Fa "void *data"
.Fc
.Ft int
.Fo Pobject_iter_resolved
.Fa "struct ps_prochandle *P"
.Fa "proc_map_f *func"
.Fa "void *data"
.Fc
.Sh DESCRIPTION
The
.Fn Pmapping_iter
and
.Fn Pmapping_iter_resolved
functions iterate over the memory mappings in the process represented by
.Fa P.
.Pp
For each memory mapping, the callback function
.Fa func
will be invoked and it will be passed the
.Fa data
argument,
the
.Sy prmap_t
structure defined from
.Xr proc 4 ,
and a name of the mapping.
The way that the name is obtained varies based on whether one calls
.Fn Pmapping_iter
or
.Fn 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
.Dv NULL
pointer is passed in for the name.
In the case of the
.Fn 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
.Dv NULL
in the case of not being able to find any name.
For more information on the
signature of the
.Ft proc_map_f ,
see
.Xr libproc 3LIB .
.Pp
The return value of
.Fa func
controls whether or not iteration continues.
If
.Fa func
returns
.Sy 0
then iteration continues.
If
.Fa func
returns non-zero then iteration will halt and the value will be
returned to the caller.
Because
.Sy -1
indicates internal failure, it is recommended that the callback function not
return
.Sy -1
to indicate an error itself.
This allows the caller to distinguish between failure of the callback function
versus failure of the
.Fn Pmapping_iter
and
.Fn Pmapping_iter_resolved
functions.
.Pp
The
.Fn Pobject_iter
and
.Fn Pobject_iter_resolved
functions are similar to the
.Fn Pmapping_iter
and
.Fn 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.
.Pp
The distinction between the
.Fn Pobject_iter
and
.Fn Pobject_iter_resolved
functions is identical to the difference in name resolution between the
.Fn Pmapping_iter
and
.Fn Pmapping_iter_resolved
functions.
.Sh RETURN VALUES
Upon successful completion, the
.Fn Pmapping_iter ,
.Fn Pmapping_iter_resolved
.Fn Pobject_iter ,
and
.Fn Pobject_iter_resolved
functions return
.Sy 0.
Otherwise, if there was an internal error then
.Sy -1
is returned.
Otherwise, if the callback function
.Fa func
returns non-zero, then its return value will be returned instead.
.Sh INTERFACE STABILITY
.Sy Uncommitted
.Sh MT-LEVEL
See
.Sy LOCKING
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr libproc 3LIB ,
.Xr proc 4