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  accessi-
       ble 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  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 applies 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 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 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
       basic 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 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.

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

       Findlocal fills s2 with the symbol table data of the automatic variable or parameter matching name.  S1 is a Symbol data structure describ-
       ing 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 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.

       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 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 argu-
       ment 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 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)