MACHINES(2X) MACHINES(2X)
NAME
crackhdr, syminit, getsym, symbase, pc2sp, pc2line,
line2addr, lookup, findlocal, getauto, findsym, localsym,
globalsym, textsym, file2pc, fileelem, fileline, newmap,
setmap, unusemap, freemap, loadmap, mget, mput, beswab,
beswal, leswab, leswal - machine dependent library
SYNOPSIS
#include <mach.h>
int crackhdr(int fd, Fhdr *fp)
int syminit(int fd, Fhdr *fp)
Sym *getsym(int index)
Sym *symbase(long *nsyms)
int fileelem(Sym **fp, uchar *encname, char *buf, int n)
long pc2sp(ulong pc)
long pc2line(ulong pc)
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)
Map *newmap(Map *map, int fd)
int setmap(Map *map, int seg, ulong base, ulong end, ulong
foffset)
void unusemap(Map *map, int seg)
MACHINES(2X) MACHINES(2X)
Map *loadmap(Map *map, int fd, Fhdr *fp)
int mget(Map *map, int seg, ulong addr, char *buf, int
size)
int mput(Map *map, int seg, ulong addr, char *buf, int size)
ushort beswab(ushort s)
long beswal(long l)
ushort leswab(ushort s)
long leswal(long l)
DESCRIPTION
The functions in this library provide machine-independent
interpretation of executable and object files and executing
process images.
Crackhdr loads data structure fp with a machine-independent
description of the header of the executable file or image
associated with the open file descriptor fd. It also sets
global variable mach pointing to the Mach data structure
containing the machine-dependent parameters of the target
architecture.
Syminit, getsym, symbase, fileelem, pc2sp, pc2line, and
line2addr process the symbol table contained in an exe-
cutable file. The symbol table is stored internally as an
array of Sym structures as defined in a.out(6).
Syminit uses the Fhdr structure filled by crackhdr to load
the raw symbol tables from the open file descriptor fd. It
returns the count of the number of symbols in the symbol
table 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 element of the vec-
tor of Sym structures comprising the symbol table. The
argument is the address of a long that is loaded with the
number of entries in the symbol table.
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 file path components
in the form of a z symbol table entry. Buf and n specify the
address of a character buffer and its length. Fileelem
returns the length of the null-terminated string that is at
MACHINES(2X) MACHINES(2X)
most n-1 bytes long.
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 algorithm is only valid for the 386 and 68020
architectures; other architectures use a fixed frame acces-
sible through a dummy local variable.
Pc2line returns the line number of the statement associated
with the instruction address pc. The line number returned is
the absolute line number in the file as seen by the compiler
after pre-processing; the original line number in the source
file may derived from this value using the history stacks
contained in the symbol table.
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 instruc-
tion location (every source file has line 1), a second argu-
ment 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 sym-
bol table. Syminit must be called prior to invoking 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 that 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.
MACHINES(2X) MACHINES(2X)
Lookup fills a Symbol structure with symbol table informa-
tion. 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
fnandvar 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 auto-
matic 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 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 func-
tion 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 sym-
bol table. Class specification CANY searches the text table
first, then the global table.
Localsym returns the ith local variable associated with the
function indicated by 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 symbol. The text symbols are ordered by increasing
address.
File2pc returns a text address associated with line in file
file.
Fileline converts text address addr to its equivalent line
number in a source file. The result, a null terminated
character string of the form file:line is placed in buffer
str of n bytes. Up to n-1 characters are copied to the
buffer.
MACHINES(2X) MACHINES(2X)
Functions file2pc and fileline may produce inaccurate
results when applied to optimized code.
A Map is a data structure used to transform an address in
the logical address space of an executable to an offset in a
file or executing image. Each map comprises up to four log-
ical segments, named SEGDATA, SEGTEXT, SEGUBLK, and SEGREGS,
that map the data, text, `u block', and register segments,
respectively. A section of the physical address space may
be mapped by multiple segments. A segment contains the low
and high addresses of the logical address space of the seg-
ment and the physical offset in the file or executing image
to the base of the address space.
Newmap creates a new map or recycles one currently in use.
If map is zero, a new map is dynamically allocated, other-
wise it is assumed to point to an existing map. The map is
marked empty and attached to the open file descriptor fd.
The address of the map is returned.
Setmap loads segment seg of map with the segment mapping
parameters. Base and end contain the lowest and highest
virtual addresses mapped by the segment, respectively.
Foffset contains the offset in the file or executable image
to the start of the segment.
Unusemap marks segment seg in map map empty. Other segments
in the map remain unaffected.
Loadmap uses the Fhdr data structure filled by crackhdr to
initialize a map for an executable file or executing image.
If map is zero, a new map is dynamically allocated; other-
wise, map is initialized with the appropriate values. This
function returns the address of the map if successful or
zero on failure.
Mget reads size bytes into buf from the file associated with
map. The data is read from logical address addr in segment
seg. Fput is similar except it writes to the executable file
or executing image associated with map. Both functions
return -1 if they are unable to calculate a physical
address, 0 if the read or write operation fails, and 1 on
success. The segment may be one of SEGTEXT, SEGDATA,
SEGUBLK, or SEGREGS, or the special segment, SEGANY. If
SEGANY is specified, the address translation is performed
using the text, data, and u-block maps, in that order.
Accesses to SEGDATA first attempt a translation using the
data map then the u-block map. The read or write operation
takes place at the address produced by the first valid
translation.
Beswab, and beswal convert a big-endian ushort and long
MACHINES(2X) MACHINES(2X)
respectively, to the target processor's native representa-
tion. Leswab, and leswal perform the same conversion for a
little-endian ushort and long respectively.
Unless otherwise specified, all functions return 1 on suc-
cess, or 0 on error.
SEE ALSO
a.out(6)