term% cat index.txt 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 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
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 ap‐
plies 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 us‐
ing 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 ba‐
sic 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‐
tion.
Getauto searches the local symbols associated with function s1 for an
automatic variable or parameter located at stack offset off. Class se‐
lects 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
variable.
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 ad‐
dresses of the function in the first and second elements of this array.
The start address is the address of the first instruction of the func‐
tion; 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 re‐
turns 1 if the address is within a text function, or zero if the ad‐
dress selects no function.
Functions file2pc and fileline may produce inaccurate results when ap‐
plied 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)