mach-map.3 (8390B)
1 .TH MACH-MAP 3 2 .SH NAME 3 allocmap, addseg, findseg, addrtoseg, 4 addrtosegafter, removeseg, freemap, 5 get1, get2, get4, get8, 6 put1, put2, put4, put8, 7 rget, rput, fpformat, 8 locnone, locaddr, locconst, locreg, locindir, 9 loccmp, loceval, locfmt, locsimplify, 10 lget1, lget2, lget4, lget8, 11 lput1, lput2, lput4, lput8 \- machine-independent 12 access to address spaces and register sets 13 .SH SYNOPSIS 14 .B #include <u.h> 15 .br 16 .B #include <libc.h> 17 .br 18 .B #include <mach.h> 19 .PP 20 .ft B 21 .ta \w'\fBxxxxxx'u +\w'xxxxxxx'u 22 .nf 23 typedef struct Map Map; 24 typedef struct Seg Seg; 25 .PP 26 .ft B 27 .nf 28 struct Seg 29 { 30 char *name; 31 char *file; 32 int fd; 33 ulong base; 34 ulong size; 35 ulong offset; 36 int (*rw)(Map*, Seg*, ulong, void*, uint, int); 37 }; 38 .PP 39 .ft B 40 .nf 41 struct Map 42 { 43 Seg *seg; 44 int nseg; 45 \fI...\fR 46 }; 47 .PP 48 .ft B 49 Map *allocmap(void) 50 .br 51 int addseg(Map *map, Seg seg) 52 .br 53 int findseg(Map *map, char *name, char *file) 54 .br 55 int addrtoseg(Map *map, ulong addr, Seg *seg) 56 .br 57 int addrtosegafter(Map *map, ulong addr, Seg *seg) 58 .br 59 void removeseg(Map *map, int i) 60 .br 61 void freemap(Map *map) 62 .PP 63 .ft B 64 int get1(Map *map, ulong addr, uchar *a, uint n) 65 .br 66 int get2(Map *map, ulong addr, u16int *u) 67 .br 68 int get4(Map *map, ulong addr, u32int *u) 69 .br 70 int get8(Map *map, ulong addr, u64int *u) 71 .PP 72 .ft B 73 int put1(Map *map, ulong addr, uchar *a, uint n) 74 .br 75 int put2(Map *map, ulong addr, u16int u) 76 .br 77 int put4(Map *map, ulong addr, u32int u) 78 .br 79 int put8(Map *map, ulong addr, u64int u) 80 .PP 81 .ft B 82 int rget(Regs *regs, char *reg, ulong *u) 83 .br 84 int fpformat(Map *map, char *reg, char *a, uint n, char code); 85 .PP 86 .ft B 87 int rput(Regs *regs, char *name, ulong u) 88 .PP 89 .ft B 90 Loc locnone(void) 91 .br 92 Loc locaddr(ulong addr) 93 .br 94 Loc locconst(ulong con) 95 .br 96 Loc locreg(char *reg) 97 .br 98 Loc locindir(char *reg, long offset) 99 .PP 100 .ft B 101 int loccmp(Loc *a, Loc *b) 102 .br 103 int loceval(Map *map, Loc loc, ulong *addr) 104 .br 105 int locfmt(Fmt *fmt) 106 .br 107 int locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc) 108 .PP 109 .ft B 110 int lget1(Map *map, Loc loc, uchar *a, uint n) 111 .br 112 int lget2(Map *map, Loc loc, u16int *u) 113 .br 114 int lget4(Map *map, Loc loc, u32int *u) 115 .br 116 int lget8(Map *map, Loc loc, u64int *u) 117 .PP 118 .ft B 119 int lput1(Map *map, Loc loc, uchar *a, uint n) 120 .br 121 int lput2(Map *map, Loc loc, u16int u) 122 .br 123 int lput4(Map *map, Loc loc, u32int u) 124 .br 125 int lput8(Map *map, Loc loc, u64int u) 126 .PP 127 .SH DESCRIPTION 128 These functions provide 129 a processor-independent interface for accessing 130 executable files, core files, and running processes 131 via 132 .IR maps , 133 data structures that provides access to an address space 134 and register set. 135 The functions described in 136 .MR mach-file (3) 137 are typically used to construct these maps. 138 Related library functions described in 139 .MR mach-symbol (3) 140 provide similar access to symbol tables. 141 .PP 142 Each 143 .I map 144 comprises an optional register set and one or more 145 .BR segments , 146 each associating a non-overlapping range of 147 memory addresses with a logical section of 148 an executable file or of a running process's address space. 149 Other library functions then use a map 150 and the architecture-specific data structures 151 to provide a generic interface to the 152 processor-dependent data. 153 .PP 154 Each segment has a name (e.g., 155 .B text 156 or 157 .BR data ) 158 and may be associated with a particular file. 159 A segment represents a range of accessible address space. 160 Segments may be backed an arbitary access function 161 (if the 162 .B rw 163 pointer is non-nil), 164 or by the contents of an open file 165 (using the 166 .B fd 167 file descriptor). 168 Each range has a starting address in the space 169 .RB ( base ) 170 and 171 an extent 172 .RB ( size ). 173 In segments mapped by files, 174 the range begins at byte 175 .B offset 176 in the file. 177 The 178 .B rw 179 function is most commonly used to provide 180 access to executing processes via 181 .MR ptrace (2) 182 and to zeroed segments. 183 .PP 184 .I Allocmap 185 creates an empty map; 186 .IR freemap 187 frees a map. 188 .PP 189 .I Addseg 190 adds the given segment to the map, resizing the map's 191 .I seg 192 array if necessary. 193 A negative return value indicates an allocation error. 194 .PP 195 .I Findseg 196 returns the index of the segment with the given name (and, if 197 .I file 198 is non-nil, the given file), 199 or \-1 if no such segment is found. 200 .PP 201 .I Addrtoseg 202 returns the index of the segment containing 203 for the given address, or \-1 if that address is not mapped. 204 Segments may have overlapping address ranges: 205 .I addseg 206 appends segments to the end of the 207 .I seg 208 array in the map, and 209 .I addrtoseg 210 searches the map backwards from the end, 211 so the most recently mapped segment wins. 212 .PP 213 .I Addrtosegafter 214 returns the index of the segment containing the lowest mapped 215 address greater than 216 .IR addr . 217 .PP 218 .I Removeseg 219 removes the segment at the given index. 220 .PP 221 .IR Get1 , 222 .IR get2 , 223 .IR get4 , 224 and 225 .I get8 226 retrieve the data stored at address 227 .I addr 228 in the address space associated 229 with 230 .IR map . 231 .I Get1 232 retrieves 233 .I n 234 bytes of data beginning at 235 .I addr 236 into 237 .IR buf . 238 .IR Get2 , 239 .I get4 240 and 241 .I get8 242 retrieve 16-bit, 32-bit and 64-bit values respectively, 243 into the location pointed to by 244 .IR u . 245 The value is byte-swapped if the source 246 byte order differs from that of the current architecture. 247 This implies that the value returned by 248 .IR get2 , 249 .IR get4 , 250 and 251 .I get8 252 may not be the same as the byte sequences 253 returned by 254 .I get1 255 when 256 .I n 257 is two, four or eight; the former may be byte-swapped, the 258 latter reflects the byte order of the target architecture. 259 These functions return the number 260 of bytes read or a \-1 when there is an error. 261 .PP 262 .IR Put1 , 263 .IR put2 , 264 .IR put4 , 265 and 266 .I put8 267 write to 268 the address space associated with 269 .IR map . 270 The address is translated using the 271 map parameters and multi-byte quantities are 272 byte-swapped, if necessary, before they are written. 273 .I Put1 274 transfers 275 .I n 276 bytes stored at 277 .IR buf ; 278 .IR put2 , 279 .IR put4 , 280 and 281 .I put8 282 write the 16-bit, 32-bit or 64-bit quantity contained in 283 .IR val , 284 respectively. The number of bytes transferred is returned. 285 A \-1 return value indicates an error. 286 .PP 287 When representing core files or running programs, 288 maps also provide access to the register set. 289 .IR Rget 290 and 291 .IR rput 292 read or write the register 293 named by 294 .IR reg . 295 If the register is smaller than a 296 .BR ulong , 297 the high bits are ignored. 298 .PP 299 .I Fpformat 300 converts the contents of a floating-point register to a string. 301 .I Buf 302 is the address of a buffer of 303 .I n 304 bytes to hold the resulting string. 305 .I Code 306 must be either 307 .L F 308 or 309 .LR f , 310 selecting double or single precision, respectively. 311 If 312 .I code 313 is 314 .LR F , 315 the contents of the specified register and the 316 following register are interpreted as a double-precision 317 floating-point number; 318 this is meaningful only for architectures that implement 319 double-precision floats by combining adjacent single-precision 320 registers. 321 .PP 322 A 323 .I location 324 represents a place in an executing image capable of 325 storing a value. 326 Note that locations are typically passed by value rather than by reference. 327 .PP 328 .I Locnone 329 returns an unreadable, unwritable location. 330 .I Locaddr 331 returns a location representing the memory address 332 .IR addr . 333 .I Locreg 334 returns a location representing the register 335 .IR reg . 336 .I Locindir 337 returns an location representing the memory address 338 at 339 .I offset 340 added to the value of 341 .IR reg . 342 .I Locconst 343 returns an imaginary unwritable location holding the constant 344 .IR con ; 345 such locations are useful for passing specific constants to 346 functions expect locations, such as 347 .I unwind 348 (see 349 .MR mach-stack (3) ). 350 .PP 351 .I Loccmp 352 compares two locations, returning negative, zero, or positive 353 values if 354 .B *a 355 is less than, equal to, or greater than 356 .BR *b , 357 respectively. 358 Register locations are ordered before memory addresses, 359 which are ordered before indirections. 360 .PP 361 .I Locfmt 362 is a 363 .MR print (3) -verb 364 that formats a 365 .B Loc 366 structure 367 .RI ( not 368 a pointer to one). 369 .PP 370 Indirection locations are needed in some contexts (e.g., when 371 using 372 .I findlsym 373 (see 374 .MR mach-symbol (3) )), 375 but bothersome in most. 376 .I Locsimplify 377 rewrites indirections as absolute memory addresses, by evaluating 378 the register using the given map and adding the offset. 379 .PP 380 The functions 381 .IR lget1 , 382 .IR lget2 , 383 .IR lget4 , 384 .IR lget8 , 385 .IR lput1 , 386 .IR lput2 , 387 .IR lput4 , 388 and 389 .I lput8 390 read and write the given locations, using the 391 .IR get , 392 .IR put , 393 .IR rget , 394 and 395 .I rput 396 function families as necessary. 397 .SH SOURCE 398 .B \*9/src/libmach 399 .SH "SEE ALSO" 400 .MR mach (3) , 401 .MR mach-file (3) 402 .SH DIAGNOSTICS 403 These routines set 404 .IR errstr . 405 .SH BUGS 406 This man page needs to describe 407 .B Regs 408 and 409 .B Regdesc 410 and 411 .I coreregs.