SYMBOL(2)                                               SYMBOL(2)

     NAME
          syminit, getsym, symbase, pc2sp, pc2line, textseg,
          line2addr, lookup, findlocal, getauto, findsym, localsym,
          globalsym, textsym, file2pc, fileelem, filesym, fileline,
          fnbound - symbol table access functions

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <bio.h>
          #include <mach.h>

          int  syminit(int fd, Fhdr *fp)

          Sym  *getsym(int index)

          Sym  *symbase(long *nsyms)

          int  fileelem(Sym **fp, uchar *encname, char *buf, int n)

          int  filesym(int index, char *buf, int n)

          long pc2sp(ulong pc)

          long pc2line(ulong pc)

          void textseg(ulong base, Fhdr *fp)

          long line2addr(ulong line, ulong basepc)

          int  lookup(char *fn, char *var, Symbol *s)

          int  findlocal(Symbol *s1, char *name, Symbol *s2)

          int  getauto(Symbol *s1, int off, int class, Symbol *s2)

          int  findsym(long addr, int class, Symbol *s)

          int  localsym(Symbol *s, int index)

          int  globalsym(Symbol *s, int index)

          int  textsym(Symbol *s, int index)

          long file2pc(char *file, ulong line)

          int  fileline(char *str, int n, ulong addr)

          int  fnbound(long addr, ulong *bounds)

     SYMBOL(2)                                               SYMBOL(2)

     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
          /proc/pid/text as described in proc(3). Mach(2) and
          object(2) describe additional library functions for process-
          ing executable and object files.

          Syminit, getsym, symbase, fileelem, pc2sp, pc2line, and
          line2addr process the symbol table contained in an exe-
          cutable file or the text image of an executing program.  The
          symbol table is stored internally as an array of Sym data
          structures as defined in a.out(6).

          Syminit uses the data in the Fhdr structure filled by
          crackhdr (see mach(2)) to read the raw symbol tables from
          the open file descriptor fd. It returns the count of the
          number of symbols or -1 if an error occurs.

          Getsym returns the address of the ith Sym structure or zero
          if index is out of range.

          Symbase returns the address of the first Sym structure in
          the symbol table.  The number of entries in the symbol table
          is returned in nsyms.

          Fileelem converts a file name, encoded as described in
          a.out(6), to a character string. Fp is the base of an array
          of pointers to file path components ordered by path index.
          Encname is the address of an array of encoded file path com-
          ponents in the form of a z symbol table entry. Buf and n
          specify the address of a receiving character buffer and its
          length.  Fileelem returns the length of the null-terminated
          string that is at most n-1 bytes long.

          Filesym is a higher-level interface to fileelem. It fills
          buf with the name of the ith file and returns the length of
          the null-terminated string that is at most 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 index is too large or too
          small or an error occurs during file name conversion.

          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 architec-
          ture; other architectures use a fixed stack frame offset by
          a constant contained in a dummy local variable (called
          .frame) in the symbol table.

          Pc2line returns the line number of the statement associated

     SYMBOL(2)                                               SYMBOL(2)

          with the instruction address pc. The line number is the
          absolute line number in the source file as seen by the com-
          piler 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.

          Pc2sp and 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 syminit. If the
          text segment address is changed, the application program
          must invoke textseg to recalculate the boundaries of the
          segment.  Base is the new base address of the text segment
          and fp points to the Fhdr data structure filled by crackhdr.

          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 instruc-
          tion 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.

          Pc2sp, pc2line, and line2addr return -1 in the case of an
          error.

          Lookup, findlocal, getauto, findsym, localsym, globalsym,
          textsym, file2pc, and 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 sym-
          bol table data.  Syminit must be called prior to using these
          functions.  The Symbol data structure:

               typedef struct {
                        void *handle;     /* private */
                        struct {
                            char  *name;
                            long   value;
                            char   type;
                            char   class;
                        };
               } Symbol;

          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 as defined in
          a.out(6). The class field assigns the symbol to a general
          class; CTEXT, CDATA, CAUTO, and CPARAM are the most popular.

     SYMBOL(2)                                               SYMBOL(2)

          Lookup fills a Symbol structure with symbol table informa-
          tion.  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.

          Findlocal fills s2 with the symbol table data of the auto-
          matic variable or parameter matching name. S1 is a Symbol
          data structure describing a function or a local variable;
          the latter resolves to its owning function.

          Getauto searches the local symbols associated with function
          s1 for an automatic variable or parameter located at stack
          offset off. Class selects the class of variable: CAUTO or
          CPARAM.  S2 is the address of a Symbol data structure to
          receive the symbol table information of the desired symbol.

          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.

          Localsym returns the ith local variable in the function
          associated with s. S may reference a function or a local
          variable; the latter resolves to its owning function.  If
          the ith local symbol exists, s is filled with the data
          describing it.

          Globalsym loads s with the symbol table information of the
          ith global variable.

          Textsym loads s with the symbol table information of the ith
          text symbol.  The text symbols are ordered by increasing
          address.

          File2pc returns a text address associated with line in file
          file, or -1 on an error.

          Fileline converts text address addr to its equivalent line
          number in a source file.  The result, a null terminated
          character string of the form `file:line', is placed in
          buffer str of n bytes.

          Fnbound returns the start and end addresses of the function

     SYMBOL(2)                                               SYMBOL(2)

          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 address of the start of the next function
          in memory, so it is beyond the end of the target function.
          Fnbound returns 1 if the address is within a text function,
          or zero if the address selects no function.

          Functions file2pc and fileline may produce inaccurate
          results when applied to optimized code.

          Unless otherwise specified, all functions return 1 on suc-
          cess, or 0 on error.  When an error occurs, a message
          describing it is stored in the system error buffer where it
          is available via errstr.

     SOURCE
          /sys/src/libmach

     SEE ALSO
          mach(2), object(2), errstr(2), proc(3), a.out(6)