sys/man/2/symbol

   1 .TH SYMBOL 2
   2 .SH NAME
   3 syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal,
   4 getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym,
   5 fileline, fnbound \- symbol table access functions
   6 .SH SYNOPSIS
   7 .B #include <u.h>
   8 .br
   9 .B #include <libc.h>
  10 .br
  11 .B #include <bio.h>
  12 .br
  13 .B #include <mach.h>
  14 .PP
  15 .ta \w'\fLmachines 'u
  16 .B
  17 int  syminit(int fd, Fhdr *fp)
  18 .PP
  19 .B
  20 Sym  *getsym(int index)
  21 .PP
  22 .B
  23 Sym  *symbase(long *nsyms)
  24 .PP
  25 .B
  26 int  fileelem(Sym **fp, uchar *encname, char *buf, int n)
  27 .PP
  28 .B
  29 int  filesym(int index, char *buf, int n)
  30 .PP
  31 .B
  32 uvlong pc2sp(uvlong pc)
  33 .PP
  34 .B
  35 long pc2line(uvlong pc)
  36 .PP
  37 .B
  38 void textseg(uvlong base, Fhdr *fp)
  39 .PP
  40 .B
  41 uvlong line2addr(long line, uvlong basepc, uvlong endpc)
  42 .PP
  43 .B
  44 int  lookup(char *fn, char *var, Symbol *s)
  45 .PP
  46 .B
  47 int  findlocal(Symbol *s1, char *name, Symbol *s2)
  48 .PP
  49 .B
  50 int  getauto(Symbol *s1, int off, int class, Symbol *s2)
  51 .PP
  52 .B
  53 int  findsym(uvlong addr, int class, Symbol *s)
  54 .PP
  55 .B
  56 int  localsym(Symbol *s, int index)
  57 .PP
  58 .B
  59 int  globalsym(Symbol *s, int index)
  60 .PP
  61 .B
  62 int  textsym(Symbol *s, int index)
  63 .PP
  64 .B
  65 uvlong file2pc(char *file, long line)
  66 .PP
  67 .B
  68 long  fileline(char *str, int n, uvlong addr)
  69 .PP
  70 .B
  71 int  fnbound(uvlong addr, uvlong *bounds)
  72 .SH DESCRIPTION
  73 These functions provide machine-independent access to the
  74 symbol table of an executable file or executing process.
  75 The latter is accessible by opening the device
  76 .B /proc/\fIpid\fP/text
  77 as described in
  78 .IR proc (3).
  79 .IR Mach (2)
  80 and
  81 .IR object (2)
  82 describe additional library functions
  83 for processing executable and object files.
  84 .PP
  85 .IR Syminit ,
  86 .IR getsym ,
  87 .IR symbase ,
  88 .IR fileelem ,
  89 .IR pc2sp ,
  90 .IR pc2line ,
  91 and
  92 .I line2addr
  93 process the symbol table contained in an executable file
  94 or the
  95 .B text
  96 image of an executing program.
  97 The symbol table is stored internally as an array of
  98 .B Sym
  99 data structures as defined in
 100 .IR a.out (6).
 101 .PP
 102 .I Syminit
 103 uses the data in the
 104 .B Fhdr
 105 structure filled by
 106 .I crackhdr
 107 (see
 108 .IR mach (2))
 109 to read the raw symbol tables from the open file descriptor
 110 .IR fd .
 111 It returns the count of the number of symbols
 112 or \-1 if an error occurs.
 113 .PP
 114 .I Getsym
 115 returns the address of the
 116 .IR i th
 117 .B Sym
 118 structure or zero if
 119 .I index
 120 is out of range.
 121 .PP
 122 .I Symbase
 123 returns the address of the first
 124 .B Sym
 125 structure in the symbol table.  The number of
 126 entries in the symbol table is returned in
 127 .IR nsyms .
 128 .PP
 129 .I Fileelem
 130 converts a file name, encoded as described in
 131 .IR a.out (6),
 132 to a character string.
 133 .I Fp
 134 is the base of
 135 an array of pointers to file path components ordered by path index.
 136 .I Encname
 137 is the address of an array of encoded
 138 file path components in the form of a
 139 .B z
 140 symbol table entry.
 141 .I Buf
 142 and
 143 .I n
 144 specify the
 145 address of a receiving character buffer and its length.
 146 .I Fileelem
 147 returns the length of the null-terminated string
 148 that is at most
 149 .IR n \-1
 150 bytes long.
 151 .PP
 152 .I Filesym
 153 is a higher-level interface to
 154 .IR fileelem .
 155 It fills
 156 .I buf
 157 with the name of the
 158 .IR i th
 159 file and returns the length of the null-terminated string
 160 that is at most
 161 .IR n \-1
 162 bytes long.
 163 File names are retrieved in no particular order, although
 164 the order of retrieval does not vary from one pass to the next.
 165 A zero is returned when
 166 .I index
 167 is too large or too small or an error occurs during file name
 168 conversion.
 169 .PP
 170 .I Pc2sp
 171 returns an offset associated with
 172 a given value of the program counter.  Adding this offset
 173 to the current value of the stack pointer gives the address
 174 of the current stack frame.  This approach only applies
 175 to the 68020 architecture; other architectures
 176 use a fixed stack frame offset by a constant contained
 177 in a dummy local variable (called
 178 .BR .frame )
 179 in the symbol table.
 180 .PP
 181 .I Pc2line
 182 returns the line number of the statement associated
 183 with the instruction address
 184 .IR pc .
 185 The
 186 line number is the absolute line number in the
 187 source file as seen by the compiler after pre-processing; the
 188 original line number in the source file may be derived from this
 189 value using the history stacks contained in the symbol table.
 190 .PP
 191 .I Pc2sp
 192 and
 193 .I pc2line
 194 must know the start and end addresses of the text segment
 195 for proper operation.  These values are calculated from the
 196 file header by function
 197 .IR syminit .
 198 If the text segment address is changed, the application
 199 program must invoke
 200 .I textseg
 201 to recalculate the boundaries of the segment.
 202 .I Base
 203 is the new base address of the text segment and
 204 .I fp
 205 points to the
 206 .I Fhdr
 207 data structure filled by
 208 .IR crackhdr .
 209 .PP
 210 .I Line2addr
 211 converts a line number to an instruction address.  The
 212 first argument is the absolute line number in
 213 a file.  Since a line number does not uniquely identify
 214 an instruction location (e.g., every source file has line 1),
 215 a second argument specifies a text address
 216 from which the search begins.  Usually this
 217 is the address of the first function in the file of interest.
 218 .PP
 219 .IR Pc2sp ,
 220 .IR pc2line ,
 221 and
 222 .I line2addr
 223 return \-1 in the case of an error.
 224 .PP
 225 .IR Lookup ,
 226 .IR findlocal ,
 227 .IR getauto ,
 228 .IR findsym ,
 229 .IR localsym ,
 230 .IR globalsym ,
 231 .IR textsym ,
 232 .IR file2pc ,
 233 and
 234 .I fileline
 235 operate on data structures riding above the raw symbol table.
 236 These data structures occupy memory
 237 and impose a startup penalty but speed retrievals
 238 and provide higher-level access to the basic symbol
 239 table data.
 240 .I Syminit
 241 must be called
 242 prior to using these functions.
 243 The
 244 .B Symbol
 245 data structure:
 246 .IP
 247 .EX
 248 typedef struct {
 249         void *handle;     /* private */
 250         struct {
 251             char  *name;
 252             long   value;
 253             char   type;
 254             char   class;
 255         };
 256 } Symbol;
 257 .EE
 258 .LP
 259 describes a symbol table entry.
 260 The
 261 .B value
 262 field contains the offset of the symbol within its
 263 address space: global variables relative to the beginning
 264 of the data segment, text beyond the start of the text
 265 segment, and automatic variables and parameters relative
 266 to the stack frame.  The
 267 .B type
 268 field contains the type of the symbol as defined in
 269 .IR a.out (6).
 270 The
 271 .B class
 272 field assigns the symbol to a general class;
 273 .BR CTEXT ,
 274 .BR CDATA ,
 275 .BR CAUTO ,
 276 and
 277 .B CPARAM
 278 are the most popular.
 279 .PP
 280 .I Lookup
 281 fills a
 282 .B Symbol
 283 structure with symbol table information.  Global variables
 284 and functions are represented by a single name; local variables
 285 and parameters are uniquely specified by a function and
 286 variable name pair.  Arguments
 287 .I fn
 288 and
 289 .I var
 290 contain the
 291 name of a function and variable, respectively.
 292 If both
 293 are non-zero, the symbol table is searched for a parameter
 294 or automatic variable.  If only
 295 .I var
 296 is
 297 zero, the text symbol table is searched for function
 298 .IR fn .
 299 If only
 300 .I fn
 301 is zero, the global variable table
 302 is searched for
 303 .IR var .
 304 .PP
 305 .I Findlocal
 306 fills
 307 .I s2
 308 with the symbol table data of the automatic variable
 309 or parameter matching
 310 .IR name .
 311 .I S1
 312 is a
 313 .B Symbol
 314 data structure describing a function or a local variable;
 315 the latter resolves to its owning function.
 316 .PP
 317 .I Getauto
 318 searches the local symbols associated with function
 319 .I s1
 320 for an automatic variable or parameter located at stack
 321 offset
 322 .IR off .
 323 .I Class
 324 selects the class of
 325 variable:
 326 .B CAUTO
 327 or
 328 .BR CPARAM .
 329 .I S2
 330 is the address of a
 331 .B Symbol
 332 data structure to receive the symbol table information
 333 of the desired symbol.
 334 .PP
 335 .I Findsym
 336 returns the symbol table entry of type
 337 .I class
 338 stored near
 339 .IR addr .
 340 The selected symbol is a global variable or function
 341 with address nearest to and less than or equal to
 342 .IR addr .
 343 Class specification
 344 .B CDATA
 345 searches only the global variable symbol table; class
 346 .B CTEXT
 347 limits the search to the text symbol table.
 348 Class specification
 349 .B CANY
 350 searches the text table first, then the global table.
 351 .PP
 352 .I Localsym
 353 returns the
 354 .IR i th
 355 local variable in the function
 356 associated with
 357 .IR s .
 358 .I S
 359 may reference a function or a local variable; the latter
 360 resolves to its owning function.
 361 If the
 362 .IR i th
 363 local symbol exists,
 364 .I s
 365 is filled with the data describing it.
 366 .PP
 367 .I Globalsym
 368 loads
 369 .I s
 370 with the symbol table information of the
 371 .IR i th
 372 global variable.
 373 .PP
 374 .I Textsym
 375 loads
 376 .I s
 377 with the symbol table information of the
 378 .IR i th
 379 text symbol.  The text symbols are ordered
 380 by increasing address.
 381 .PP
 382 .I File2pc
 383 returns a text address associated with
 384 .I line
 385 in file
 386 .IR file ,
 387 or -1 on an error.
 388 .PP
 389 .I Fileline
 390 converts text address
 391 .I addr
 392 to its equivalent
 393 line number in a source file.  The result,
 394 a null terminated character string of
 395 the form
 396 .LR file:line ,
 397 is placed in buffer
 398 .I str
 399 of
 400 .I n
 401 bytes.
 402 .PP
 403 .I Fnbound
 404 returns the start and end addresses of the function containing
 405 the text address supplied as the first argument.  The second
 406 argument is an array of two unsigned longs;
 407 .I fnbound
 408 places the bounding addresses of the function in the first
 409 and second elements of this array.  The start address is the
 410 address of the first instruction of the function; the end
 411 address is the address of the start of the next function
 412 in memory, so it is beyond the end of the target function.
 413 .I Fnbound
 414 returns 1 if the address is within a text function, or zero
 415 if the address selects no function.
 416 .PP
 417 Functions
 418 .I file2pc
 419 and
 420 .I fileline
 421 may produce inaccurate results when applied to
 422 optimized code.
 423 .PP
 424 Unless otherwise specified, all functions return 1
 425 on success, or 0 on error.  When an error occurs,
 426 a message describing it is stored in the system
 427 error buffer where it is available via
 428 .IR errstr .
 429 .SH SOURCE
 430 .B /sys/src/libmach
 431 .SH "SEE ALSO"
 432 .IR mach (2),
 433 .IR object (2),
 434 .IR errstr (2),
 435 .IR proc (3),
 436 .IR a.out (6)