436 lines
9.2 KiB
Text
436 lines
9.2 KiB
Text
.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
|
|
uvlong pc2sp(uvlong pc)
|
|
.PP
|
|
.B
|
|
long pc2line(uvlong pc)
|
|
.PP
|
|
.B
|
|
void textseg(uvlong base, Fhdr *fp)
|
|
.PP
|
|
.B
|
|
uvlong line2addr(long 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, long line)
|
|
.PP
|
|
.B
|
|
long 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)
|