1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2015 Joyent, Inc.
13.\"
14.Dd May 11, 2016
15.Dt PMAPPING_ITER 3PROC
16.Os
17.Sh NAME
18.Nm Pmapping_iter ,
19.Nm Pmapping_iter_resolved ,
20.Nm Pobject_iter ,
21.Nm Pobject_iter_resolved
22.Nd iterate over process mappings and objects
23.Sh LIBRARY
24.Lb libproc
25.Sh SYNOPSIS
26.In libproc.h
27.Ft int
28.Fo Pmapping_iter
29.Fa "struct ps_prochandle *P"
30.Fa "proc_map_f *func"
31.Fa "void *data"
32.Fc
33.Ft int
34.Fo Pmapping_iter_resolved
35.Fa "struct ps_prochandle *P"
36.Fa "proc_map_f *func"
37.Fa "void *data"
38.Fc
39.Ft int
40.Fo Pobject_iter
41.Fa "struct ps_prochandle *P"
42.Fa "proc_map_f *func"
43.Fa "void *data"
44.Fc
45.Ft int
46.Fo Pobject_iter_resolved
47.Fa "struct ps_prochandle *P"
48.Fa "proc_map_f *func"
49.Fa "void *data"
50.Fc
51.Sh DESCRIPTION
52The
53.Fn Pmapping_iter
54and
55.Fn Pmapping_iter_resolved
56functions iterate over the memory mappings in the process represented by
57.Fa P.
58.Pp
59For each memory mapping, the callback function
60.Fa func
61will be invoked and it will be passed the
62.Fa data
63argument,
64the
65.Sy prmap_t
66structure defined from
67.Xr proc 5 ,
68and a name of the mapping.
69The way that the name is obtained varies based on whether one calls
70.Fn Pmapping_iter
71or
72.Fn Pmapping_iter_resolved .
73In both cases, the dynamic linker is consulted to determine the file
74name for the mapping, if it's known.
75If the name is unknown, for example an anonymous mapping, then the
76.Dv NULL
77pointer is passed in for the name.
78In the case of the
79.Fn Pmapping_iter_resolved
80function the system tries to resolve it to a complete file system path.
81If that fails, it falls back to the information from the dynamic linker,
82before returning
83.Dv NULL
84in the case of not being able to find any name.
85For more information on the
86signature of the
87.Ft proc_map_f ,
88see
89.Xr libproc 3LIB .
90.Pp
91The return value of
92.Fa func
93controls whether or not iteration continues.
94If
95.Fa func
96returns
97.Sy 0
98then iteration continues.
99If
100.Fa func
101returns non-zero then iteration will halt and the value will be
102returned to the caller.
103Because
104.Sy -1
105indicates internal failure, it is recommended that the callback function not
106return
107.Sy -1
108to indicate an error itself.
109This allows the caller to distinguish between failure of the callback function
110versus failure of the
111.Fn Pmapping_iter
112and
113.Fn Pmapping_iter_resolved
114functions.
115.Pp
116The
117.Fn Pobject_iter
118and
119.Fn Pobject_iter_resolved
120functions are similar to the
121.Fn Pmapping_iter
122and
123.Fn Pmapping_iter_resolved
124functions.
125Except, rather than iterating over every mapping, they iterate over the objects
126that the process has loaded by the dynamic linker.
127For example, an anonymous mapping will show up when iterating mappings, but will
128not show up when iterating objects.
129Further, while most dynamic shared objects have multiple mappings for the text
130and data sections, there will only be a single object that is iterated over.
131.Pp
132The distinction between the
133.Fn Pobject_iter
134and
135.Fn Pobject_iter_resolved
136functions is identical to the difference in name resolution between the
137.Fn Pmapping_iter
138and
139.Fn Pmapping_iter_resolved
140functions.
141.Sh RETURN VALUES
142Upon successful completion, the
143.Fn Pmapping_iter ,
144.Fn Pmapping_iter_resolved
145.Fn Pobject_iter ,
146and
147.Fn Pobject_iter_resolved
148functions return
149.Sy 0.
150Otherwise, if there was an internal error then
151.Sy -1
152is returned.
153Otherwise, if the callback function
154.Fa func
155returns non-zero, then its return value will be returned instead.
156.Sh INTERFACE STABILITY
157.Sy Uncommitted
158.Sh MT-LEVEL
159See
160.Sy LOCKING
161in
162.Xr libproc 3LIB .
163.Sh SEE ALSO
164.Xr libproc 3LIB ,
165.Xr proc 5
166