plan9fox/sys/man/2/symbol

.TH SYMBOL 2
.SH NAME
syminit, getsym, symbase, pc2sp, pc2line, textseg, line2addr, lookup, findlocal,
getauto, findsym, localsym, globalsym, textsym, file2pc, fileelem, filesym,
fileline, fnbound \- symbol table access functions
.SH SYNOPSIS
.B #include <u.h>
.br
.B #include <libc.h>
.br
.B #include <bio.h>
.br
.B #include <mach.h>
.PP
.ta \w'\fLmachines 'u
.B
int  syminit(int fd, Fhdr *fp)
.PP
.B
Sym  *getsym(int index)
.PP
.B
Sym  *symbase(long *nsyms)
.PP
.B
int  fileelem(Sym **fp, uchar *encname, char *buf, int n)
.PP
.B
int  filesym(int index, char *buf, int n)
.PP
.B
long pc2sp(uvlong pc)
.PP
.B
long pc2line(uvlong pc)
.PP
.B
void textseg(uvlong base, Fhdr *fp)
.PP
.B
uvlong line2addr(ulong line, uvlong basepc, uvlong endpc)
.PP
.B
int  lookup(char *fn, char *var, Symbol *s)
.PP
.B
int  findlocal(Symbol *s1, char *name, Symbol *s2)
.PP
.B
int  getauto(Symbol *s1, int off, int class, Symbol *s2)
.PP
.B
int  findsym(uvlong addr, int class, Symbol *s)
.PP
.B
int  localsym(Symbol *s, int index)
.PP
.B
int  globalsym(Symbol *s, int index)
.PP
.B
int  textsym(Symbol *s, int index)
.PP
.B
uvlong file2pc(char *file, ulong line)
.PP
.B
int  fileline(char *str, int n, uvlong addr)
.PP
.B
int  fnbound(uvlong addr, uvlong *bounds)
.SH 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
.B /proc/\fIpid\fP/text
as described in
.IR proc (3).
.IR Mach (2)
and
.IR object (2)
describe additional library functions
for processing executable and object files.
.PP
.IR Syminit ,
.IR getsym ,
.IR symbase ,
.IR fileelem ,
.IR pc2sp ,
.IR pc2line ,
and
.I line2addr
process the symbol table contained in an executable file
or the
.B text
image of an executing program.
The symbol table is stored internally as an array of
.B Sym
data structures as defined in
.IR a.out (6).
.PP
.I Syminit
uses the data in the
.B Fhdr
structure filled by
.I crackhdr
(see
.IR mach (2))
to read the raw symbol tables from the open file descriptor
.IR fd .
It returns the count of the number of symbols
or \-1 if an error occurs.
.PP
.I Getsym
returns the address of the
.IR i th
.B Sym
structure or zero if 
.I index
is out of range.
.PP
.I Symbase
returns the address of the first
.B Sym
structure in the symbol table.  The number of
entries in the symbol table is returned in
.IR nsyms .
.PP
.I Fileelem
converts a file name, encoded as described in
.IR a.out (6),
to a character string.  
.I Fp
is the base of
an array of pointers to file path components ordered by path index.
.I Encname
is the address of an array of encoded
file path components in the form of a
.B z
symbol table entry.  
.I Buf
and
.I n
specify the
address of a receiving character buffer and its length.
.I Fileelem
returns the length of the null-terminated string
that is at most
.IR n \-1
bytes long.
.PP
.I Filesym
is a higher-level interface to 
.IR fileelem .
It fills
.I buf
with the name of the
.IR i th
file and returns the length of the null-terminated string
that is at most
.IR 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
.I index
is too large or too small or an error occurs during file name
conversion.
.PP
.I 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
.BR .frame )
in the symbol table.
.PP
.I Pc2line
returns the line number of the statement associated
with the instruction address
.IR 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.
.PP
.I Pc2sp
and
.I 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
.IR syminit .
If the text segment address is changed, the application
program must invoke
.I textseg
to recalculate the boundaries of the segment.
.I Base
is the new base address of the text segment and
.I fp
points to the
.I Fhdr
data structure filled by
.IR crackhdr .
.PP
.I 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.
.PP
.IR Pc2sp ,
.IR pc2line ,
and
.I line2addr
return \-1 in the case of an error.
.PP
.IR Lookup ,
.IR findlocal ,
.IR getauto ,
.IR findsym ,
.IR localsym ,
.IR globalsym ,
.IR textsym ,
.IR file2pc ,
and
.I 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.
.I Syminit
must be called
prior to using these functions.
The
.B Symbol
data structure:
.IP
.EX
typedef struct {	
	void *handle;     /* private */
	struct {
	    char  *name;
	    long   value;
	    char   type;
	    char   class;
	};
} Symbol;
.EE
.LP
describes a symbol table entry.
The
.B 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
.B type
field contains the type of the symbol as defined in
.IR a.out (6).
The
.B class
field assigns the symbol to a general class;
.BR CTEXT ,
.BR CDATA ,
.BR CAUTO ,
and
.B CPARAM
are the most popular.
.PP
.I Lookup
fills a
.B 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
.I fn
and
.I 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
.I var
is
zero, the text symbol table is searched for function
.IR fn .
If only
.I fn
is zero, the global variable table
is searched for
.IR var .
.PP
.I Findlocal
fills
.I s2
with the symbol table data of the automatic variable
or parameter matching
.IR name .
.I S1
is a
.B Symbol
data structure describing a function or a local variable;
the latter resolves to its owning function.
.PP
.I Getauto
searches the local symbols associated with function
.I s1
for an automatic variable or parameter located at stack
offset
.IR off .
.I Class
selects the class of
variable:
.B CAUTO
or
.BR CPARAM .
.I S2
is the address of a
.B Symbol
data structure to receive the symbol table information
of the desired symbol.
.PP
.I Findsym
returns the symbol table entry of type
.I class
stored near
.IR addr .
The selected symbol is a global variable or function
with address nearest to and less than or equal to
.IR addr .
Class specification
.B CDATA
searches only the global variable symbol table; class
.B CTEXT
limits the search to the text symbol table.
Class specification
.B CANY
searches the text table first, then the global table.
.PP
.I Localsym
returns the
.IR i th
local variable in the function
associated with
.IR s .
.I S
may reference a function or a local variable; the latter
resolves to its owning function.
If the
.IR i th
local symbol exists,
.I s
is filled with the data describing it.
.PP
.I Globalsym
loads
.I s
with the symbol table information of the
.IR i th
global variable.
.PP
.I Textsym
loads
.I s
with the symbol table information of the
.IR i th
text symbol.  The text symbols are ordered
by increasing address.
.PP
.I File2pc
returns a text address associated with
.I line
in file
.IR file ,
or -1 on an error.
.PP
.I Fileline
converts text address
.I addr
to its equivalent
line number in a source file.  The result,
a null terminated character string of
the form
.LR file:line ,
is placed in buffer
.I str
of
.I n
bytes.
.PP
.I 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;
.I 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.
.I Fnbound
returns 1 if the address is within a text function, or zero
if the address selects no function.
.PP
Functions
.I file2pc
and
.I fileline
may produce inaccurate results when applied to
optimized code.
.PP
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
.IR errstr .
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR mach (2),
.IR object (2),
.IR errstr (2),
.IR proc (3),
.IR a.out (6)