.TH MACHINES 2X
.SH 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
.SH SYNOPSIS
.B #include <mach.h>
.PP
.ta \w'\fLmachines 'u
.B
int  crackhdr(int fd, Fhdr *fp)
.PP
.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
long pc2sp(ulong pc)
.PP
.B
long pc2line(ulong pc)
.PP
.B
long line2addr(ulong line, ulong basepc)
.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(long 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
long file2pc(char *file, ulong line)
.PP
.B
int fileline(char *str, int n, ulong addr)
.PP
.B
Map  *newmap(Map *map, int fd)
.PP
.B
int  setmap(Map *map, int seg, ulong base, ulong end, ulong foffset)
.PP
.B
void unusemap(Map *map, int seg)
.PP
.B
Map  *loadmap(Map *map, int fd, Fhdr *fp)
.PP
.B
int  mget(Map *map, int seg, ulong addr, char *buf, int size)
.PP
.B
int mput(Map *map, int seg, ulong addr, char *buf, int size)
.PP
.B
ushort beswab(ushort s)
.PP
.B
long beswal(long l)
.PP
.B
ushort leswab(ushort s)
.PP
.B
long leswal(long l)
.SH DESCRIPTION
The functions in this library provide machine-independent interpretation
of executable and object files and executing process images.
.PP
.I Crackhdr
loads data structure
.I fp
with a machine-independent description of the
header of the executable file or image associated
with the open file descriptor
.IR fd .
It also sets global variable
.I mach
pointing to the
.B Mach
data structure containing the machine-dependent parameters
of the target architecture.
.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.
The symbol table is stored internally as an array of
.B Sym
structures as defined in
.IR a.out (6).
.PP
.I Syminit
uses the
.B Fhdr
structure filled by
.I crackhdr
to load the raw symbol tables from the open file descriptor
.IR fd .
It returns the count of the number of symbols in the
symbol table 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 element of the vector of
.I 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.
.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
file path components in the form of a
.B z
symbol table entry.  
.I Buf
and
.I n
specify the
address of a character buffer and its length.
.I Fileelem
returns the length of the null-terminated string
that is at most
.I n-1
bytes long.
.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 algorithm is only valid
for the 386 and 68020 architectures; other architectures
use a fixed frame accessible through a dummy local variable.
.PP
.I Pc2line
returns the line number of the statement associated
with the instruction address
.IR 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.
.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 (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.
.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.
.I Syminit
must be called
prior to invoking 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 that 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
.IR 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
.I var
is
zero, the text symbol table is searched for function
.I 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
.I 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 associated with the function
indicated by
.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 .
.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
.B file:line
is placed in buffer
.I str
of
.I n
bytes.
Up to
.I n-1
characters are copied to the buffer.
.PP
Functions
.I file2pc
and
.I fileline
may produce inaccurate results when applied to
optimized code.
.PP
A
.I 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 logical
.BR segments ,
named
.BR SEGDATA ,
.BR SEGTEXT ,
.BR SEGUBLK ,
and
.BR 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 segment and the physical offset in the file
or executing image to the base of the address space.
.PP
.I Newmap
creates a new map or recycles one currently in use.
If
.I map
is zero, a new map is dynamically
allocated, otherwise it is assumed to
point to an existing map.
The map is marked empty and attached to the open file
descriptor
.IR fd .
The address of the map is returned.
.PP
.I Setmap
loads segment 
.I seg
of
.I map
with the
segment mapping parameters.
.I Base
and
.I end
contain the lowest and highest virtual addresses
mapped by the segment, respectively.
.I Foffset
contains the offset in the file or executable image
to the start of the segment.
.PP
.I Unusemap
marks segment
.I seg
in map
.I map
empty.  Other
segments in the map remain unaffected.
.PP
.I Loadmap
uses the
.B Fhdr
data structure filled by
.I crackhdr
to initialize a map for an executable file or executing
image.  If
.I map
is zero, a new map is dynamically allocated; otherwise,
.I map
is initialized with the appropriate values.  This function
returns the address of the map if successful or
zero on failure.
.PP
.I Mget
reads 
.I size
bytes into
.I buf
from the file associated with
.IR map .
The data is read from logical address
.I addr
in segment
.IR seg .
.I Fput
is similar except it writes to the executable file or
executing image associated with
.IR 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
.BR SEGTEXT ,
.BR SEGDATA ,
.BR SEGUBLK ,
or
.BR SEGREGS ,
or the special segment,
.BR SEGANY .
If
.B 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.
.PP
.IR Beswab ,
and
.IR beswal
convert a big-endian ushort and long respectively, to
the target processor's native representation.
.IR Leswab ,
and
.IR leswal
perform the same conversion for a little-endian ushort
and long respectively.
.PP
Unless otherwise specified, all functions return 1
on success, or 0 on error.
.SH "SEE ALSO"
.IR a.out (6)