tmach-symbol.3 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tmach-symbol.3 (7776B)
---
1 .TH MACH-SYMBOL 3
2 .SH NAME
3 symopen, symclose, findhdr, indexsym, lookupsym, findsym,
4 findexsym, flookupsym, ffindsym,
5 lookuplsym, indexlsym, findlsym,
6 symoff, pc2file, file2pc, line2pc, fnbound, fileline,
7 pc2line \- symbol table access functions
8 .SH SYNOPSIS
9 .B #include <u.h>
10 .br
11 .B #include <libc.h>
12 .br
13 .B #include <mach.h>
14 .PP
15 .ta \w'\fBxxxxxxxx'u +\w'\fBxxxxxx'u
16 .ft B
17 int symopen(Fhdr *hdr)
18 .br
19 void symclose(Fhdr *hdr)
20 .br
21 Fhdr *findhdr(char *name)
22 .br
23 extern Fhdr* fhdrlist;
24 .PP
25 .ft B
26 int indexsym(uint n, Symbol *s)
27 .br
28 int lookupsym(char *fn, char *var, Symbol *s)
29 .br
30 int findsym(Loc loc, uint class, Symbol *s)
31 .PP
32 .ft B
33 int findexsym(Fhdr *hdr, uint n, Symbol *s)
34 .br
35 Symbol *flookupsym(Fhdr *hdr, char *name)
36 .br
37 Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class)
38 .PP
39 .ft B
40 int indexlsym(Symbol *s1, uint n, Symbol *s2)
41 .br
42 int lookuplsym(Symbol *s1, char *name, Symbol *s2)
43 .br
44 int findlsym(Symbol *s1, Loc loc, Symbol *s2)
45 .PP
46 .ft B
47 int symoff(char *a, uint n, ulong addr, uint class)
48 .PP
49 .ft B
50 int pc2file(ulong pc, char *file, uint n, ulong *line)
51 .br
52 int pc2line(ulong pc, ulong *line)
53 .br
54 int fileline(ulong pc, char *buf, uint n)
55 .br
56 int file2pc(char *file, ulong line, ulong *pc)
57 .br
58 int line2pc(ulong basepc, ulong line, ulong *pc)
59 .br
60 int fnbound(ulong pc, ulong bounds[2])
61 .SH DESCRIPTION
62 These functions provide machine-independent access to the
63 symbol table of an executable file or executing process.
64 .MR Mach (3) ,
65 .MR mach-file (3) ,
66 and
67 .MR mach-map (3)
68 describe additional library functions for
69 accessing executable files and executing processes.
70 .PP
71 .IR Symopen
72 uses the data in the
73 .B Fhdr
74 structure filled by
75 .I crackhdr
76 (see
77 .MR mach-file (3) )
78 to initialize in-memory structures used to access the symbol
79 tables contained in the file.
80 .IR Symclose
81 frees the structures.
82 The rest of the functions described here access a composite
83 symbol table made up of all currently open tables.
84 .PP
85 The set of all currently open
86 .BR Fhdr s
87 is maintained as a linked list starting at
88 .I fhdrlist
89 (chained via
90 .BR Fhdr.next ).
91 .PP
92 .I Findhdr
93 searches the currently open
94 .BR Fhdr s
95 for one whose file name ends with the path
96 .I name
97 (that is,
98 .B libc.so
99 matches
100 .B /usr/lib/libc.so
101 but not
102 .BR mylibc.so ).
103 .PP
104 The
105 .B Symbol
106 data structure:
107 .IP
108 .RS
109 .ft B
110 .nf
111 typedef struct Symbol Symbol;
112 struct Symbol
113 {
114 char *name;
115 Loc loc;
116 Loc hiloc;
117 char class;
118 char type;
119 \fI...\fP
120 };
121 .fi
122 .RE
123 .LP
124 describes a symbol table entry.
125 The
126 .B value
127 field contains the offset of the symbol within its
128 address space: global variables relative to the beginning
129 of the data segment, text beyond the start of the text
130 segment, and automatic variables and parameters relative
131 to the stack frame. The
132 .B type
133 field contains the type of the symbol:
134 .RS
135 .TP
136 .B T
137 text segment symbol
138 .TP
139 .B t
140 static text segment symbol
141 .TP
142 .B D
143 data segment symbol
144 .TP
145 .B d
146 static data segment symbol
147 .TP
148 .B B
149 bss segment symbol
150 .TP
151 .B b
152 static bss segment symbol
153 .TP
154 .B a
155 automatic (local) variable symbol
156 .TP
157 .B p
158 function parameter symbol
159 .TP
160 .B U
161 undefined symbol
162 .RE
163 .PD
164 .LP
165 The
166 .B class
167 field assigns the symbol to a general class;
168 .BR CTEXT ,
169 .BR CDATA ,
170 .BR CAUTO ,
171 and
172 .B CPARAM
173 are the most popular.
174 .PP
175 .I Indexsym
176 stores information for the
177 .I n th
178 symbol into
179 .IR s .
180 The symbols are ordered by increasing address.
181 .PP
182 .I Lookupsym
183 fills a
184 .B Symbol
185 structure with symbol table information. Global variables
186 and functions are represented by a single name; local variables
187 and parameters are uniquely specified by a function and
188 variable name pair. Arguments
189 .I fn
190 and
191 .I var
192 contain the
193 name of a function and variable, respectively.
194 If both
195 are non-zero, the symbol table is searched for a parameter
196 or automatic variable. If only
197 .I var
198 is
199 zero, the text symbol table is searched for function
200 .IR fn .
201 If only
202 .I fn
203 is zero, the global variable table
204 is searched for
205 .IR var .
206 .PP
207 .I Findsym
208 returns the symbol table entry of type
209 .I class
210 stored near
211 .IR addr .
212 The selected symbol is a global variable or function with
213 address nearest to and less than or equal to
214 .IR addr .
215 Class specification
216 .B CDATA
217 searches only the global variable symbol table; class
218 .B CTEXT
219 limits the search to the text symbol table.
220 Class specification
221 .B CANY
222 searches the text table first, then the global table.
223 .PP
224 .IR Findexsym ,
225 .IR flookupsym ,
226 and
227 .I ffindsym
228 are similar to
229 .IR indexsym ,
230 .IR lookupsym ,
231 and
232 .IR findsym ,
233 but operate only on the symbols from
234 .IR hdr .
235 .I Flookupsym
236 and
237 .I ffindsym
238 return pointers to data stored in the
239 .IR hdr ,
240 which must not be modified or freed.
241 .PP
242 .IR Indexlsym ,
243 .IR lookuplsym ,
244 and
245 .I findlsym
246 are similar to
247 .IR indexsym ,
248 .IR lookupsym ,
249 and
250 .IR findsym ,
251 but operate on the smaller symbol table of parameters and
252 variables local to the function represented by symbol
253 .IR s1 .
254 .PP
255 .I Indexlsym
256 writes symbol information for the
257 .IR n th
258 local symbol of function
259 .I s1
260 to
261 .IR s2 .
262 Function parameters appear first in the ordering, followed by local symbols.
263 .PP
264 .I Lookuplsym
265 writes symbol information for the symbol named
266 .I name
267 in function
268 .I s1
269 to
270 .IR s2 .
271 .PP
272 .I Findlsym
273 searches for a symbol local to the function
274 .I s1
275 whose location is exactly
276 .IR loc ,
277 writing its symbol information to
278 .IR s2 .
279 .I Loc
280 is almost always an indirection through a frame pointer register;
281 the details vary from architecture to architecture.
282 .PP
283 .I Symoff
284 converts a location to a symbol reference.
285 The string containing that reference is of the form
286 `name+offset', where `name' is the name of the
287 nearest symbol with an address less than or equal to the
288 target address, and `offset' is the hexadecimal offset beyond
289 that symbol. If `offset' is zero, only the name of the
290 symbol is printed.
291 If no symbol is found within 4096 bytes of the address, the address
292 is formatted as a hexadecimal address.
293 .I Buf
294 is the address of a buffer of
295 .I n
296 bytes to receive the formatted string.
297 .I Addr
298 is the address to be converted.
299 .I Type
300 is the type code of the search space:
301 .BR CTEXT ,
302 .BR CDATA ,
303 or
304 .BR CANY .
305 .I Symoff
306 returns the length of the formatted string contained in
307 .IR buf .
308 .PP
309 .I Pc2file
310 searches the symbol table to find the file and line number
311 corresponding to the instruction at program counter
312 .IR pc .
313 .I File
314 is the address of a buffer of
315 .I n
316 bytes to receive the file name.
317 .I Line
318 receives the line number.
319 .PP
320 .I Pc2line
321 is like
322 .I pc2file
323 but neglects to return information about the source file.
324 .PP
325 .I Fileline
326 is also like
327 .IR pc2file ,
328 but returns the file and line number in the
329 .IR n -byte
330 text buffer
331 .IR buf ,
332 formatted as
333 `file:line'.
334 .PP
335 .I File2pc
336 performs the opposite mapping:
337 it stores in
338 .I pc
339 a text address associated with
340 line
341 .I line
342 in file
343 .IR file .
344 .PP
345 .I Line2pc
346 is similar: it converts a line number to an
347 instruction address, storing it in
348 .IR pc .
349 Since a line number does not uniquely identify an
350 instruction (e.g., every source file has line 1),
351 .I basepc
352 specifies a text address from which
353 the search begins.
354 Usually this is the address of the first function in the
355 file of interest.
356 .PP
357 .I Fnbound
358 returns the start and end addresses of the function containing
359 the text address supplied as the first argument.
360 The second argument is an array of two unsigned longs;
361 .I fnbound
362 places the bounding addresses of the function in the
363 first and second elements of this array.
364 The start address is the address of the first instruction of the function;
365 the end address is the first address beyond the end of the target function.
366 .PP
367 All functions return 0 on success and \-1 on error.
368 When an error occurs, a message describing it is stored
369 in the system error buffer where it is available via
370 .IR errstr .
371 .SH SOURCE
372 .B \*9/src/libmach
373 .SH "SEE ALSO"
374 .MR mach (3) ,
375 .MR mach-file (3) ,
376 .MR mach-map (3)