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
132 bf8a59fa 2004-04-11 devnull .B class
133 bf8a59fa 2004-04-11 devnull field assigns the symbol to a general class;
134 bf8a59fa 2004-04-11 devnull .BR CTEXT ,
135 bf8a59fa 2004-04-11 devnull .BR CDATA ,
136 bf8a59fa 2004-04-11 devnull .BR CAUTO ,
138 bf8a59fa 2004-04-11 devnull .B CPARAM
139 bf8a59fa 2004-04-11 devnull are the most popular.
141 bf8a59fa 2004-04-11 devnull .I Indexsym
142 bf8a59fa 2004-04-11 devnull stores information for the
144 bf8a59fa 2004-04-11 devnull symbol into
146 bf8a59fa 2004-04-11 devnull The symbols are ordered by increasing address.
148 bf8a59fa 2004-04-11 devnull .I Lookupsym
150 bf8a59fa 2004-04-11 devnull .B Symbol
151 bf8a59fa 2004-04-11 devnull structure with symbol table information. Global variables
152 bf8a59fa 2004-04-11 devnull and functions are represented by a single name; local variables
153 bf8a59fa 2004-04-11 devnull and parameters are uniquely specified by a function and
154 bf8a59fa 2004-04-11 devnull variable name pair. Arguments
158 bf8a59fa 2004-04-11 devnull contain the
159 bf8a59fa 2004-04-11 devnull name of a function and variable, respectively.
161 bf8a59fa 2004-04-11 devnull are non-zero, the symbol table is searched for a parameter
162 bf8a59fa 2004-04-11 devnull or automatic variable. If only
165 bf8a59fa 2004-04-11 devnull zero, the text symbol table is searched for function
166 bf8a59fa 2004-04-11 devnull .IR fn .
169 bf8a59fa 2004-04-11 devnull is zero, the global variable table
170 bf8a59fa 2004-04-11 devnull is searched for
171 bf8a59fa 2004-04-11 devnull .IR var .
173 bf8a59fa 2004-04-11 devnull .I Findsym
174 bf8a59fa 2004-04-11 devnull returns the symbol table entry of type
175 bf8a59fa 2004-04-11 devnull .I class
176 bf8a59fa 2004-04-11 devnull stored near
177 bf8a59fa 2004-04-11 devnull .IR addr .
178 bf8a59fa 2004-04-11 devnull The selected symbol is a global variable or function with
179 bf8a59fa 2004-04-11 devnull address nearest to and less than or equal to
180 bf8a59fa 2004-04-11 devnull .IR addr .
181 bf8a59fa 2004-04-11 devnull Class specification
182 bf8a59fa 2004-04-11 devnull .B CDATA
183 bf8a59fa 2004-04-11 devnull searches only the global variable symbol table; class
184 bf8a59fa 2004-04-11 devnull .B CTEXT
185 bf8a59fa 2004-04-11 devnull limits the search to the text symbol table.
186 bf8a59fa 2004-04-11 devnull Class specification
188 bf8a59fa 2004-04-11 devnull searches the text table first, then the global table.
190 bf8a59fa 2004-04-11 devnull .IR Indexlsym ,
191 bf8a59fa 2004-04-11 devnull .IR lookuplsym ,
193 bf8a59fa 2004-04-11 devnull .IR findlsym
194 bf8a59fa 2004-04-11 devnull are similar to
195 bf8a59fa 2004-04-11 devnull .IR indexsym ,
196 bf8a59fa 2004-04-11 devnull .IR lookupsym ,
198 bf8a59fa 2004-04-11 devnull .IR findsym ,
199 bf8a59fa 2004-04-11 devnull but operate on the smaller symbol table of parameters and
200 bf8a59fa 2004-04-11 devnull variables local to the function represented by symbol
201 bf8a59fa 2004-04-11 devnull .IR s1 .
203 bf8a59fa 2004-04-11 devnull .I Indexlsym
204 bf8a59fa 2004-04-11 devnull writes symbol information for the
205 bf8a59fa 2004-04-11 devnull .IR n th
206 bf8a59fa 2004-04-11 devnull local symbol of function
209 bf8a59fa 2004-04-11 devnull .IR s2 .
210 bf8a59fa 2004-04-11 devnull Function parameters appear first in the ordering, followed by local symbols.
212 bf8a59fa 2004-04-11 devnull .I Lookuplsym
213 bf8a59fa 2004-04-11 devnull writes symbol information for the symbol named
215 bf8a59fa 2004-04-11 devnull in function
218 bf8a59fa 2004-04-11 devnull .IR s2 .
220 bf8a59fa 2004-04-11 devnull .I Findlsym
221 bf8a59fa 2004-04-11 devnull searches for a symbol local to the function
223 bf8a59fa 2004-04-11 devnull whose location is exactly
224 bf8a59fa 2004-04-11 devnull .IR loc ,
225 bf8a59fa 2004-04-11 devnull writing its symbol information to
226 bf8a59fa 2004-04-11 devnull .IR s2 .
228 bf8a59fa 2004-04-11 devnull is almost always an indirection through a frame pointer register;
229 bf8a59fa 2004-04-11 devnull the details vary from architecture to architecture.
231 bf8a59fa 2004-04-11 devnull .I Symoff
232 bf8a59fa 2004-04-11 devnull converts a location to a symbol reference.
233 bf8a59fa 2004-04-11 devnull The string containing that reference is of the form
234 bf8a59fa 2004-04-11 devnull `name+offset', where `name' is the name of the
235 bf8a59fa 2004-04-11 devnull nearest symbol with an address less than or equal to the
236 bf8a59fa 2004-04-11 devnull target address, and `offset' is the hexadecimal offset beyond
237 bf8a59fa 2004-04-11 devnull that symbol. If `offset' is zero, only the name of the
238 bf8a59fa 2004-04-11 devnull symbol is printed.
239 bf8a59fa 2004-04-11 devnull If no symbol is found within 4096 bytes of the address, the address
240 bf8a59fa 2004-04-11 devnull is formatted as a hexadecimal address.
242 bf8a59fa 2004-04-11 devnull is the address of a buffer of
244 bf8a59fa 2004-04-11 devnull bytes to receive the formatted string.
246 bf8a59fa 2004-04-11 devnull is the address to be converted.
248 bf8a59fa 2004-04-11 devnull is the type code of the search space:
249 bf8a59fa 2004-04-11 devnull .BR CTEXT ,
250 bf8a59fa 2004-04-11 devnull .BR CDATA ,
252 bf8a59fa 2004-04-11 devnull .BR CANY .
253 bf8a59fa 2004-04-11 devnull .I Symoff
254 bf8a59fa 2004-04-11 devnull returns the length of the formatted string contained in
255 bf8a59fa 2004-04-11 devnull .IR buf .
257 bf8a59fa 2004-04-11 devnull .I Pc2file
258 bf8a59fa 2004-04-11 devnull searches the symbol table to find the file and line number
259 bf8a59fa 2004-04-11 devnull corresponding to the instruction at program counter
260 bf8a59fa 2004-04-11 devnull .IR pc .
262 bf8a59fa 2004-04-11 devnull is the address of a buffer of
264 bf8a59fa 2004-04-11 devnull bytes to receive the file name.
266 bf8a59fa 2004-04-11 devnull receives the line number.
268 bf8a59fa 2004-04-11 devnull .I Pc2line
270 bf8a59fa 2004-04-11 devnull .I pc2file
271 bf8a59fa 2004-04-11 devnull but neglects to return information about the source file.
273 bf8a59fa 2004-04-11 devnull .I Fileline
274 bf8a59fa 2004-04-11 devnull is also like
275 bf8a59fa 2004-04-11 devnull .IR pc2file ,
276 bf8a59fa 2004-04-11 devnull but returns the file and line number in the
277 bf8a59fa 2004-04-11 devnull .IR n -byte
278 bf8a59fa 2004-04-11 devnull text buffer
279 bf8a59fa 2004-04-11 devnull .IR buf ,
280 bf8a59fa 2004-04-11 devnull formatted as
281 bf8a59fa 2004-04-11 devnull `file:line'.
283 bf8a59fa 2004-04-11 devnull .I File2pc
284 bf8a59fa 2004-04-11 devnull performs the opposite mapping:
285 bf8a59fa 2004-04-11 devnull it stores in
287 bf8a59fa 2004-04-11 devnull a text address associated with
291 bf8a59fa 2004-04-11 devnull .IR file .
293 bf8a59fa 2004-04-11 devnull .I Line2pc
294 bf8a59fa 2004-04-11 devnull is similar: it converts a line number to an
295 bf8a59fa 2004-04-11 devnull instruction address, storing it in
296 bf8a59fa 2004-04-11 devnull .IR pc .
297 bf8a59fa 2004-04-11 devnull Since a line number does not uniquely identify an
298 bf8a59fa 2004-04-11 devnull instruction (e.g., every source file has line 1),
299 bf8a59fa 2004-04-11 devnull .I basepc
300 bf8a59fa 2004-04-11 devnull specifies a text address from which
301 bf8a59fa 2004-04-11 devnull the search begins.
302 bf8a59fa 2004-04-11 devnull Usually this is the address of the first function in the
303 bf8a59fa 2004-04-11 devnull file of interest.
305 bf8a59fa 2004-04-11 devnull .I Fnbound
306 bf8a59fa 2004-04-11 devnull returns the start and end addresses of the function containing
307 bf8a59fa 2004-04-11 devnull the text address supplied as the first argument.
308 bf8a59fa 2004-04-11 devnull The second argument is an array of two unsigned longs;
309 bf8a59fa 2004-04-11 devnull .I fnbound
310 bf8a59fa 2004-04-11 devnull places the bounding addresses of the function in the
311 bf8a59fa 2004-04-11 devnull first and second elements of this array.
312 bf8a59fa 2004-04-11 devnull The start address is the address of the first instruction of the function;
313 bf8a59fa 2004-04-11 devnull the end address is the first address beyond the end of the target function.
315 bf8a59fa 2004-04-11 devnull All functions return 0 on success and \-1 on error.
316 bf8a59fa 2004-04-11 devnull When an error occurs, a message describing it is stored
317 bf8a59fa 2004-04-11 devnull in the system error buffer where it is available via
318 bf8a59fa 2004-04-11 devnull .IR errstr .
319 bf8a59fa 2004-04-11 devnull .SH SOURCE
320 bf8a59fa 2004-04-11 devnull .B /sys/src/libmach
321 bf8a59fa 2004-04-11 devnull .SH "SEE ALSO"
322 bf8a59fa 2004-04-11 devnull .IR mach (3),
323 bf8a59fa 2004-04-11 devnull .IR mach-file (3),
324 bf8a59fa 2004-04-11 devnull .IR mach-map (3)
