| .TH MACH-MAP 3 |
| .SH 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 |
| .SH SYNOPSIS |
| .B #include <u.h> |
| .br |
| .B #include <libc.h> |
| .br |
| .B #include <mach.h> |
| .PP |
| .ft B |
| .ta \w'\fBxxxxxx'u +\w'xxxxxxx'u |
| .nf |
| typedef struct Map Map; |
| typedef struct Seg Seg; |
| .PP |
| .ft B |
| .nf |
| struct Seg |
| { |
| char *name; |
| char *file; |
| int fd; |
| ulong base; |
| ulong size; |
| ulong offset; |
| int (*rw)(Map*, Seg*, ulong, void*, uint, int); |
| }; |
| .PP |
| .ft B |
| .nf |
| struct Map |
| { |
| Seg *seg; |
| int nseg; |
| \fI...\fR |
| }; |
| .PP |
| .ft B |
| 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) |
| .PP |
| .ft B |
| 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) |
| .PP |
| .ft B |
| 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) |
| .PP |
| .ft B |
| int rget(Regs *regs, char *reg, ulong *u) |
| .br |
| int fpformat(Map *map, char *reg, char *a, uint n, char code); |
| .PP |
| .ft B |
| int rput(Regs *regs, char *name, ulong u) |
| .PP |
| .ft B |
| 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) |
| .PP |
| .ft B |
| 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) |
| .PP |
| .ft B |
| 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) |
| .PP |
| .ft B |
| 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) |
| .PP |
| .SH DESCRIPTION |
| These functions provide |
| a processor-independent interface for accessing |
| executable files, core files, and running processes |
| via |
| .IR maps , |
| data structures that provides access to an address space |
| and register set. |
| The functions described in |
| .IR mach-file (3) |
| are typically used to construct these maps. |
| Related library functions described in |
| .IR mach-symbol (3) |
| provide similar access to symbol tables. |
| .PP |
| Each |
| .I map |
| comprises an optional register set and one or more |
| .BR 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. |
| .PP |
| Each segment has a name (e.g., |
| .B text |
| or |
| .BR 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 |
| .B rw |
| pointer is non-nil), |
| or by the contents of an open file |
| (using the |
| .B fd |
| file descriptor). |
| Each range has a starting address in the space |
| .RB ( base ) |
| and |
| an extent |
| .RB ( size ). |
| In segments mapped by files, |
| the range begins at byte |
| .B offset |
| in the file. |
| The |
| .B rw |
| function is most commonly used to provide |
| access to executing processes via |
| .IR ptrace (2) |
| and to zeroed segments. |
| .PP |
| .I Allocmap |
| creates an empty map; |
| .IR freemap |
| frees a map. |
| .PP |
| .I Addseg |
| adds the given segment to the map, resizing the map's |
| .I seg |
| array if necessary. |
| A negative return value indicates an allocation error. |
| .PP |
| .I Findseg |
| returns the index of the segment with the given name (and, if |
| .I file |
| is non-nil, the given file), |
| or \-1 if no such segment is found. |
| .PP |
| .I 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: |
| .I addseg |
| appends segments to the end of the |
| .I seg |
| array in the map, and |
| .I addrtoseg |
| searches the map backwards from the end, |
| so the most recently mapped segment wins. |
| .PP |
| .I Addrtosegafter |
| returns the index of the segment containing the lowest mapped |
| address greater than |
| .IR addr . |
| .PP |
| .I Removeseg |
| removes the segment at the given index. |
| .PP |
| .IR Get1 , |
| .IR get2 , |
| .IR get4 , |
| and |
| .I get8 |
| retrieve the data stored at address |
| .I addr |
| in the address space associated |
| with |
| .IR map . |
| .I Get1 |
| retrieves |
| .I n |
| bytes of data beginning at |
| .I addr |
| into |
| .IR buf . |
| .IR Get2 , |
| .I get4 |
| and |
| .I get8 |
| retrieve 16-bit, 32-bit and 64-bit values respectively, |
| into the location pointed to by |
| .IR 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 |
| .IR get2 , |
| .IR get4 , |
| and |
| .I get8 |
| may not be the same as the byte sequences |
| returned by |
| .I get1 |
| when |
| .I 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. |
| .PP |
| .IR Put1 , |
| .IR put2 , |
| .IR put4 , |
| and |
| .I put8 |
| write to |
| the address space 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 ; |
| .IR put2 , |
| .IR put4 , |
| and |
| .I put8 |
| write the 16-bit, 32-bit or 64-bit quantity contained in |
| .IR val , |
| respectively. The number of bytes transferred is returned. |
| A \-1 return value indicates an error. |
| .PP |
| When representing core files or running programs, |
| maps also provide access to the register set. |
| .IR Rget |
| and |
| .IR rput |
| read or write the register |
| named by |
| .IR reg . |
| If the register is smaller than a |
| .BR ulong , |
| the high bits are ignored. |
| .PP |
| .I Fpformat |
| converts the contents of a floating-point register to a string. |
| .I Buf |
| is the address of a buffer of |
| .I n |
| bytes to hold the resulting string. |
| .I Code |
| must be either |
| .L F |
| or |
| .LR f , |
| selecting double or single precision, respectively. |
| If |
| .I code |
| is |
| .LR 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. |
| .PP |
| A |
| .I 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. |
| .PP |
| .I Locnone |
| returns an unreadable, unwritable location. |
| .I Locaddr |
| returns a location representing the memory address |
| .IR addr . |
| .I Locreg |
| returns a location representing the register |
| .IR reg . |
| .I Locindir |
| returns an location representing the memory address |
| at |
| .I offset |
| added to the value of |
| .IR reg . |
| .I Locconst |
| returns an imaginary unwritable location holding the constant |
| .IR con ; |
| such locations are useful for passing specific constants to |
| functions expect locations, such as |
| .I unwind |
| (see |
| .IR mach-stack (3)). |
| .PP |
| .I Loccmp |
| compares two locations, returning negative, zero, or positive |
| values if |
| .B *a |
| is less than, equal to, or greater than |
| .BR *b , |
| respectively. |
| Register locations are ordered before memory addresses, |
| which are ordered before indirections. |
| .PP |
| .I Locfmt |
| is a |
| .IR print (3)-verb |
| that formats a |
| .B Loc |
| structure |
| .RI ( not |
| a pointer to one). |
| .PP |
| Indirection locations are needed in some contexts (e.g., when |
| using |
| .I findlsym |
| (see |
| .IR mach-symbol (3))), |
| but bothersome in most. |
| .I Locsimplify |
| rewrites indirections as absolute memory addresses, by evaluating |
| the register using the given map and adding the offset. |
| .PP |
| The functions |
| .IR lget1 , |
| .IR lget2 , |
| .IR lget4 , |
| .IR lget8 , |
| .IR lput1 , |
| .IR lput2 , |
| .IR lput4 , |
| and |
| .I lput8 |
| read and write the given locations, using the |
| .IR get , |
| .IR put , |
| .IR rget , |
| and |
| .I rput |
| function families as necessary. |
| .SH SOURCE |
| .B \*9/src/libmach |
| .SH "SEE ALSO" |
| .IR mach (3), |
| .IR mach-file (3) |
| .SH DIAGNOSTICS |
| These routines set |
| .IR errstr . |
| .SH BUGS |
| This man page needs to describe |
| .B Regs |
| and |
| .B Regdesc |
| and |
| .I coreregs. |