diff options
Diffstat (limited to 'man/man3/symbol.3')
| -rw-r--r-- | man/man3/symbol.3 | 436 |
1 files changed, 436 insertions, 0 deletions
diff --git a/man/man3/symbol.3 b/man/man3/symbol.3 new file mode 100644 index 00000000..f22590ae --- /dev/null +++ b/man/man3/symbol.3 @@ -0,0 +1,436 @@ +.TH SYMBOL 3 +.SH NAME +syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal, +getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym, +fileline, fnbound \- symbol table access functions +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.br +.B #include <bio.h> +.br +.B #include <mach.h> +.PP +.ta \w'\fLmachines 'u +.B +int syminit(int fd, Fhdr *fp) +.PP +.B +Sym *getsym(int index) +.PP +.B +Sym *symbase(long *nsyms) +.PP +.B +int fileelem(Sym **fp, uchar *encname, char *buf, int n) +.PP +.B +int filesym(int index, char *buf, int n) +.PP +.B +long pc2sp(ulong pc) +.PP +.B +long pc2line(ulong pc) +.PP +.B +void textseg(ulong base, Fhdr *fp) +.PP +.B +long line2addr(ulong line, ulong basepc) +.PP +.B +int lookup(char *fn, char *var, Symbol *s) +.PP +.B +int findlocal(Symbol *s1, char *name, Symbol *s2) +.PP +.B +int getauto(Symbol *s1, int off, int class, Symbol *s2) +.PP +.B +int findsym(long addr, int class, Symbol *s) +.PP +.B +int localsym(Symbol *s, int index) +.PP +.B +int globalsym(Symbol *s, int index) +.PP +.B +int textsym(Symbol *s, int index) +.PP +.B +long file2pc(char *file, ulong line) +.PP +.B +int fileline(char *str, int n, ulong addr) +.PP +.B +int fnbound(long addr, ulong *bounds) +.SH DESCRIPTION +These functions provide machine-independent access to the +symbol table of an executable file or executing process. +The latter is accessible by opening the device +.B /proc/\fIpid\fP/text +as described in +.IR proc (3). +.IR Mach (2) +and +.IR object (2) +describe additional library functions +for processing executable and object files. +.PP +.IR Syminit , +.IR getsym , +.IR symbase , +.IR fileelem , +.IR pc2sp , +.IR pc2line , +and +.I line2addr +process the symbol table contained in an executable file +or the +.B text +image of an executing program. +The symbol table is stored internally as an array of +.B Sym +data structures as defined in +.IR a.out (6). +.PP +.I Syminit +uses the data in the +.B Fhdr +structure filled by +.I crackhdr +(see +.IR mach (2)) +to read the raw symbol tables from the open file descriptor +.IR fd . +It returns the count of the number of symbols +or \-1 if an error occurs. +.PP +.I Getsym +returns the address of the +.IR i th +.B Sym +structure or zero if +.I index +is out of range. +.PP +.I Symbase +returns the address of the first +.B Sym +structure in the symbol table. The number of +entries in the symbol table is returned in +.IR nsyms . +.PP +.I Fileelem +converts a file name, encoded as described in +.IR a.out (6), +to a character string. +.I Fp +is the base of +an array of pointers to file path components ordered by path index. +.I Encname +is the address of an array of encoded +file path components in the form of a +.B z +symbol table entry. +.I Buf +and +.I n +specify the +address of a receiving character buffer and its length. +.I Fileelem +returns the length of the null-terminated string +that is at most +.IR n \-1 +bytes long. +.PP +.I Filesym +is a higher-level interface to +.IR fileelem . +It fills +.I buf +with the name of the +.IR i th +file and returns the length of the null-terminated string +that is at most +.IR n \-1 +bytes long. +File names are retrieved in no particular order, although +the order of retrieval does not vary from one pass to the next. +A zero is returned when +.I index +is too large or too small or an error occurs during file name +conversion. +.PP +.I Pc2sp +returns an offset associated with +a given value of the program counter. Adding this offset +to the current value of the stack pointer gives the address +of the current stack frame. This approach only applies +to the 68020 architecture; other architectures +use a fixed stack frame offset by a constant contained +in a dummy local variable (called +.BR .frame ) +in the symbol table. +.PP +.I Pc2line +returns the line number of the statement associated +with the instruction address +.IR pc . +The +line number is the absolute line number in the +source file as seen by the compiler after pre-processing; the +original line number in the source file may be derived from this +value using the history stacks contained in the symbol table. +.PP +.I Pc2sp +and +.I pc2line +must know the start and end addresses of the text segment +for proper operation. These values are calculated from the +file header by function +.IR syminit . +If the text segment address is changed, the application +program must invoke +.I textseg +to recalculate the boundaries of the segment. +.I Base +is the new base address of the text segment and +.I fp +points to the +.I Fhdr +data structure filled by +.IR crackhdr . +.PP +.I Line2addr +converts a line number to an instruction address. The +first argument is the absolute line number in +a file. Since a line number does not uniquely identify +an instruction location (e.g., every source file has line 1), +a second argument specifies a text address +from which the search begins. Usually this +is the address of the first function in the file of interest. +.PP +.IR Pc2sp , +.IR pc2line , +and +.I line2addr +return \-1 in the case of an error. +.PP +.IR Lookup , +.IR findlocal , +.IR getauto , +.IR findsym , +.IR localsym , +.IR globalsym , +.IR textsym , +.IR file2pc , +and +.I fileline +operate on data structures riding above the raw symbol table. +These data structures occupy memory +and impose a startup penalty but speed retrievals +and provide higher-level access to the basic symbol +table data. +.I Syminit +must be called +prior to using these functions. +The +.B Symbol +data structure: +.IP +.EX +typedef struct { + void *handle; /* private */ + struct { + char *name; + long value; + char type; + char class; + }; +} Symbol; +.EE +.LP +describes a symbol table entry. +The +.B value +field contains the offset of the symbol within its +address space: global variables relative to the beginning +of the data segment, text beyond the start of the text +segment, and automatic variables and parameters relative +to the stack frame. The +.B type +field contains the type of the symbol as defined in +.IR a.out (6). +The +.B class +field assigns the symbol to a general class; +.BR CTEXT , +.BR CDATA , +.BR CAUTO , +and +.B CPARAM +are the most popular. +.PP +.I Lookup +fills a +.B Symbol +structure with symbol table information. Global variables +and functions are represented by a single name; local variables +and parameters are uniquely specified by a function and +variable name pair. Arguments +.I fn +and +.I var +contain the +name of a function and variable, respectively. +If both +are non-zero, the symbol table is searched for a parameter +or automatic variable. If only +.I var +is +zero, the text symbol table is searched for function +.IR fn . +If only +.I fn +is zero, the global variable table +is searched for +.IR var . +.PP +.I Findlocal +fills +.I s2 +with the symbol table data of the automatic variable +or parameter matching +.IR name . +.I S1 +is a +.B Symbol +data structure describing a function or a local variable; +the latter resolves to its owning function. +.PP +.I Getauto +searches the local symbols associated with function +.I s1 +for an automatic variable or parameter located at stack +offset +.IR off . +.I Class +selects the class of +variable: +.B CAUTO +or +.BR CPARAM . +.I S2 +is the address of a +.B Symbol +data structure to receive the symbol table information +of the desired symbol. +.PP +.I Findsym +returns the symbol table entry of type +.I class +stored near +.IR addr . +The selected symbol is a global variable or function +with address nearest to and less than or equal to +.IR addr . +Class specification +.B CDATA +searches only the global variable symbol table; class +.B CTEXT +limits the search to the text symbol table. +Class specification +.B CANY +searches the text table first, then the global table. +.PP +.I Localsym +returns the +.IR i th +local variable in the function +associated with +.IR s . +.I S +may reference a function or a local variable; the latter +resolves to its owning function. +If the +.IR i th +local symbol exists, +.I s +is filled with the data describing it. +.PP +.I Globalsym +loads +.I s +with the symbol table information of the +.IR i th +global variable. +.PP +.I Textsym +loads +.I s +with the symbol table information of the +.IR i th +text symbol. The text symbols are ordered +by increasing address. +.PP +.I File2pc +returns a text address associated with +.I line +in file +.IR file , +or -1 on an error. +.PP +.I Fileline +converts text address +.I addr +to its equivalent +line number in a source file. The result, +a null terminated character string of +the form +.LR file:line , +is placed in buffer +.I str +of +.I n +bytes. +.PP +.I Fnbound +returns the start and end addresses of the function containing +the text address supplied as the first argument. The second +argument is an array of two unsigned longs; +.I fnbound +places the bounding addresses of the function in the first +and second elements of this array. The start address is the +address of the first instruction of the function; the end +address is the address of the start of the next function +in memory, so it is beyond the end of the target function. +.I Fnbound +returns 1 if the address is within a text function, or zero +if the address selects no function. +.PP +Functions +.I file2pc +and +.I fileline +may produce inaccurate results when applied to +optimized code. +.PP +Unless otherwise specified, all functions return 1 +on success, or 0 on error. When an error occurs, +a message describing it is stored in the system +error buffer where it is available via +.IR errstr . +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR mach (2), +.IR object (2), +.IR errstr (2), +.IR proc (3), +.IR a.out (6) |