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