SYMBOL man page on Plan9

Printed from

SYMBOL(2)							     SYMBOL(2)

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

       #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)

       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

       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 orig‐
       inal 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  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‐

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

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


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

                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Plan9

List of man pages available for Plan9

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net