MACH-SYMBOL(3)                                     MACH-SYMBOL(3)

     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 execut-
          ing processes.

          Symopen uses the data in the Fhdr structure filled by
          crackhdr (see mach-file(3)) to initialize in-memory struc-
          tures used to access the symbol tables contained in the
          file.  Symclose frees the structures.  The rest of the func-
          tions described here access a composite symbol table made up
          of all currently open tables.

     MACH-SYMBOL(3)                                     MACH-SYMBOL(3)

          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:

               typedef struct Symbol Symbol;
               struct Symbol
               {
                       char  *name;
                       Loc   loc;
                       Loc   hiloc;
                       char  class;
                       char  type;
                       ...
               };

          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:

               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

          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

     MACH-SYMBOL(3)                                     MACH-SYMBOL(3)

          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 func-
          tion 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 sym-
          bol 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 rep-
          resented 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 informa-
          tion 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 `off-
          set' is the hexadecimal offset beyond that symbol.  If `off-
          set' 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.

     MACH-SYMBOL(3)                                     MACH-SYMBOL(3)

          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 instruc-
          tion 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 tar-
          get function.

          All functions return 0 on success and -1 on error.  When an
          error occurs, a message describing it is stored in the sys-
          tem error buffer where it is available via errstr.

     SOURCE
          /src/libmach

     SEE ALSO
          mach(3), mach-file(3), mach-map(3)