| blob | 69e893a330282f57dbf0351d91b943cb6e5e032b |
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 PSYMBOL_ITER 3PROC
16 .Os
17 .Sh NAME
18 .Nm Psymbol_iter ,
19 .Nm Psymbol_iter_by_addr ,
20 .Nm Psymbol_iter_by_lmid ,
21 .Nm Psymbol_iter_by_name ,
22 .Nm Pxsymbol_iter
23 .Nd iterate symbols in a process
24 .Sh LIBRARY
25 .Lb libproc
26 .Sh SYNOPSIS
27 .In libproc.h
28 .Ft int
29 .Fo Psymbol_iter
30 .Fa "struct ps_prochandle *P"
31 .Fa "const char *object_name"
32 .Fa "int which"
33 .Fa "int mask"
34 .Fa "proc_sym_f *func"
35 .Fa "void *data"
36 .Fc
37 .Ft int
38 .Fo Psymbol_iter_by_addr
39 .Fa "struct ps_prochandle *P"
40 .Fa "const char *object_name"
41 .Fa "int which"
42 .Fa "int mask"
43 .Fa "proc_sym_f *func"
44 .Fa "void *data"
45 .Fc
46 .Ft int
47 .Fo Psymbol_iter_by_lmid
48 .Fa "struct ps_prochandle *P"
49 .Fa "Lmid_t lmid"
50 .Fa "const char *object_name"
51 .Fa "int which"
52 .Fa "int mask"
53 .Fa "proc_sym_f *func"
54 .Fa "void *data"
55 .Fc
56 .Ft int
57 .Fo Psymbol_iter_by_name
58 .Fa "struct ps_prochandle *P"
59 .Fa "const char *object_name"
60 .Fa "int which"
61 .Fa "int mask"
62 .Fa "proc_sym_f *func"
63 .Fa "void *data"
64 .Fc
65 .Ft int
66 .Fo Pxsymbol_iter
67 .Fa "struct ps_prochandle *P"
68 .Fa "Lmid_t lmid"
69 .Fa "const char *object_name"
70 .Fa "int which"
71 .Fa "int mask"
72 .Fa "proc_xsym_f *func"
73 .Fa "void *data"
74 .Fc
75 .Sh DESCRIPTION
76 The
77 .Fn Psymbol_iter ,
78 .Fn Psymbol_iter_by_addr ,
79 .Fn Psymbol_iter_by_lmid ,
80 .Fn Psymbol_iter_by_name ,
81 and
82 .Fn Pxsymbol_iter
83 functions are used to iterate over the symbols present in the process
84 referred to by the handle
85 .Fa P .
86 For each symbol found, the callback function
87 .Fa func
88 will be called once and the argument
89 .Fa data
90 will be passed to it along with an ELF symbol entry in the form of the
91 .Sy GElf_Sym
92 along with the name of the symbol, if known.
93 In the case of the
94 .Fn Pxsymbol_iter
95 function an additional
96 .Sy prsyminfo_t
97 argument will be provided to the callback.
98 The definitions of
99 .Sy proc_sym_f ,
100 .Sy proc_xsym_f ,
101 and
102 .Sy prsyminfo_t
103 are found in
104 .Xr libproc 3LIB .
105 .Pp
106 The
107 .Fa object_name
108 argument names the object that is a part of the controlled process which
109 will be searched for symbols.
110 Only one object may be searched at any given time.
111 Valid object names may be obtained through the
112 .Xr Pobjname 3PROC
113 and
114 .Xr Pobject_iter 3PROC
115 functions, among others.
116 The system also has two special object names that may be passed in to refer to
117 the objects of the executable file and for ld.so.1.
118 The symbol
119 .Dv PR_OBJ_EXEC
120 refers to the executables object and the symbol
121 .Dv PR_OBJ_LDSO
122 refers to the object ld.so.1.
123 .Pp
124 The
125 .Fa which
126 argument controls which of two possible symbol tables will be searched.
127 If the argument is
128 .Dv PR_SYMTAB
129 then the ELF symbol table will be searched.
130 Otherwise, if it is
131 .Dv PR_DYNSYM
132 then the symbol table associated with the dynamic section will be
133 searched instead.
134 If any other value is specified for
135 .Fa which ,
136 then an error will be returned.
137 .Pp
138 The
139 .Fa mask
140 argument controls which symbols will be included.
141 The
142 .Fa mask
143 argument allows for control over both the symbol's binding and the
144 symbol's type.
145 These flags logically correspond to the various ELF symbol bindings and types.
146 The following values may be passed as a bitwise-inclusive-OR into the
147 .Fa flags
148 argument:
149 .Bl -tag -width Dv -offset indent
150 .It Dv BIND_LOCAL
151 The symbol is a local symbol.
152 Local symbols are not visible outside of their object file.
153 .It Dv BIND_GLOBAL
154 The symbol is a global symbol.
155 Global symbols are visible outside of their object file and may be referred to
156 by other ELF objects.
157 .It Dv BIND_WEAK
158 The symbol is a weak symbol.
159 Weak symbols are visible outside of their object file, but another definition of
160 the symbol may be used instead.
161 .It Dv BIND_ANY
162 This is a combination of
163 .Dv BIND_LOCAL ,
164 .Dv BIND_GLOBAL ,
165 and
166 .Dv BIND_WEAK .
167 Every symbol's binding will match this value.
168 .It Dv TYPE_NOTYPE
169 The symbol's type is not specified.
170 .It Dv TYPE_OBJECT
171 The symbol refers to a data object.
172 For example, variables.
173 .It Dv TYPE_FUNC
174 The symbol refers to a function.
175 .It Dv TYPE_SECTION
176 The symbol refers to an ELF section.
177 .It Dv TYPE_FILE
178 The symbol refers to the name of a source file associated with an object
179 file.
180 .It Dv TYPE_ANY
181 This is a combination of
182 .Dv TYPE_NOTYPE ,
183 .Dv TYPE_OBJECT ,
184 .Dv TYPE_FUNC ,
185 .Dv TYPE_SECTION ,
186 and
187 .Dv TYPE_FILE .
188 Every symbol's type will match this value.
189 .El
190 .Pp
191 To obtain all of the symbols in an object, the caller would pass the
192 expression
193 .Dv BIND_ANY |
194 .Dv TYPE_ANY
195 in as the value of
196 .Fa mask.
197 .Pp
198 The
199 .Fn Psymbol_iter_by_lmid
200 and
201 .Fn Pxsymbol_iter
202 functions allow for a link-map identifier to be specified in the
203 .Fa lmid
204 argument.
205 This will restrict the search for the object specified in
206 .Fa object_name
207 to the specified link-map.
208 There are three special link-map identifiers that may be passed in.
209 The symbol
210 .Dv PR_LMID_EVERY
211 indicates that every link-map should be searched.
212 The symbol
213 .Dv LM_ID_BASE
214 indicates that the base link-map, the one that is used for the
215 executable should be searched.
216 Finally, the symbol
217 .Dv LM_ID_LDSO
218 refers to the link-map that is used by the run-time link editor, ld.so.1.
219 The functions which do not allow a link-map identifier to be specified always
220 search every link-map.
221 .Pp
222 By default, symbols are iterated based on the order of the symbol
223 table being searched.
224 However, it is also possible to iterate based on the name of the symbol and
225 based on the address of the symbol.
226 To iterate by name use the
227 .Fn Psymbol_iter_by_name
228 function.
229 To iterate by address use the
230 .Fn Psymbol_iter_by_addr
231 function.
232 The
233 .Fn Psymbol_iter ,
234 .Fn Psymbol_iter_by_lmid ,
235 and
236 .Fn Pxsymbol_iter
237 functions all sort based on the order of the symbol table.
238 .Pp
239 The return value of the callback function
240 .Fa func
241 determines whether or not iteration continues.
242 If
243 .Fa func
244 returns
245 .Sy 0,
246 then iteration will continue.
247 However, if
248 .Fa func
249 returns non-zero, then iteration will halt and that value will be used
250 as the return value of the
251 .Fn Psymbol_iter ,
252 .Fn Psymbol_iter_by_addr ,
253 .Fn Psymbol_iter_by_lmid ,
254 .Fn Psymbol_iter_by_name ,
255 and
256 .Fn Pxsymbol_iter
257 functions.
258 Because these functions return
259 .Sy -1
260 on internal failure, it is recommended that the callback function not return
261 .Sy -1
262 to indicate an error so that the caller may distinguish between the
263 failure of the callback function and the failure of these functions.
264 .Sh RETURN VALUES
265 Upon successful completion, the
266 .Fn Psymbol_iter ,
267 .Fn Psymbol_iter_by_addr ,
268 .Fn Psymbol_iter_by_lmid ,
269 .Fn Psymbol_iter_by_name ,
270 and
271 .Fn Pxsymbol_iter
272 functions return
273 .Sy 0 .
274 If there was an internal error then
275 .Sy -1
276 is returned.
277 Otherwise, if the callback function
278 .Fa func
279 returns non-zero, then its return value will be returned instead.
280 .Sh INTERFACE STABILITY
281 .Sy Uncommitted
282 .Sh MT-LEVEL
283 See
284 .Sy LOCKING
285 in
286 .Xr libproc 3LIB .
287 .Sh SEE ALSO
288 .Xr elf 3ELF ,
289 .Xr gelf 3ELF ,
290 .Xr libproc 3LIB ,
291 .Xr proc 4