|  | 
 NAME     
 |  |  |  | symopen, symclose, findhdr, indexsym, lookupsym, findsym, findexsym,
    flookupsym, ffindsym, lookuplsym, indexlsym, findlsym, symoff,
    pc2file, file2pc, line2pc, fnbound, fileline, pc2line – symbol
    table access functions 
 | 
 SYNOPSIS     
 |  |  |  | #include <u.h> #include <libc.h>
 #include <mach.h> 
    
    
    int      symopen(Fhdr *hdr)
 void     symclose(Fhdr *hdr)
 Fhdr     *findhdr(char *name)
 extern    Fhdr* fhdrlist; 
    
    
    int      indexsym(uint n, Symbol *s)
 int      lookupsym(char *fn, char *var, Symbol *s)
 int      findsym(Loc loc, uint class, Symbol *s) 
    
    
    int      findexsym(Fhdr *hdr, uint n, Symbol *s)
 Symbol *flookupsym(Fhdr *hdr, char *name)
 Symbol *ffindsym(Fhdr *hdr, Loc loc, uint class) 
    
    
    int      indexlsym(Symbol *s1, uint n, Symbol *s2)
 int      lookuplsym(Symbol *s1, char *name, Symbol *s2)
 int      findlsym(Symbol *s1, Loc loc, Symbol *s2) 
    
    
    int      symoff(char *a, uint n, ulong addr, uint class) 
    
    
    int      pc2file(ulong pc, char *file, uint n, ulong *line)
 int      pc2line(ulong pc, ulong *line)
 int      fileline(ulong pc, char *buf, uint n)
 int      file2pc(char *file, ulong line, ulong *pc)
 int      line2pc(ulong basepc, ulong line, ulong *pc)
 int      fnbound(ulong pc, ulong bounds[2])
 
 | 
 DESCRIPTION     
 |  |  |  | These functions provide machine-independent access to the symbol
    table of an executable file or executing process. Mach(3), mach-file(3),
    and mach-map(3) describe additional library functions for accessing
    executable files and executing processes. 
    
    
    Symopen uses the data in the Fhdr structure filled by crackhdr
    (see mach-file(3)) to initialize in-memory structures used to
    access the symbol tables contained in the file. Symclose frees
    the structures. The rest of the functions described here access
    a composite symbol table made up of all currently open tables.
    
    
    
    The set of all currently open Fhdrs is maintained as a linked
    list starting at fhdrlist (chained via Fhdr.next). 
    
    
    Findhdr searches the currently open Fhdrs for one whose file name
    ends with the path name (that is, libc.so matches /usr/lib/libc.so
    but not mylibc.so). 
    
    
    The Symbol data structure: 
 describes a symbol table entry. The 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 type field contains the type of the symbol:|  |  |  | typedef struct Symbol Symbol; struct Symbol
 {
 
 };|  |  |  | char    *name; Loc    loc;
 Loc    hiloc;
 char    class;
 char    type;
 ...
 
 | 
 
 | 
 The class field assigns the symbol to a general class; CTEXT,
    CDATA, CAUTO, and CPARAM are the most popular. 
    
    
    Indexsym stores information for the n th symbol into s. The symbols
    are ordered by increasing address. 
    
    
    Lookupsym fills a 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 fn and 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 var is
    zero, the text symbol table is searched for function fn. If only
    fn is zero, the global variable table is searched for var. 
    
    
    Findsym returns the symbol table entry of type class stored near
    addr. The selected symbol is a global variable or function with
    address nearest to and less than or equal to addr. Class specification
    CDATA searches only the global variable symbol table; class CTEXT
    limits the search to the text symbol table. Class specification
    CANY searches the text
    table first, then the global table. 
    
    
    Findexsym, flookupsym, and ffindsym are similar to indexsym, lookupsym,
    and findsym, but operate only on the symbols from hdr. Flookupsym
    and ffindsym return pointers to data stored in the hdr, which
    must not be modified or freed. 
    
    
    Indexlsym, lookuplsym, and findlsym are similar to indexsym, lookupsym,
    and findsym, but operate on the smaller symbol table of parameters
    and variables local to the function represented by symbol s1.
    
    
    
    Indexlsym writes symbol information for the nth local symbol of
    function s1 to s2. Function parameters appear first in the ordering,
    followed by local symbols. 
    
    
    Lookuplsym writes symbol information for the symbol named name
    in function s1 to s2. 
    
    
    Findlsym searches for a symbol local to the function s1 whose
    location is exactly loc, writing its symbol information to s2.
    Loc is almost always an indirection through a frame pointer register;
    the details vary from architecture to architecture. 
    
    
    Symoff converts a location to a symbol reference. The string containing
    that reference is of the form ‘name+offset’, where ‘name’ is the
    name of the nearest symbol with an address less than or equal
    to the target address, and ‘offset’ is the hexadecimal offset
    beyond that symbol. If ‘offset’ is zero, only the name of the
    symbol is printed. If no symbol is
    found within 4096 bytes of the address, the address is formatted
    as a hexadecimal address. Buf is the address of a buffer of n
    bytes to receive the formatted string. Addr is the address to
    be converted. Type is the type code of the search space: CTEXT,
    CDATA, or CANY. Symoff returns the length of the formatted string
    contained in buf. 
    
    
    Pc2file searches the symbol table to find the file and line number
    corresponding to the instruction at program counter pc. File is
    the address of a buffer of n bytes to receive the file name. Line
    receives the line number. 
    
    
    Pc2line is like pc2file but neglects to return information about
    the source file. 
    
    
    Fileline is also like pc2file, but returns the file and line number
    in the n-byte text buffer buf, formatted as ‘file:line’. 
    
    
    File2pc performs the opposite mapping: it stores in pc a text
    address associated with line line in file file. 
    
    
    Line2pc is similar: it converts a line number to an instruction
    address, storing it in pc. Since a line number does not uniquely
    identify an instruction (e.g., every source file has line 1),
    basepc specifies a text address from which the search begins.
    Usually this is the address of the first function in the file
    of interest. 
    
    
    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; 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 first address beyond the end of the target
    function. 
    
    
    All functions return 0 on success and –1 on error. When an error
    occurs, a message describing it is stored in the system error
    buffer where it is available via errstr.|  |  |  | T     text segment symbol t     static text segment symbol
 D     data segment symbol
 d     static data segment symbol
 B     bss segment symbol
 b     static bss segment symbol
 a     automatic (local) variable symbol
 p     function parameter symbol
 U     undefined symbol
 
 | 
 
 | 
 SOURCE     
 SEE ALSO     
 |  |