3 symopen, symclose, indexsym, lookupsym, findsym,
4 lookuplsym, indexlsym, findlsym,
5 symoff, pc2file, file2pc, line2pc, fnbound, fileline,
6 pc2line \- symbol table access functions
14 .ta \w'\fBxxxxxx'u +\w'\fBxxxxxx'u
16 int symopen(Fhdr *hdr)
18 void symclose(Fhdr *hdr)
21 int indexsym(uint n, Symbol *s)
23 int lookupsym(char *fn, char *var, Symbol *s)
25 int findsym(Loc loc, uint class, Symbol *s)
28 int indexlsym(Symbol *s1, uint n, Symbol *s2)
30 int lookuplsym(Symbol *s1, char *name, Symbol *s2)
32 int findlsym(Symbol *s1, Loc loc, Symbol *s2)
35 int symoff(char *a, uint n, ulong addr, uint class)
38 int pc2file(ulong pc, char *file, uint n, ulong *line)
40 int pc2line(ulong pc, ulong *line)
42 int fileline(ulong pc, char *buf, uint n)
44 int file2pc(char *file, ulong line, ulong *pc)
46 int line2pc(ulong basepc, ulong line, ulong *pc)
48 int fnbound(ulong pc, ulong bounds[2])
50 These functions provide machine-independent access to the
51 symbol table of an executable file or executing process.
56 describe additional library functions for
57 accessing executable files and executing processes.
66 to initialize in-memory structures used to access the symbol
67 tables contained in the file.
70 The rest of the functions described here access a composite
71 symbol table made up of all currently open tables.
80 typedef struct Symbol Symbol;
93 describes a symbol table entry.
96 field contains the offset of the symbol within its
97 address space: global variables relative to the beginning
98 of the data segment, text beyond the start of the text
99 segment, and automatic variables and parameters relative
100 to the stack frame. The
102 field contains the type of the symbol:
109 static text segment symbol
115 static data segment symbol
121 static bss segment symbol
124 automatic (local) variable symbol
127 function parameter symbol
136 field assigns the symbol to a general class;
142 are the most popular.
145 stores information for the
149 The symbols are ordered by increasing address.
154 structure with symbol table information. Global variables
155 and functions are represented by a single name; local variables
156 and parameters are uniquely specified by a function and
157 variable name pair. Arguments
162 name of a function and variable, respectively.
164 are non-zero, the symbol table is searched for a parameter
165 or automatic variable. If only
168 zero, the text symbol table is searched for function
172 is zero, the global variable table
177 returns the symbol table entry of type
181 The selected symbol is a global variable or function with
182 address nearest to and less than or equal to
186 searches only the global variable symbol table; class
188 limits the search to the text symbol table.
191 searches the text table first, then the global table.
202 but operate on the smaller symbol table of parameters and
203 variables local to the function represented by symbol
207 writes symbol information for the
209 local symbol of function
213 Function parameters appear first in the ordering, followed by local symbols.
216 writes symbol information for the symbol named
224 searches for a symbol local to the function
226 whose location is exactly
228 writing its symbol information to
231 is almost always an indirection through a frame pointer register;
232 the details vary from architecture to architecture.
235 converts a location to a symbol reference.
236 The string containing that reference is of the form
237 `name+offset', where `name' is the name of the
238 nearest symbol with an address less than or equal to the
239 target address, and `offset' is the hexadecimal offset beyond
240 that symbol. If `offset' is zero, only the name of the
242 If no symbol is found within 4096 bytes of the address, the address
243 is formatted as a hexadecimal address.
245 is the address of a buffer of
247 bytes to receive the formatted string.
249 is the address to be converted.
251 is the type code of the search space:
257 returns the length of the formatted string contained in
261 searches the symbol table to find the file and line number
262 corresponding to the instruction at program counter
265 is the address of a buffer of
267 bytes to receive the file name.
269 receives the line number.
274 but neglects to return information about the source file.
279 but returns the file and line number in the
287 performs the opposite mapping:
290 a text address associated with
297 is similar: it converts a line number to an
298 instruction address, storing it in
300 Since a line number does not uniquely identify an
301 instruction (e.g., every source file has line 1),
303 specifies a text address from which
305 Usually this is the address of the first function in the
309 returns the start and end addresses of the function containing
310 the text address supplied as the first argument.
311 The second argument is an array of two unsigned longs;
313 places the bounding addresses of the function in the
314 first and second elements of this array.
315 The start address is the address of the first instruction of the function;
316 the end address is the first address beyond the end of the target function.
318 All functions return 0 on success and \-1 on error.
319 When an error occurs, a message describing it is stored
320 in the system error buffer where it is available via
323 .B /usr/local/plan9/src/libmach
