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