.TH MACH 2
.SH NAME
crackhdr, machbytype, machbyname, newmap, setmap, unusemap,
loadmap, findseg, get1, get2, get4, put1, put2, put4,
beswab, beswal, leswab, leswal \- machine-independent executable file access
.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 crackhdr(int fd, Fhdr *fp)
.PP
.B
void machbytype(int type)
.PP
.B
int machbyname(char *name)
.PP
.B
Map *newmap(Map *map, int fd, int n)
.PP
.B
int setmap(Map *map, ulong base, ulong end, ulong foffset,
.PP
.B
           char *name)
.PP
.B
void unusemap(Map *map, int seg)
.PP
.B
Map *loadmap(Map *map, int fd, Fhdr *fp)
.PP
.B
int findseg(Map *map, char *name)
.PP
.B
int get1(Map *map, ulong addr, uchar *buf, int n)
.PP
.B
int get2(Map *map, ulong addr, ushort *val)
.PP
.B
int get4(Map *map, ulong addr, long *val)
.PP
.B
int put1(Map *map, ulong addr, uchar *buf, int n)
.PP
.B
int put2(Map *map, ulong addr, ushort val)
.PP
.B
int put4(Map *map, ulong addr, long val)
.PP
.B
ushort beswab(ushort val)
.PP
.B
long beswal(long val)
.PP
.B
ushort leswab(ushort val)
.PP
.B
long leswal(long val)
.PP
.B
extern Mach mach;
.PP
.B
extern Machdata machdata;
.SH DESCRIPTION
These functions provide machine-independent access to
an executable file or executing process image.
The latter is accessed by opening either
.BR /proc/\fIpid\fP/text
or
.B /proc/\fIpid\fP/mem
as described in
.IR proc (3).
.IR Symbol (2)
and
.IR object (2)
describe other library functions
for machine-independent access to symbol tables and object files.
.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
.I Machbytype
and
.I machbyname
select the data structures and parameter
values associated with the specified architecture.
The former selects the architecture based on
the code stored in the
field named
.I type
in the
.B Fhdr
data structure.  The latter selects a processor
class by name; one of
.IR 68020 ,
.IR mips ,
.IR mipsco ,
.IR sparc ,
.IR sunsparc ,
.IR 386 ,
.IR 86 ,
or
.IR 960 .
These functions point the
.I mach
and
.I machdata
global variables to the proper
.I Mach
and
.I Machdata
data structures and load global variable
.I asstype 
with the disassembler type code.
.PP
A
.I map
is a data structure used to
transform an address in the address space
of an executable to an offset in a file or
executing image.  A map comprises one or more
.BR segments ,
each associating a range of addresses with an offset
in the file or memory image.  The range of one segment
may not overlap the range of another segment in the map.
Most maps define segments named `text' and `data' to
map the instruction and initialized data sections of
an executable file.  When the map is associated with
the memory image of an executing program, the range of
the `data' segment is usually extended to include the bss,
heap, and stack of the process and an additional segment, named `ublock',
maps the page containing the saved registers and process
state information.
.PP
.I Newmap
creates a map with
.I n
segments or recycles a map currently in use.
If
.I map
is zero, a new map is dynamically
allocated, otherwise it is assumed to
point to an existing dynamically allocated map whose
size is adjusted, as necessary.
The map is associated with the open file
descriptor
.I fd 
and all segments are marked as unused.
The address of the map is returned.  A zero
return indicates an allocation error.
.PP
.I Setmap
loads the first unused segment in
.I map
with the
segment mapping parameters.
.I Base
and
.I end
contain the lowest and highest virtual addresses
mapped by the segment.
.I Foffset
contains the offset in the executable
to the start of the segment.
.I Name
is a name to be attached to the segment.
.PP
.I Unusemap
marks segment number
.I seg
in map
.I map
unused.  Other
segments in the map remain unaffected.
.PP
.I Loadmap
uses the values in a
.B Fhdr
data structure (usually filled by
.IR crackhdr )
to initialize a default map for an executable file or executing
image.  If
.I map
is zero, a new map with two segments is dynamically allocated; otherwise,
.I map
is initialized with the appropriate values.  This function
returns the address of the map if successful,
zero on failure.  Two segments, named `text' and `data'
are defined in the map; they map the instruction and
initialized data sections of the program described by
the
.I Fhdr
structure.
.PP
.IR Get1 ,
.IR get2 ,
and
.I get4
retrieve the data stored at address
.I addr
in the program file or executable image associated
with
.IR map .
.I Get1
retrieves
.I n
bytes of data beginning at
.I addr
into
.IR buf .
.I Get2
and
.I get4
retrieve 16-bit and 32-bit values respectively,
into the location pointed to by
.IR val .
The value is byte-swapped if the source
byte order differs from that of the current architecture.
This implies that the value returned by
.I get4
may not be the same as the four-byte sequence
returned by
.I get1
when
.I n
is four; the former may be byte-swapped, the
latter is independent of source and target byte order.
If the file descriptor associated with
.I map
is negative, the address itself is placed in the
return location.  These functions return the number
of bytes read.  A \-1 indicates an error condition.
.PP
.IR Put1 ,
.IR put2 ,
and
.I put4
write to
the file or executing image associated with
.IR map .
The address is translated using the
map parameters and multi-byte quantities are
byte-swapped, if necessary, before they are written.
.I Put1
transfers
.I n
bytes stored at
.IR buf ;
.I put2
and
.I put4
write the 16-bit and 32-bit quantity contained in
.IR val ,
respectively.  The number of bytes transferred is returned.
A \-1 return value indicates an error.
.PP
.I Beswab
and
.I beswal
return the
.B ushort
and
.B long
big-endian representation of
.IR val ,
respectively.
.I Leswab
and
.I leswal
return the little-endian representation of the
.B ushort
and
.B long
contained in
.IR val .
.SH SOURCE
.B /sys/src/libmach
.SH "SEE ALSO"
.IR symbol (2),
.IR object (2),
.IR errstr (2),
.IR proc (3),
.IR a.out (6)
.SH DIAGNOSTICS
These routines set
.IR errstr .
