diff options
Diffstat (limited to 'man/man3/mach-map.html')
| -rw-r--r-- | man/man3/mach-map.html | 312 |
1 files changed, 312 insertions, 0 deletions
diff --git a/man/man3/mach-map.html b/man/man3/mach-map.html new file mode 100644 index 00000000..ddf7275f --- /dev/null +++ b/man/man3/mach-map.html @@ -0,0 +1,312 @@ +<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> |