312 lines
15 KiB
HTML
312 lines
15 KiB
HTML
<head>
|
|
<title>mach-map(3) - Plan 9 from User Space</title>
|
|
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
|
|
</head>
|
|
<body bgcolor=#ffffff>
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=10><td>
|
|
<tr><td width=20><td>
|
|
<tr><td width=20><td><b>MACH-MAP(3)</b><td align=right><b>MACH-MAP(3)</b>
|
|
<tr><td width=20><td colspan=2>
|
|
<br>
|
|
<p><font size=+1><b>NAME </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
allocmap, addseg, findseg, addrtoseg, addrtosegafter, removeseg,
|
|
freemap, get1, get2, get4, get8, put1, put2, put4, put8, rget,
|
|
rput, fpformat, locnone, locaddr, locconst, locreg, locindir,
|
|
loccmp, loceval, locfmt, locsimplify, lget1, lget2, lget4, lget8,
|
|
lput1, lput2, lput4, lput8 – machine-independent access to address
|
|
spaces and register sets<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SYNOPSIS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>#include <u.h><br>
|
|
#include <libc.h><br>
|
|
#include <mach.h>
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
</font></tt>
|
|
typedef struct Map Map;<br>
|
|
typedef struct Seg Seg;<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
struct Seg<br>
|
|
{<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
char *name;<br>
|
|
char *file;<br>
|
|
int fd;<br>
|
|
ulong base;<br>
|
|
ulong size;<br>
|
|
ulong offset;<br>
|
|
int (*rw)(Map*, Seg*, ulong, void*, uint, int);<br>
|
|
|
|
</table>
|
|
};<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
struct Map<br>
|
|
{<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
Seg *seg;<br>
|
|
int nseg;<br>
|
|
<i>...<br>
|
|
</i>
|
|
</table>
|
|
};<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Map *allocmap(void)<br>
|
|
int addseg(Map *map, Seg seg)<br>
|
|
int findseg(Map *map, char *name, char *file)<br>
|
|
int addrtoseg(Map *map, ulong addr, Seg *seg)<br>
|
|
int addrtosegafter(Map *map, ulong addr, Seg *seg)<br>
|
|
void removeseg(Map *map, int i)<br>
|
|
void freemap(Map *map)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
int get1(Map *map, ulong addr, uchar *a, uint n)<br>
|
|
int get2(Map *map, ulong addr, u16int *u)<br>
|
|
int get4(Map *map, ulong addr, u32int *u)<br>
|
|
int get8(Map *map, ulong addr, u64int *u)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
int put1(Map *map, ulong addr, uchar *a, uint n)<br>
|
|
int put2(Map *map, ulong addr, u16int u)<br>
|
|
int put4(Map *map, ulong addr, u32int u)<br>
|
|
int put8(Map *map, ulong addr, u64int u)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
int rget(Regs *regs, char *reg, ulong *u)<br>
|
|
int fpformat(Map *map, char *reg, char *a, uint n, char code);<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
int rput(Regs *regs, char *name, ulong u)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Loc locnone(void)<br>
|
|
Loc locaddr(ulong addr)<br>
|
|
Loc locconst(ulong con)<br>
|
|
Loc locreg(char *reg)<br>
|
|
Loc locindir(char *reg, long offset)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
int loccmp(Loc *a, Loc *b)<br>
|
|
int loceval(Map *map, Loc loc, ulong *addr)<br>
|
|
int locfmt(Fmt *fmt)<br>
|
|
int locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
int lget1(Map *map, Loc loc, uchar *a, uint n)<br>
|
|
int lget2(Map *map, Loc loc, u16int *u)<br>
|
|
int lget4(Map *map, Loc loc, u32int *u)<br>
|
|
int lget8(Map *map, Loc loc, u64int *u)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
int lput1(Map *map, Loc loc, uchar *a, uint n)<br>
|
|
int lput2(Map *map, Loc loc, u16int u)<br>
|
|
int lput4(Map *map, Loc loc, u32int u)<br>
|
|
int lput8(Map *map, Loc loc, u64int u)<br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
|
|
</table>
|
|
<p><font size=+1><b>DESCRIPTION </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
These functions provide a processor-independent interface for
|
|
accessing executable files, core files, and running processes
|
|
via <i>maps</i>, data structures that provides access to an address space
|
|
and register set. The functions described in <a href="../man3/mach-file.html"><i>mach-file</i>(3)</a> are
|
|
typically used to construct these maps. Related library functions
|
|
described in <a href="../man3/mach-symbol.html"><i>mach-symbol</i>(3)</a> provide similar access to symbol tables.
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Each <i>map</i> comprises an optional register set and one or more <tt><font size=+1>segments</font></tt>,
|
|
each associating a non-overlapping range of memory addresses with
|
|
a logical section of an executable file or of a running process’s
|
|
address space. Other library functions then use a map and the
|
|
architecture-specific data structures to provide
|
|
a generic interface to the processor-dependent data.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Each segment has a name (e.g., <tt><font size=+1>text</font></tt> or <tt><font size=+1>data</font></tt>) and may be associated
|
|
with a particular file. A segment represents a range of accessible
|
|
address space. Segments may be backed an arbitary access function
|
|
(if the <tt><font size=+1>rw</font></tt> pointer is non-nil), or by the contents of an open
|
|
file (using the <tt><font size=+1>fd</font></tt> file descriptor). Each range has a
|
|
starting address in the space (<tt><font size=+1>base</font></tt>) and an extent (<tt><font size=+1>size</font></tt>). In
|
|
segments mapped by files, the range begins at byte <tt><font size=+1>offset</font></tt> in the
|
|
file. The <tt><font size=+1>rw</font></tt> function is most commonly used to provide access
|
|
to executing processes via <a href="../man2/ptrace.html"><i>ptrace</i>(2)</a> and to zeroed segments.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Allocmap</i> creates an empty map; <i>freemap</i> frees a map.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Addseg</i> adds the given segment to the map, resizing the map’s <i>seg</i>
|
|
array if necessary. A negative return value indicates an allocation
|
|
error.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Findseg</i> returns the index of the segment with the given name (and,
|
|
if <i>file</i> is non-nil, the given file), or –1 if no such segment is
|
|
found.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Addrtoseg</i> returns the index of the segment containing for the
|
|
given address, or –1 if that address is not mapped. Segments may
|
|
have overlapping address ranges: <i>addseg</i> appends segments to the
|
|
end of the <i>seg</i> array in the map, and <i>addrtoseg</i> searches the map
|
|
backwards from the end, so the most recently mapped
|
|
segment wins.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Addrtosegafter</i> returns the index of the segment containing the
|
|
lowest mapped address greater than <i>addr</i>.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Removeseg</i> removes the segment at the given index.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Get1</i>, <i>get2</i>, <i>get4</i>, and <i>get8</i> retrieve the data stored at address
|
|
<i>addr</i> in the address space associated with <i>map</i>. <i>Get1</i> retrieves
|
|
<i>n</i> bytes of data beginning at <i>addr</i> into <i>buf</i>. <i>Get2</i>, <i>get4</i> and <i>get8</i>
|
|
retrieve 16-bit, 32-bit and 64-bit values respectively, into the
|
|
location pointed to by <i>u</i>. 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>get2</i>, <i>get4</i>, and <i>get8</i> may not
|
|
be the same as the byte sequences returned by <i>get1</i> when <i>n</i> is two,
|
|
four or eight; the former may be byte-swapped, the latter reflects
|
|
the byte order of the target architecture. These functions
|
|
return the number of bytes read or a –1 when there is an error.
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Put1</i>, <i>put2</i>, <i>put4</i>, and <i>put8</i> write to the address space associated
|
|
with <i>map</i>. The address is translated using the map parameters and
|
|
multi-byte quantities are byte-swapped, if necessary, before they
|
|
are written. <i>Put1</i> transfers <i>n</i> bytes stored at <i>buf</i>; <i>put2</i>, <i>put4</i>,
|
|
and <i>put8</i> write the 16-bit, 32-bit or 64-bit quantity
|
|
contained in <i>val</i>, respectively. The number of bytes transferred
|
|
is returned. A –1 return value indicates an error.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
When representing core files or running programs, maps also provide
|
|
access to the register set. <i>Rget</i> and <i>rput</i> read or write the register
|
|
named by <i>reg</i>. If the register is smaller than a <tt><font size=+1>ulong</font></tt>, the high
|
|
bits are ignored.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Fpformat</i> converts the contents of a floating-point register to
|
|
a string. <i>Buf</i> is the address of a buffer of <i>n</i> bytes to hold the
|
|
resulting string. <i>Code</i> must be either <tt><font size=+1>F</font></tt> or <tt><font size=+1>f</font></tt>, selecting double
|
|
or single precision, respectively. If <i>code</i> is <tt><font size=+1>F</font></tt>, the contents
|
|
of the specified register and the following register are interpreted
|
|
as a
|
|
double-precision floating-point number; this is meaningful only
|
|
for architectures that implement double-precision floats by combining
|
|
adjacent single-precision registers.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
A <i>location</i> represents a place in an executing image capable of
|
|
storing a value. Note that locations are typically passed by value
|
|
rather than by reference.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Locnone</i> returns an unreadable, unwritable location. <i>Locaddr</i> returns
|
|
a location representing the memory address <i>addr</i>. <i>Locreg</i> returns
|
|
a location representing the register <i>reg</i>. <i>Locindir</i> returns an
|
|
location representing the memory address at <i>offset</i> added to the
|
|
value of <i>reg</i>. <i>Locconst</i> returns an imaginary unwritable
|
|
location holding the constant <i>con</i>; such locations are useful for
|
|
passing specific constants to functions expect locations, such
|
|
as <i>unwind</i> (see <a href="../man3/mach-stack.html"><i>mach-stack</i>(3)</a>).
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Loccmp</i> compares two locations, returning negative, zero, or positive
|
|
values if <tt><font size=+1>*a</font></tt> is less than, equal to, or greater than <tt><font size=+1>*b</font></tt>, respectively.
|
|
Register locations are ordered before memory addresses, which
|
|
are ordered before indirections.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
<i>Locfmt</i> is a <a href="../man3/print.html"><i>print</i>(3)</a>-verb that formats a <tt><font size=+1>Loc</font></tt> structure (<i>not</i> a
|
|
pointer to one).
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
Indirection locations are needed in some contexts (e.g., when
|
|
using <i>findlsym</i> (see <a href="../man3/mach-symbol.html"><i>mach-symbol</i>(3)</a>)), but bothersome in most.
|
|
<i>Locsimplify</i> rewrites indirections as absolute memory addresses,
|
|
by evaluating the register using the given map and adding the
|
|
offset.
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
|
|
|
The functions <i>lget1</i>, <i>lget2</i>, <i>lget4</i>, <i>lget8</i>, <i>lput1</i>, <i>lput2</i>, <i>lput4</i>,
|
|
and <i>lput8</i> read and write the given locations, using the <i>get</i>, <i>put</i>,
|
|
<i>rget</i>, and <i>rput</i> function families as necessary.<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>SOURCE </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<tt><font size=+1>/usr/local/plan9/src/libmach<br>
|
|
</font></tt>
|
|
</table>
|
|
<p><font size=+1><b>SEE ALSO </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
<a href="../man3/mach.html"><i>mach</i>(3)</a>, <a href="../man3/mach-file.html"><i>mach-file</i>(3)</a><br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>DIAGNOSTICS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
These routines set <i>errstr</i>.<br>
|
|
|
|
</table>
|
|
<p><font size=+1><b>BUGS </b></font><br>
|
|
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
|
|
|
This man page needs to describe <tt><font size=+1>Regs</font></tt> and <tt><font size=+1>Regdesc<br>
|
|
</font></tt>
|
|
</table>
|
|
|
|
<td width=20>
|
|
<tr height=20><td>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
|
<tr height=15><td width=10><td><td width=10>
|
|
<tr><td><td>
|
|
<center>
|
|
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
|
|
</center>
|
|
</table>
|
|
<!-- TRAILER -->
|
|
</body></html>
|