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