mach-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)