1 bf8a59fa 2004-04-11 devnull .TH MACH-SYMBOL 3
3 bf8a59fa 2004-04-11 devnull symopen, symclose, indexsym, lookupsym, findsym,
4 bf8a59fa 2004-04-11 devnull lookuplsym, indexlsym, findlsym,
5 bf8a59fa 2004-04-11 devnull symoff, pc2file, file2pc, line2pc, fnbound, fileline,
6 bf8a59fa 2004-04-11 devnull pc2line \- symbol table access functions
7 bf8a59fa 2004-04-11 devnull .SH SYNOPSIS
8 bf8a59fa 2004-04-11 devnull .B #include <u.h>
10 bf8a59fa 2004-04-11 devnull .B #include <libc.h>
12 bf8a59fa 2004-04-11 devnull .B #include <mach.h>
14 bf8a59fa 2004-04-11 devnull .ta \w'\fBxxxxxx'u +\w'\fBxxxxxx'u
16 bf8a59fa 2004-04-11 devnull int symopen(Fhdr *hdr)
18 bf8a59fa 2004-04-11 devnull void symclose(Fhdr *hdr)
21 bf8a59fa 2004-04-11 devnull int indexsym(uint n, Symbol *s)
23 bf8a59fa 2004-04-11 devnull int lookupsym(char *fn, char *var, Symbol *s)
25 bf8a59fa 2004-04-11 devnull int findsym(Loc loc, uint class, Symbol *s)
28 bf8a59fa 2004-04-11 devnull int indexlsym(Symbol *s1, uint n, Symbol *s2)
30 bf8a59fa 2004-04-11 devnull int lookuplsym(Symbol *s1, char *name, Symbol *s2)
32 bf8a59fa 2004-04-11 devnull int findlsym(Symbol *s1, Loc loc, Symbol *s2)
35 bf8a59fa 2004-04-11 devnull int symoff(char *a, uint n, ulong addr, uint class)
38 bf8a59fa 2004-04-11 devnull int pc2file(ulong pc, char *file, uint n, ulong *line)
40 bf8a59fa 2004-04-11 devnull int pc2line(ulong pc, ulong *line)
42 bf8a59fa 2004-04-11 devnull int fileline(ulong pc, char *buf, uint n)
44 bf8a59fa 2004-04-11 devnull int file2pc(char *file, ulong line, ulong *pc)
46 bf8a59fa 2004-04-11 devnull int line2pc(ulong basepc, ulong line, ulong *pc)
48 bf8a59fa 2004-04-11 devnull int fnbound(ulong pc, ulong bounds[2])
49 bf8a59fa 2004-04-11 devnull .SH DESCRIPTION
50 bf8a59fa 2004-04-11 devnull These functions provide machine-independent access to the
51 bf8a59fa 2004-04-11 devnull symbol table of an executable file or executing process.
52 bf8a59fa 2004-04-11 devnull .IR Mach (3),
53 bf8a59fa 2004-04-11 devnull .IR mach-file (3),
55 bf8a59fa 2004-04-11 devnull .IR mach-map (3)
56 bf8a59fa 2004-04-11 devnull describe additional library functions for
57 bf8a59fa 2004-04-11 devnull accessing executable files and executing processes.
59 bf8a59fa 2004-04-11 devnull .IR Symopen
60 bf8a59fa 2004-04-11 devnull uses the data in the
62 bf8a59fa 2004-04-11 devnull structure filled by
63 bf8a59fa 2004-04-11 devnull .I crackhdr
65 bf8a59fa 2004-04-11 devnull .IR mach-file (3))
66 bf8a59fa 2004-04-11 devnull to initialize in-memory structures used to access the symbol
67 bf8a59fa 2004-04-11 devnull tables contained in the file.
68 bf8a59fa 2004-04-11 devnull .IR Symclose
69 bf8a59fa 2004-04-11 devnull frees the structures.
70 bf8a59fa 2004-04-11 devnull The rest of the functions described here access a composite
71 bf8a59fa 2004-04-11 devnull symbol table made up of all currently open tables.
74 bf8a59fa 2004-04-11 devnull .B Symbol
75 bf8a59fa 2004-04-11 devnull data structure:
80 bf8a59fa 2004-04-11 devnull typedef struct Symbol Symbol;
81 bf8a59fa 2004-04-11 devnull struct Symbol
83 bf8a59fa 2004-04-11 devnull char *name;
85 bf8a59fa 2004-04-11 devnull Loc hiloc;
86 bf8a59fa 2004-04-11 devnull char class;
87 bf8a59fa 2004-04-11 devnull char type;
88 bf8a59fa 2004-04-11 devnull \fI...\fP
93 bf8a59fa 2004-04-11 devnull describes a symbol table entry.
96 bf8a59fa 2004-04-11 devnull field contains the offset of the symbol within its
97 bf8a59fa 2004-04-11 devnull address space: global variables relative to the beginning
98 bf8a59fa 2004-04-11 devnull of the data segment, text beyond the start of the text
99 bf8a59fa 2004-04-11 devnull segment, and automatic variables and parameters relative
100 bf8a59fa 2004-04-11 devnull to the stack frame. The
102 bf8a59fa 2004-04-11 devnull field contains the type of the symbol:
106 bf8a59fa 2004-04-11 devnull text segment symbol
109 bf8a59fa 2004-04-11 devnull static text segment symbol
112 bf8a59fa 2004-04-11 devnull data segment symbol
115 bf8a59fa 2004-04-11 devnull static data segment symbol
118 bf8a59fa 2004-04-11 devnull bss segment symbol
121 bf8a59fa 2004-04-11 devnull static bss segment symbol
124 bf8a59fa 2004-04-11 devnull automatic (local) variable symbol
127 bf8a59fa 2004-04-11 devnull function parameter symbol
130 905ca4e6 2004-04-19 devnull undefined symbol
135 bf8a59fa 2004-04-11 devnull .B class
136 bf8a59fa 2004-04-11 devnull field assigns the symbol to a general class;
137 bf8a59fa 2004-04-11 devnull .BR CTEXT ,
138 bf8a59fa 2004-04-11 devnull .BR CDATA ,
139 bf8a59fa 2004-04-11 devnull .BR CAUTO ,
141 bf8a59fa 2004-04-11 devnull .B CPARAM
142 bf8a59fa 2004-04-11 devnull are the most popular.
144 bf8a59fa 2004-04-11 devnull .I Indexsym
145 bf8a59fa 2004-04-11 devnull stores information for the
147 bf8a59fa 2004-04-11 devnull symbol into
149 bf8a59fa 2004-04-11 devnull The symbols are ordered by increasing address.
151 bf8a59fa 2004-04-11 devnull .I Lookupsym
153 bf8a59fa 2004-04-11 devnull .B Symbol
154 bf8a59fa 2004-04-11 devnull structure with symbol table information. Global variables
155 bf8a59fa 2004-04-11 devnull and functions are represented by a single name; local variables
156 bf8a59fa 2004-04-11 devnull and parameters are uniquely specified by a function and
157 bf8a59fa 2004-04-11 devnull variable name pair. Arguments
161 bf8a59fa 2004-04-11 devnull contain the
162 bf8a59fa 2004-04-11 devnull name of a function and variable, respectively.
164 bf8a59fa 2004-04-11 devnull are non-zero, the symbol table is searched for a parameter
165 bf8a59fa 2004-04-11 devnull or automatic variable. If only
168 bf8a59fa 2004-04-11 devnull zero, the text symbol table is searched for function
169 bf8a59fa 2004-04-11 devnull .IR fn .
172 bf8a59fa 2004-04-11 devnull is zero, the global variable table
173 bf8a59fa 2004-04-11 devnull is searched for
174 bf8a59fa 2004-04-11 devnull .IR var .
176 bf8a59fa 2004-04-11 devnull .I Findsym
177 bf8a59fa 2004-04-11 devnull returns the symbol table entry of type
178 bf8a59fa 2004-04-11 devnull .I class
179 bf8a59fa 2004-04-11 devnull stored near
180 bf8a59fa 2004-04-11 devnull .IR addr .
181 bf8a59fa 2004-04-11 devnull The selected symbol is a global variable or function with
182 bf8a59fa 2004-04-11 devnull address nearest to and less than or equal to
183 bf8a59fa 2004-04-11 devnull .IR addr .
184 bf8a59fa 2004-04-11 devnull Class specification
185 bf8a59fa 2004-04-11 devnull .B CDATA
186 bf8a59fa 2004-04-11 devnull searches only the global variable symbol table; class
187 bf8a59fa 2004-04-11 devnull .B CTEXT
188 bf8a59fa 2004-04-11 devnull limits the search to the text symbol table.
189 bf8a59fa 2004-04-11 devnull Class specification
191 bf8a59fa 2004-04-11 devnull searches the text table first, then the global table.
193 bf8a59fa 2004-04-11 devnull .IR Indexlsym ,
194 bf8a59fa 2004-04-11 devnull .IR lookuplsym ,
196 bf8a59fa 2004-04-11 devnull .IR findlsym
197 bf8a59fa 2004-04-11 devnull are similar to
198 bf8a59fa 2004-04-11 devnull .IR indexsym ,
199 bf8a59fa 2004-04-11 devnull .IR lookupsym ,
201 bf8a59fa 2004-04-11 devnull .IR findsym ,
202 bf8a59fa 2004-04-11 devnull but operate on the smaller symbol table of parameters and
203 bf8a59fa 2004-04-11 devnull variables local to the function represented by symbol
204 bf8a59fa 2004-04-11 devnull .IR s1 .
206 bf8a59fa 2004-04-11 devnull .I Indexlsym
207 bf8a59fa 2004-04-11 devnull writes symbol information for the
208 bf8a59fa 2004-04-11 devnull .IR n th
209 bf8a59fa 2004-04-11 devnull local symbol of function
212 bf8a59fa 2004-04-11 devnull .IR s2 .
213 bf8a59fa 2004-04-11 devnull Function parameters appear first in the ordering, followed by local symbols.
215 bf8a59fa 2004-04-11 devnull .I Lookuplsym
216 bf8a59fa 2004-04-11 devnull writes symbol information for the symbol named
218 bf8a59fa 2004-04-11 devnull in function
221 bf8a59fa 2004-04-11 devnull .IR s2 .
223 bf8a59fa 2004-04-11 devnull .I Findlsym
224 bf8a59fa 2004-04-11 devnull searches for a symbol local to the function
226 bf8a59fa 2004-04-11 devnull whose location is exactly
227 bf8a59fa 2004-04-11 devnull .IR loc ,
228 bf8a59fa 2004-04-11 devnull writing its symbol information to
229 bf8a59fa 2004-04-11 devnull .IR s2 .
231 bf8a59fa 2004-04-11 devnull is almost always an indirection through a frame pointer register;
232 bf8a59fa 2004-04-11 devnull the details vary from architecture to architecture.
234 bf8a59fa 2004-04-11 devnull .I Symoff
235 bf8a59fa 2004-04-11 devnull converts a location to a symbol reference.
236 bf8a59fa 2004-04-11 devnull The string containing that reference is of the form
237 bf8a59fa 2004-04-11 devnull `name+offset', where `name' is the name of the
238 bf8a59fa 2004-04-11 devnull nearest symbol with an address less than or equal to the
239 bf8a59fa 2004-04-11 devnull target address, and `offset' is the hexadecimal offset beyond
240 bf8a59fa 2004-04-11 devnull that symbol. If `offset' is zero, only the name of the
241 bf8a59fa 2004-04-11 devnull symbol is printed.
242 bf8a59fa 2004-04-11 devnull If no symbol is found within 4096 bytes of the address, the address
243 bf8a59fa 2004-04-11 devnull is formatted as a hexadecimal address.
245 bf8a59fa 2004-04-11 devnull is the address of a buffer of
247 bf8a59fa 2004-04-11 devnull bytes to receive the formatted string.
249 bf8a59fa 2004-04-11 devnull is the address to be converted.
251 bf8a59fa 2004-04-11 devnull is the type code of the search space:
252 bf8a59fa 2004-04-11 devnull .BR CTEXT ,
253 bf8a59fa 2004-04-11 devnull .BR CDATA ,
255 bf8a59fa 2004-04-11 devnull .BR CANY .
256 bf8a59fa 2004-04-11 devnull .I Symoff
257 bf8a59fa 2004-04-11 devnull returns the length of the formatted string contained in
258 bf8a59fa 2004-04-11 devnull .IR buf .
260 bf8a59fa 2004-04-11 devnull .I Pc2file
261 bf8a59fa 2004-04-11 devnull searches the symbol table to find the file and line number
262 bf8a59fa 2004-04-11 devnull corresponding to the instruction at program counter
263 bf8a59fa 2004-04-11 devnull .IR pc .
265 bf8a59fa 2004-04-11 devnull is the address of a buffer of
267 bf8a59fa 2004-04-11 devnull bytes to receive the file name.
269 bf8a59fa 2004-04-11 devnull receives the line number.
271 bf8a59fa 2004-04-11 devnull .I Pc2line
273 bf8a59fa 2004-04-11 devnull .I pc2file
274 bf8a59fa 2004-04-11 devnull but neglects to return information about the source file.
276 bf8a59fa 2004-04-11 devnull .I Fileline
277 bf8a59fa 2004-04-11 devnull is also like
278 bf8a59fa 2004-04-11 devnull .IR pc2file ,
279 bf8a59fa 2004-04-11 devnull but returns the file and line number in the
280 bf8a59fa 2004-04-11 devnull .IR n -byte
281 bf8a59fa 2004-04-11 devnull text buffer
282 bf8a59fa 2004-04-11 devnull .IR buf ,
283 bf8a59fa 2004-04-11 devnull formatted as
284 bf8a59fa 2004-04-11 devnull `file:line'.
286 bf8a59fa 2004-04-11 devnull .I File2pc
287 bf8a59fa 2004-04-11 devnull performs the opposite mapping:
288 bf8a59fa 2004-04-11 devnull it stores in
290 bf8a59fa 2004-04-11 devnull a text address associated with
294 bf8a59fa 2004-04-11 devnull .IR file .
296 bf8a59fa 2004-04-11 devnull .I Line2pc
297 bf8a59fa 2004-04-11 devnull is similar: it converts a line number to an
298 bf8a59fa 2004-04-11 devnull instruction address, storing it in
299 bf8a59fa 2004-04-11 devnull .IR pc .
300 bf8a59fa 2004-04-11 devnull Since a line number does not uniquely identify an
301 bf8a59fa 2004-04-11 devnull instruction (e.g., every source file has line 1),
302 bf8a59fa 2004-04-11 devnull .I basepc
303 bf8a59fa 2004-04-11 devnull specifies a text address from which
304 bf8a59fa 2004-04-11 devnull the search begins.
305 bf8a59fa 2004-04-11 devnull Usually this is the address of the first function in the
306 bf8a59fa 2004-04-11 devnull file of interest.
308 bf8a59fa 2004-04-11 devnull .I Fnbound
309 bf8a59fa 2004-04-11 devnull returns the start and end addresses of the function containing
310 bf8a59fa 2004-04-11 devnull the text address supplied as the first argument.
311 bf8a59fa 2004-04-11 devnull The second argument is an array of two unsigned longs;
312 bf8a59fa 2004-04-11 devnull .I fnbound
313 bf8a59fa 2004-04-11 devnull places the bounding addresses of the function in the
314 bf8a59fa 2004-04-11 devnull first and second elements of this array.
315 bf8a59fa 2004-04-11 devnull The start address is the address of the first instruction of the function;
316 bf8a59fa 2004-04-11 devnull the end address is the first address beyond the end of the target function.
318 bf8a59fa 2004-04-11 devnull All functions return 0 on success and \-1 on error.
319 bf8a59fa 2004-04-11 devnull When an error occurs, a message describing it is stored
320 bf8a59fa 2004-04-11 devnull in the system error buffer where it is available via
321 bf8a59fa 2004-04-11 devnull .IR errstr .
322 bf8a59fa 2004-04-11 devnull .SH SOURCE
323 bf8a59fa 2004-04-11 devnull .B /sys/src/libmach
324 bf8a59fa 2004-04-11 devnull .SH "SEE ALSO"
325 bf8a59fa 2004-04-11 devnull .IR mach (3),
326 bf8a59fa 2004-04-11 devnull .IR mach-file (3),
327 bf8a59fa 2004-04-11 devnull .IR mach-map (3)
