glenda.party
term% ls -F
term% cat index.txt
SYMBOL(2)                     System Calls Manual                    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)

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 processing exe‐
       cutable and object files.

       Syminit,  getsym,  symbase,  fileelem,  pc2sp,  pc2line,  and line2addr
       process the symbol table contained in an executable 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 components 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  ap‐
       plies  to the 68020 architecture; 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 with the
       instruction address pc.  The line number is the absolute line number in
       the source file as seen by the compiler after pre-processing; the orig‐
       inal line number in the source file may be derived from this value  us‐
       ing 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 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.

       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 ba‐
       sic  symbol  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  seg‐
       ment,  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.

       Lookup fills a Symbol structure with symbol table information.   Global
       variables  and  functions are represented by a single name; local vari‐
       ables 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 automatic variable
       or parameter matching name.  S1 is a Symbol data structure describing a
       function  or  a local variable; the latter resolves to its owning func‐
       tion.

       Getauto searches the local symbols associated with function s1  for  an
       automatic variable or parameter located at stack offset off.  Class se‐
       lects 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 function with address near‐
       est 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.

       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 sym‐
       bol.  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 is placed in buffer str of n bytes.

       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 ad‐
       dresses of the function in the first and second elements of this array.
       The  start address is the address of the first instruction of the func‐
       tion; 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 re‐
       turns 1 if the address is within a text function, or zero  if  the  ad‐
       dress selects no function.

       Functions  file2pc and fileline may produce inaccurate results when ap‐
       plied to optimized code.

       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 errstr.

SOURCE
       /sys/src/libmach

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



                                                                     SYMBOL(2)