mach-map(3) - Plan 9 from User Space

From 78e51a8c6678b6e3dff3d619aa786669f531f4bc Mon Sep 17 00:00:00 2001 From: rsc Date: Fri, 14 Jan 2005 03:45:44 +0000 Subject: checkpoint --- man/man3/mach-map.html | 312 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 312 insertions(+) create mode 100644 man/man3/mach-map.html (limited to 'man/man3/mach-map.html') 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 @@ + +mach-map(3) - Plan 9 from User Space + + + + +

MACH-MAP(3) MACH-MAP(3) +

+
+

NAME
+ +
+ + 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
+ +
+

SYNOPSIS
+ +
+ + #include <u.h> + #include <libc.h> + #include <mach.h> + + + typedef struct Map Map;
+ typedef struct Seg Seg;
+ +
+ + struct Seg
+ {
+ +
+ + char    *name;
+ char    *file;
+ int     fd;
+ ulong    base;
+ ulong    size;
+ ulong    offset;
+ int     (*rw)(Map*, Seg*, ulong, void*, uint, int);
+ +
+ };
+ +
+ + struct Map
+ {
+ +
+ + Seg     *seg;
+ int     nseg;
+ ...
+ +
+ };
+ +
+ + Map    *allocmap(void)
+ int     addseg(Map *map, Seg seg)
+ int     findseg(Map *map, char *name, char *file)
+ int     addrtoseg(Map *map, ulong addr, Seg *seg)
+ int     addrtosegafter(Map *map, ulong addr, Seg *seg)
+ void    removeseg(Map *map, int i)
+ void    freemap(Map *map)
+ +
+ + int     get1(Map *map, ulong addr, uchar *a, uint n)
+ int     get2(Map *map, ulong addr, u16int *u)
+ int     get4(Map *map, ulong addr, u32int *u)
+ int     get8(Map *map, ulong addr, u64int *u)
+ +
+ + int     put1(Map *map, ulong addr, uchar *a, uint n)
+ int     put2(Map *map, ulong addr, u16int u)
+ int     put4(Map *map, ulong addr, u32int u)
+ int     put8(Map *map, ulong addr, u64int u)
+ +
+ + int     rget(Regs *regs, char *reg, ulong *u)
+ int     fpformat(Map *map, char *reg, char *a, uint n, char code);
+ +
+ + int     rput(Regs *regs, char *name, ulong u)
+ +
+ + Loc    locnone(void)
+ Loc    locaddr(ulong addr)
+ Loc    locconst(ulong con)
+ Loc    locreg(char *reg)
+ Loc    locindir(char *reg, long offset)
+ +
+ + int     loccmp(Loc *a, Loc *b)
+ int     loceval(Map *map, Loc loc, ulong *addr)
+ int     locfmt(Fmt *fmt)
+ int     locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc)
+ +
+ + int     lget1(Map *map, Loc loc, uchar *a, uint n)
+ int     lget2(Map *map, Loc loc, u16int *u)
+ int     lget4(Map *map, Loc loc, u32int *u)
+ int     lget8(Map *map, Loc loc, u64int *u)
+ +
+ + int     lput1(Map *map, Loc loc, uchar *a, uint n)
+ int     lput2(Map *map, Loc loc, u16int u)
+ int     lput4(Map *map, Loc loc, u32int u)
+ int     lput8(Map *map, Loc loc, u64int u)
+ +
+ + +
+

DESCRIPTION
+ +
+ + These functions provide a processor-independent interface for + accessing executable files, core files, and running processes + via maps, data structures that provides access to an address space + and register set. The functions described in mach-file(3) are + typically used to construct these maps. Related library functions + described in mach-symbol(3) provide similar access to symbol tables. + +
+ + Each map comprises an optional register set and one or more segments, + 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. +
+ + Each segment has a name (e.g., text or data) 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 rw pointer is non-nil), or by the contents of an open + file (using the fd file descriptor). Each range has a + starting address in the space (base) and an extent (size). In + segments mapped by files, the range begins at byte offset in the + file. The rw function is most commonly used to provide access + to executing processes via ptrace(2) and to zeroed segments. +
+ + Allocmap creates an empty map; freemap frees a map. +
+ + Addseg adds the given segment to the map, resizing the map’s seg + array if necessary. A negative return value indicates an allocation + error. +
+ + Findseg returns the index of the segment with the given name (and, + if file is non-nil, the given file), or –1 if no such segment is + found. +
+ + Addrtoseg 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: addseg appends segments to the + end of the seg array in the map, and addrtoseg searches the map + backwards from the end, so the most recently mapped + segment wins. +
+ + Addrtosegafter returns the index of the segment containing the + lowest mapped address greater than addr. +
+ + Removeseg removes the segment at the given index. +
+ + Get1, get2, get4, and get8 retrieve the data stored at address + addr in the address space associated with map. Get1 retrieves + n bytes of data beginning at addr into buf. Get2, get4 and get8 + retrieve 16-bit, 32-bit and 64-bit values respectively, into the + location pointed to by u. The value is byte-swapped if the source + byte order differs from that of the current architecture. This + implies that the value returned by get2, get4, and get8 may not + be the same as the byte sequences returned by get1 when n 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. + +
+ + Put1, put2, put4, and put8 write to the address space associated + with map. The address is translated using the map parameters and + multi-byte quantities are byte-swapped, if necessary, before they + are written. Put1 transfers n bytes stored at buf; put2, put4, + and put8 write the 16-bit, 32-bit or 64-bit quantity + contained in val, respectively. The number of bytes transferred + is returned. A –1 return value indicates an error. +
+ + When representing core files or running programs, maps also provide + access to the register set. Rget and rput read or write the register + named by reg. If the register is smaller than a ulong, the high + bits are ignored. +
+ + Fpformat converts the contents of a floating-point register to + a string. Buf is the address of a buffer of n bytes to hold the + resulting string. Code must be either F or f, selecting double + or single precision, respectively. If code is F, 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. +
+ + A location represents a place in an executing image capable of + storing a value. Note that locations are typically passed by value + rather than by reference. +
+ + Locnone returns an unreadable, unwritable location. Locaddr returns + a location representing the memory address addr. Locreg returns + a location representing the register reg. Locindir returns an + location representing the memory address at offset added to the + value of reg. Locconst returns an imaginary unwritable + location holding the constant con; such locations are useful for + passing specific constants to functions expect locations, such + as unwind (see mach-stack(3)). +
+ + Loccmp compares two locations, returning negative, zero, or positive + values if *a is less than, equal to, or greater than *b, respectively. + Register locations are ordered before memory addresses, which + are ordered before indirections. +
+ + Locfmt is a print(3)-verb that formats a Loc structure (not a + pointer to one). +
+ + Indirection locations are needed in some contexts (e.g., when + using findlsym (see mach-symbol(3))), but bothersome in most. + Locsimplify rewrites indirections as absolute memory addresses, + by evaluating the register using the given map and adding the + offset. +
+ + The functions lget1, lget2, lget4, lget8, lput1, lput2, lput4, + and lput8 read and write the given locations, using the get, put, + rget, and rput function families as necessary.
+ +
+

SOURCE
+ +
+ + /usr/local/plan9/src/libmach + +
+

SEE ALSO
+ +
+ + mach(3), mach-file(3)
+ +
+

DIAGNOSTICS
+ +
+ + These routines set errstr.
+ +
+

BUGS
+ +
+ + This man page needs to describe Regs and Regdesc + +
+ +

+ + +

		+
	+ + + +

+ + -- cgit v1.2.3