diff options
Diffstat (limited to 'man/man3/symbol.3')
| -rw-r--r-- | man/man3/symbol.3 | 436 |
1 files changed, 0 insertions, 436 deletions
diff --git a/man/man3/symbol.3 b/man/man3/symbol.3 deleted file mode 100644 index f22590ae..00000000 --- a/man/man3/symbol.3 +++ /dev/null @@ -1,436 +0,0 @@ -.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) |