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
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.
12 .\" Copyright 2015 Joyent, Inc.
15 .Dt PSYMBOL_ITER 3PROC
19 .Nm Psymbol_iter_by_addr ,
20 .Nm Psymbol_iter_by_lmid ,
21 .Nm Psymbol_iter_by_name ,
23 .Nd iterate symbols in a process
29 .Fa "struct ps_prochandle *P"
30 .Fa "const char *object_name"
33 .Fa "proc_sym_f *func"
37 .Fo Psymbol_iter_by_addr
38 .Fa "struct ps_prochandle *P"
39 .Fa "const char *object_name"
42 .Fa "proc_sym_f *func"
46 .Fo Psymbol_iter_by_lmid
47 .Fa "struct ps_prochandle *P"
49 .Fa "const char *object_name"
52 .Fa "proc_sym_f *func"
56 .Fo Psymbol_iter_by_name
57 .Fa "struct ps_prochandle *P"
58 .Fa "const char *object_name"
61 .Fa "proc_sym_f *func"
66 .Fa "struct ps_prochandle *P"
68 .Fa "const char *object_name"
71 .Fa "proc_xsym_f *func"
77 .Fn Psymbol_iter_by_addr ,
78 .Fn Psymbol_iter_by_lmid ,
79 .Fn Psymbol_iter_by_name ,
82 functions are used to iterate over the symbols present in the process
83 referred to by the handle
85 For each symbol found, the callback function
87 will be called once and the argument
89 will be passed to it along with an ELF symbol entry in the form of the
91 along with the name of the symbol, if known.
94 function an additional
96 argument will be provided to the callback.
107 argument names the object that is a part of the controlled process which
108 will be searched for symbols.
109 Only one object may be searched at any given time.
110 Valid object names may be obtained through the
113 .Xr Pobject_iter 3PROC
114 functions, among others.
115 The system also has two special object names that may be passed in to refer to
116 the objects of the executable file and for ld.so.1.
119 refers to the executables object and the symbol
121 refers to the object ld.so.1.
125 argument controls which of two possible symbol tables will be searched.
128 then the ELF symbol table will be searched.
131 then the symbol table associated with the dynamic section will be
133 If any other value is specified for
135 then an error will be returned.
139 argument controls which symbols will be included.
142 argument allows for control over both the symbol's binding and the
144 These flags logically correspond to the various ELF symbol bindings and types.
145 The following values may be passed as a bitwise-inclusive-OR into the
148 .Bl -tag -width Dv -offset indent
150 The symbol is a local symbol.
151 Local symbols are not visible outside of their object file.
153 The symbol is a global symbol.
154 Global symbols are visible outside of their object file and may be referred to
155 by other ELF objects.
157 The symbol is a weak symbol.
158 Weak symbols are visible outside of their object file, but another definition of
159 the symbol may be used instead.
161 This is a combination of
166 Every symbol's binding will match this value.
168 The symbol's type is not specified.
170 The symbol refers to a data object.
171 For example, variables.
173 The symbol refers to a function.
175 The symbol refers to an ELF section.
177 The symbol refers to the name of a source file associated with an object
180 This is a combination of
187 Every symbol's type will match this value.
190 To obtain all of the symbols in an object, the caller would pass the
198 .Fn Psymbol_iter_by_lmid
201 functions allow for a link-map identifier to be specified in the
204 This will restrict the search for the object specified in
206 to the specified link-map.
207 There are three special link-map identifiers that may be passed in.
210 indicates that every link-map should be searched.
213 indicates that the base link-map, the one that is used for the
214 executable should be searched.
217 refers to the link-map that is used by the run-time link editor, ld.so.1.
218 The functions which do not allow a link-map identifier to be specified always
219 search every link-map.
221 By default, symbols are iterated based on the order of the symbol
222 table being searched.
223 However, it is also possible to iterate based on the name of the symbol and
224 based on the address of the symbol.
225 To iterate by name use the
226 .Fn Psymbol_iter_by_name
228 To iterate by address use the
229 .Fn Psymbol_iter_by_addr
233 .Fn Psymbol_iter_by_lmid ,
236 functions all sort based on the order of the symbol table.
238 The return value of the callback function
240 determines whether or not iteration continues.
245 then iteration will continue.
248 returns non-zero, then iteration will halt and that value will be used
249 as the return value of the
251 .Fn Psymbol_iter_by_addr ,
252 .Fn Psymbol_iter_by_lmid ,
253 .Fn Psymbol_iter_by_name ,
257 Because these functions return
259 on internal failure, it is recommended that the callback function not return
261 to indicate an error so that the caller may distinguish between the
262 failure of the callback function and the failure of these functions.
264 Upon successful completion, the
266 .Fn Psymbol_iter_by_addr ,
267 .Fn Psymbol_iter_by_lmid ,
268 .Fn Psymbol_iter_by_name ,
273 If there was an internal error then
276 Otherwise, if the callback function
278 returns non-zero, then its return value will be returned instead.
279 .Sh INTERFACE STABILITY