Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

Plan 9 - man page for symbol (plan9 section 2)

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 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 ta-
       ble 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 sym-
       bol 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 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 recalcu-
       late 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 func-
       tion 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  func-
       tions.  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 func-
       tions are represented by a single name; local variables and parameters are uniquely speci-
       fied 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 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 informa-
       tion of the desired symbol.

       Findsym	returns the symbol table entry of type class stored near addr.	The selected sym-
       bol 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 refer-
       ence 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 sym-
       bols 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 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)


All times are GMT -4. The time now is 12:51 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password