1 bf8a59fa 2004-04-11 devnull .TH MACH-SYMBOL 3
3 058b0118 2005-01-03 devnull symopen, symclose, findhdr, indexsym, lookupsym, findsym,
4 058b0118 2005-01-03 devnull findexsym, flookupsym, ffindsym,
5 bf8a59fa 2004-04-11 devnull lookuplsym, indexlsym, findlsym,
6 bf8a59fa 2004-04-11 devnull symoff, pc2file, file2pc, line2pc, fnbound, fileline,
7 bf8a59fa 2004-04-11 devnull pc2line \- symbol table access functions
8 bf8a59fa 2004-04-11 devnull .SH SYNOPSIS
9 bf8a59fa 2004-04-11 devnull .B #include <u.h>
11 bf8a59fa 2004-04-11 devnull .B #include <libc.h>
13 bf8a59fa 2004-04-11 devnull .B #include <mach.h>
15 058b0118 2005-01-03 devnull .ta \w'\fBxxxxxxxx'u +\w'\fBxxxxxx'u
17 bf8a59fa 2004-04-11 devnull int symopen(Fhdr *hdr)
19 bf8a59fa 2004-04-11 devnull void symclose(Fhdr *hdr)
21 058b0118 2005-01-03 devnull Fhdr *findhdr(char *name)
23 058b0118 2005-01-03 devnull extern Fhdr* fhdrlist;
26 bf8a59fa 2004-04-11 devnull int indexsym(uint n, Symbol *s)
28 bf8a59fa 2004-04-11 devnull int lookupsym(char *fn, char *var, Symbol *s)
30 bf8a59fa 2004-04-11 devnull int findsym(Loc loc, uint class, Symbol *s)
33 058b0118 2005-01-03 devnull int findexsym(Fhdr *hdr, uint n, Symbol *s)
35 058b0118 2005-01-03 devnull Symbol *flookupsym(Fhdr *hdr, char *name)
37 058b0118 2005-01-03 devnull Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class)
40 bf8a59fa 2004-04-11 devnull int indexlsym(Symbol *s1, uint n, Symbol *s2)
42 bf8a59fa 2004-04-11 devnull int lookuplsym(Symbol *s1, char *name, Symbol *s2)
44 bf8a59fa 2004-04-11 devnull int findlsym(Symbol *s1, Loc loc, Symbol *s2)
47 bf8a59fa 2004-04-11 devnull int symoff(char *a, uint n, ulong addr, uint class)
50 bf8a59fa 2004-04-11 devnull int pc2file(ulong pc, char *file, uint n, ulong *line)
52 bf8a59fa 2004-04-11 devnull int pc2line(ulong pc, ulong *line)
54 bf8a59fa 2004-04-11 devnull int fileline(ulong pc, char *buf, uint n)
56 bf8a59fa 2004-04-11 devnull int file2pc(char *file, ulong line, ulong *pc)
58 bf8a59fa 2004-04-11 devnull int line2pc(ulong basepc, ulong line, ulong *pc)
60 bf8a59fa 2004-04-11 devnull int fnbound(ulong pc, ulong bounds[2])
61 bf8a59fa 2004-04-11 devnull .SH DESCRIPTION
62 bf8a59fa 2004-04-11 devnull These functions provide machine-independent access to the
63 bf8a59fa 2004-04-11 devnull symbol table of an executable file or executing process.
64 d32deab1 2020-08-16 rsc .MR Mach (3) ,
65 d32deab1 2020-08-16 rsc .MR mach-file (3) ,
67 d32deab1 2020-08-16 rsc .MR mach-map (3)
68 bf8a59fa 2004-04-11 devnull describe additional library functions for
69 bf8a59fa 2004-04-11 devnull accessing executable files and executing processes.
71 bf8a59fa 2004-04-11 devnull .IR Symopen
72 bf8a59fa 2004-04-11 devnull uses the data in the
74 bf8a59fa 2004-04-11 devnull structure filled by
75 bf8a59fa 2004-04-11 devnull .I crackhdr
77 d32deab1 2020-08-16 rsc .MR mach-file (3) )
78 bf8a59fa 2004-04-11 devnull to initialize in-memory structures used to access the symbol
79 bf8a59fa 2004-04-11 devnull tables contained in the file.
80 bf8a59fa 2004-04-11 devnull .IR Symclose
81 bf8a59fa 2004-04-11 devnull frees the structures.
82 bf8a59fa 2004-04-11 devnull The rest of the functions described here access a composite
83 bf8a59fa 2004-04-11 devnull symbol table made up of all currently open tables.
85 058b0118 2005-01-03 devnull The set of all currently open
86 058b0118 2005-01-03 devnull .BR Fhdr s
87 058b0118 2005-01-03 devnull is maintained as a linked list starting at
88 058b0118 2005-01-03 devnull .I fhdrlist
89 058b0118 2005-01-03 devnull (chained via
90 058b0118 2005-01-03 devnull .BR Fhdr.next ).
92 058b0118 2005-01-03 devnull .I Findhdr
93 058b0118 2005-01-03 devnull searches the currently open
94 058b0118 2005-01-03 devnull .BR Fhdr s
95 058b0118 2005-01-03 devnull for one whose file name ends with the path
97 058b0118 2005-01-03 devnull (that is,
98 058b0118 2005-01-03 devnull .B libc.so
100 058b0118 2005-01-03 devnull .B /usr/lib/libc.so
102 058b0118 2005-01-03 devnull .BR mylibc.so ).
105 bf8a59fa 2004-04-11 devnull .B Symbol
106 bf8a59fa 2004-04-11 devnull data structure:
111 bf8a59fa 2004-04-11 devnull typedef struct Symbol Symbol;
112 bf8a59fa 2004-04-11 devnull struct Symbol
114 bf8a59fa 2004-04-11 devnull char *name;
115 bf8a59fa 2004-04-11 devnull Loc loc;
116 bf8a59fa 2004-04-11 devnull Loc hiloc;
117 bf8a59fa 2004-04-11 devnull char class;
118 bf8a59fa 2004-04-11 devnull char type;
119 bf8a59fa 2004-04-11 devnull \fI...\fP
124 bf8a59fa 2004-04-11 devnull describes a symbol table entry.
126 bf8a59fa 2004-04-11 devnull .B value
127 bf8a59fa 2004-04-11 devnull field contains the offset of the symbol within its
128 bf8a59fa 2004-04-11 devnull address space: global variables relative to the beginning
129 bf8a59fa 2004-04-11 devnull of the data segment, text beyond the start of the text
130 bf8a59fa 2004-04-11 devnull segment, and automatic variables and parameters relative
131 bf8a59fa 2004-04-11 devnull to the stack frame. The
133 bf8a59fa 2004-04-11 devnull field contains the type of the symbol:
137 bf8a59fa 2004-04-11 devnull text segment symbol
140 bf8a59fa 2004-04-11 devnull static text segment symbol
143 bf8a59fa 2004-04-11 devnull data segment symbol
146 bf8a59fa 2004-04-11 devnull static data segment symbol
149 bf8a59fa 2004-04-11 devnull bss segment symbol
152 bf8a59fa 2004-04-11 devnull static bss segment symbol
155 bf8a59fa 2004-04-11 devnull automatic (local) variable symbol
158 bf8a59fa 2004-04-11 devnull function parameter symbol
161 905ca4e6 2004-04-19 devnull undefined symbol
166 bf8a59fa 2004-04-11 devnull .B class
167 bf8a59fa 2004-04-11 devnull field assigns the symbol to a general class;
168 bf8a59fa 2004-04-11 devnull .BR CTEXT ,
169 bf8a59fa 2004-04-11 devnull .BR CDATA ,
170 bf8a59fa 2004-04-11 devnull .BR CAUTO ,
172 bf8a59fa 2004-04-11 devnull .B CPARAM
173 bf8a59fa 2004-04-11 devnull are the most popular.
175 bf8a59fa 2004-04-11 devnull .I Indexsym
176 bf8a59fa 2004-04-11 devnull stores information for the
178 bf8a59fa 2004-04-11 devnull symbol into
180 bf8a59fa 2004-04-11 devnull The symbols are ordered by increasing address.
182 bf8a59fa 2004-04-11 devnull .I Lookupsym
184 bf8a59fa 2004-04-11 devnull .B Symbol
185 bf8a59fa 2004-04-11 devnull structure with symbol table information. Global variables
186 bf8a59fa 2004-04-11 devnull and functions are represented by a single name; local variables
187 bf8a59fa 2004-04-11 devnull and parameters are uniquely specified by a function and
188 bf8a59fa 2004-04-11 devnull variable name pair. Arguments
192 bf8a59fa 2004-04-11 devnull contain the
193 bf8a59fa 2004-04-11 devnull name of a function and variable, respectively.
195 bf8a59fa 2004-04-11 devnull are non-zero, the symbol table is searched for a parameter
196 bf8a59fa 2004-04-11 devnull or automatic variable. If only
199 bf8a59fa 2004-04-11 devnull zero, the text symbol table is searched for function
200 bf8a59fa 2004-04-11 devnull .IR fn .
203 bf8a59fa 2004-04-11 devnull is zero, the global variable table
204 bf8a59fa 2004-04-11 devnull is searched for
205 bf8a59fa 2004-04-11 devnull .IR var .
207 bf8a59fa 2004-04-11 devnull .I Findsym
208 bf8a59fa 2004-04-11 devnull returns the symbol table entry of type
209 bf8a59fa 2004-04-11 devnull .I class
210 bf8a59fa 2004-04-11 devnull stored near
211 bf8a59fa 2004-04-11 devnull .IR addr .
212 bf8a59fa 2004-04-11 devnull The selected symbol is a global variable or function with
213 bf8a59fa 2004-04-11 devnull address nearest to and less than or equal to
214 bf8a59fa 2004-04-11 devnull .IR addr .
215 bf8a59fa 2004-04-11 devnull Class specification
216 bf8a59fa 2004-04-11 devnull .B CDATA
217 bf8a59fa 2004-04-11 devnull searches only the global variable symbol table; class
218 bf8a59fa 2004-04-11 devnull .B CTEXT
219 bf8a59fa 2004-04-11 devnull limits the search to the text symbol table.
220 bf8a59fa 2004-04-11 devnull Class specification
222 bf8a59fa 2004-04-11 devnull searches the text table first, then the global table.
224 058b0118 2005-01-03 devnull .IR Findexsym ,
225 058b0118 2005-01-03 devnull .IR flookupsym ,
227 058b0118 2005-01-03 devnull .I ffindsym
228 058b0118 2005-01-03 devnull are similar to
229 058b0118 2005-01-03 devnull .IR indexsym ,
230 058b0118 2005-01-03 devnull .IR lookupsym ,
232 058b0118 2005-01-03 devnull .IR findsym ,
233 058b0118 2005-01-03 devnull but operate only on the symbols from
234 058b0118 2005-01-03 devnull .IR hdr .
235 058b0118 2005-01-03 devnull .I Flookupsym
237 058b0118 2005-01-03 devnull .I ffindsym
238 058b0118 2005-01-03 devnull return pointers to data stored in the
239 058b0118 2005-01-03 devnull .IR hdr ,
240 058b0118 2005-01-03 devnull which must not be modified or freed.
242 bf8a59fa 2004-04-11 devnull .IR Indexlsym ,
243 bf8a59fa 2004-04-11 devnull .IR lookuplsym ,
245 058b0118 2005-01-03 devnull .I findlsym
246 bf8a59fa 2004-04-11 devnull are similar to
247 bf8a59fa 2004-04-11 devnull .IR indexsym ,
248 bf8a59fa 2004-04-11 devnull .IR lookupsym ,
250 bf8a59fa 2004-04-11 devnull .IR findsym ,
251 bf8a59fa 2004-04-11 devnull but operate on the smaller symbol table of parameters and
252 bf8a59fa 2004-04-11 devnull variables local to the function represented by symbol
253 bf8a59fa 2004-04-11 devnull .IR s1 .
255 bf8a59fa 2004-04-11 devnull .I Indexlsym
256 bf8a59fa 2004-04-11 devnull writes symbol information for the
257 bf8a59fa 2004-04-11 devnull .IR n th
258 bf8a59fa 2004-04-11 devnull local symbol of function
261 bf8a59fa 2004-04-11 devnull .IR s2 .
262 bf8a59fa 2004-04-11 devnull Function parameters appear first in the ordering, followed by local symbols.
264 bf8a59fa 2004-04-11 devnull .I Lookuplsym
265 bf8a59fa 2004-04-11 devnull writes symbol information for the symbol named
267 bf8a59fa 2004-04-11 devnull in function
270 bf8a59fa 2004-04-11 devnull .IR s2 .
272 bf8a59fa 2004-04-11 devnull .I Findlsym
273 bf8a59fa 2004-04-11 devnull searches for a symbol local to the function
275 bf8a59fa 2004-04-11 devnull whose location is exactly
276 bf8a59fa 2004-04-11 devnull .IR loc ,
277 bf8a59fa 2004-04-11 devnull writing its symbol information to
278 bf8a59fa 2004-04-11 devnull .IR s2 .
280 bf8a59fa 2004-04-11 devnull is almost always an indirection through a frame pointer register;
281 bf8a59fa 2004-04-11 devnull the details vary from architecture to architecture.
283 bf8a59fa 2004-04-11 devnull .I Symoff
284 bf8a59fa 2004-04-11 devnull converts a location to a symbol reference.
285 bf8a59fa 2004-04-11 devnull The string containing that reference is of the form
286 bf8a59fa 2004-04-11 devnull `name+offset', where `name' is the name of the
287 bf8a59fa 2004-04-11 devnull nearest symbol with an address less than or equal to the
288 bf8a59fa 2004-04-11 devnull target address, and `offset' is the hexadecimal offset beyond
289 bf8a59fa 2004-04-11 devnull that symbol. If `offset' is zero, only the name of the
290 bf8a59fa 2004-04-11 devnull symbol is printed.
291 bf8a59fa 2004-04-11 devnull If no symbol is found within 4096 bytes of the address, the address
292 bf8a59fa 2004-04-11 devnull is formatted as a hexadecimal address.
294 bf8a59fa 2004-04-11 devnull is the address of a buffer of
296 bf8a59fa 2004-04-11 devnull bytes to receive the formatted string.
298 bf8a59fa 2004-04-11 devnull is the address to be converted.
300 bf8a59fa 2004-04-11 devnull is the type code of the search space:
301 bf8a59fa 2004-04-11 devnull .BR CTEXT ,
302 bf8a59fa 2004-04-11 devnull .BR CDATA ,
304 bf8a59fa 2004-04-11 devnull .BR CANY .
305 bf8a59fa 2004-04-11 devnull .I Symoff
306 bf8a59fa 2004-04-11 devnull returns the length of the formatted string contained in
307 bf8a59fa 2004-04-11 devnull .IR buf .
309 bf8a59fa 2004-04-11 devnull .I Pc2file
310 bf8a59fa 2004-04-11 devnull searches the symbol table to find the file and line number
311 bf8a59fa 2004-04-11 devnull corresponding to the instruction at program counter
312 bf8a59fa 2004-04-11 devnull .IR pc .
314 bf8a59fa 2004-04-11 devnull is the address of a buffer of
316 bf8a59fa 2004-04-11 devnull bytes to receive the file name.
318 bf8a59fa 2004-04-11 devnull receives the line number.
320 bf8a59fa 2004-04-11 devnull .I Pc2line
322 bf8a59fa 2004-04-11 devnull .I pc2file
323 bf8a59fa 2004-04-11 devnull but neglects to return information about the source file.
325 bf8a59fa 2004-04-11 devnull .I Fileline
326 bf8a59fa 2004-04-11 devnull is also like
327 bf8a59fa 2004-04-11 devnull .IR pc2file ,
328 bf8a59fa 2004-04-11 devnull but returns the file and line number in the
329 bf8a59fa 2004-04-11 devnull .IR n -byte
330 bf8a59fa 2004-04-11 devnull text buffer
331 bf8a59fa 2004-04-11 devnull .IR buf ,
332 bf8a59fa 2004-04-11 devnull formatted as
333 bf8a59fa 2004-04-11 devnull `file:line'.
335 bf8a59fa 2004-04-11 devnull .I File2pc
336 bf8a59fa 2004-04-11 devnull performs the opposite mapping:
337 bf8a59fa 2004-04-11 devnull it stores in
339 bf8a59fa 2004-04-11 devnull a text address associated with
343 bf8a59fa 2004-04-11 devnull .IR file .
345 bf8a59fa 2004-04-11 devnull .I Line2pc
346 bf8a59fa 2004-04-11 devnull is similar: it converts a line number to an
347 bf8a59fa 2004-04-11 devnull instruction address, storing it in
348 bf8a59fa 2004-04-11 devnull .IR pc .
349 bf8a59fa 2004-04-11 devnull Since a line number does not uniquely identify an
350 bf8a59fa 2004-04-11 devnull instruction (e.g., every source file has line 1),
351 bf8a59fa 2004-04-11 devnull .I basepc
352 bf8a59fa 2004-04-11 devnull specifies a text address from which
353 bf8a59fa 2004-04-11 devnull the search begins.
354 bf8a59fa 2004-04-11 devnull Usually this is the address of the first function in the
355 bf8a59fa 2004-04-11 devnull file of interest.
357 bf8a59fa 2004-04-11 devnull .I Fnbound
358 bf8a59fa 2004-04-11 devnull returns the start and end addresses of the function containing
359 bf8a59fa 2004-04-11 devnull the text address supplied as the first argument.
360 bf8a59fa 2004-04-11 devnull The second argument is an array of two unsigned longs;
361 bf8a59fa 2004-04-11 devnull .I fnbound
362 bf8a59fa 2004-04-11 devnull places the bounding addresses of the function in the
363 bf8a59fa 2004-04-11 devnull first and second elements of this array.
364 bf8a59fa 2004-04-11 devnull The start address is the address of the first instruction of the function;
365 bf8a59fa 2004-04-11 devnull the end address is the first address beyond the end of the target function.
367 bf8a59fa 2004-04-11 devnull All functions return 0 on success and \-1 on error.
368 bf8a59fa 2004-04-11 devnull When an error occurs, a message describing it is stored
369 bf8a59fa 2004-04-11 devnull in the system error buffer where it is available via
370 bf8a59fa 2004-04-11 devnull .IR errstr .
371 bf8a59fa 2004-04-11 devnull .SH SOURCE
372 c3674de4 2005-01-11 devnull .B \*9/src/libmach
373 bf8a59fa 2004-04-11 devnull .SH "SEE ALSO"
374 d32deab1 2020-08-16 rsc .MR mach (3) ,
375 d32deab1 2020-08-16 rsc .MR mach-file (3) ,
376 d32deab1 2020-08-16 rsc .MR mach-map (3)
