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 bf8a59fa 2004-04-11 devnull rget1, rget2, rget4, rget8,
8 bf8a59fa 2004-04-11 devnull rput1, rput2, rput4, rput8,
9 bf8a59fa 2004-04-11 devnull locaddr, locconst, locreg, locindir,
10 bf8a59fa 2004-04-11 devnull loccmp, loceval, locfmt, locredir,
11 bf8a59fa 2004-04-11 devnull lget1, lget2, lget4, lget8,
12 bf8a59fa 2004-04-11 devnull lput1, lput2, lput4, lput8 \- machine-independent
13 bf8a59fa 2004-04-11 devnull access to address spaces and register sets
14 bf8a59fa 2004-04-11 devnull .SH SYNOPSIS
15 bf8a59fa 2004-04-11 devnull .B #include <u.h>
17 bf8a59fa 2004-04-11 devnull .B #include <libc.h>
19 bf8a59fa 2004-04-11 devnull .B #include <mach.h>
22 bf8a59fa 2004-04-11 devnull .ta \w'\fBxxxxxx'u +\w'xxxxxxx'u
24 bf8a59fa 2004-04-11 devnull typedef struct Map Map;
25 bf8a59fa 2004-04-11 devnull typedef struct Seg Seg;
29 bf8a59fa 2004-04-11 devnull struct Seg
31 bf8a59fa 2004-04-11 devnull char *name;
32 bf8a59fa 2004-04-11 devnull char *file;
34 bf8a59fa 2004-04-11 devnull ulong base;
35 bf8a59fa 2004-04-11 devnull ulong size;
36 bf8a59fa 2004-04-11 devnull ulong offset;
37 bf8a59fa 2004-04-11 devnull int (*rw)(Map*, Seg*, ulong, void*, uint, int);
42 bf8a59fa 2004-04-11 devnull struct Map
44 bf8a59fa 2004-04-11 devnull Seg *seg;
45 bf8a59fa 2004-04-11 devnull int nseg;
46 bf8a59fa 2004-04-11 devnull \fI...\fR
50 bf8a59fa 2004-04-11 devnull Map *allocmap(void)
52 bf8a59fa 2004-04-11 devnull int addseg(Map *map, Seg seg)
54 bf8a59fa 2004-04-11 devnull int findseg(Map *map, char *name, char *file)
56 bf8a59fa 2004-04-11 devnull int addrtoseg(Map *map, ulong addr, Seg *seg)
58 bf8a59fa 2004-04-11 devnull int addrtosegafter(Map *map, ulong addr, Seg *seg)
60 bf8a59fa 2004-04-11 devnull void removeseg(Map *map, int i)
62 bf8a59fa 2004-04-11 devnull void freemap(Map *map)
65 bf8a59fa 2004-04-11 devnull int get1(Map *map, ulong addr, uchar *a, uint n)
67 bf8a59fa 2004-04-11 devnull int get2(Map *map, ulong addr, u16int *u)
69 bf8a59fa 2004-04-11 devnull int get4(Map *map, ulong addr, u32int *u)
71 bf8a59fa 2004-04-11 devnull int get8(Map *map, ulong addr, u64int *u)
74 bf8a59fa 2004-04-11 devnull int put1(Map *map, ulong addr, uchar *a, uint n)
76 bf8a59fa 2004-04-11 devnull int put2(Map *map, ulong addr, u16int u)
78 bf8a59fa 2004-04-11 devnull int put4(Map *map, ulong addr, u32int u)
80 bf8a59fa 2004-04-11 devnull int put8(Map *map, ulong addr, u64int u)
83 bf8a59fa 2004-04-11 devnull int rget1(Map *map, char *reg, u8int *u)
85 bf8a59fa 2004-04-11 devnull int rget2(Map *map, char *reg, u16int *u)
87 bf8a59fa 2004-04-11 devnull int rget4(Map *map, char *reg, u32int *u)
89 bf8a59fa 2004-04-11 devnull int rget8(Map *map, char *reg, u64int *u)
91 bf8a59fa 2004-04-11 devnull int fpformat(Map *map, char *reg, char *a, uint n, char code);
94 bf8a59fa 2004-04-11 devnull int rput1(Map *map, char *reg, u8int u)
96 bf8a59fa 2004-04-11 devnull int rput2(Map *map, char *reg, u16int u)
98 bf8a59fa 2004-04-11 devnull int rput4(Map *map, char *reg, u32int u)
100 bf8a59fa 2004-04-11 devnull int rput8(Map *map, char *reg, u64int u)
103 bf8a59fa 2004-04-11 devnull Loc locaddr(ulong addr)
105 bf8a59fa 2004-04-11 devnull Loc locconst(ulong con)
107 bf8a59fa 2004-04-11 devnull Loc locreg(char *reg)
109 bf8a59fa 2004-04-11 devnull Loc locindir(char *reg, long offset)
112 bf8a59fa 2004-04-11 devnull int loccmp(Loc *a, Loc *b)
114 bf8a59fa 2004-04-11 devnull int loceval(Map *map, Loc loc, ulong *addr)
116 bf8a59fa 2004-04-11 devnull int locfmt(Fmt *fmt)
118 bf8a59fa 2004-04-11 devnull int locredir(Map *map, Loc *regs, Loc loc, Loc *newloc)
121 bf8a59fa 2004-04-11 devnull int lget1(Map *map, Loc loc, uchar *a, uint n)
123 bf8a59fa 2004-04-11 devnull int lget2(Map *map, Loc loc, u16int *u)
125 bf8a59fa 2004-04-11 devnull int lget4(Map *map, Loc loc, u32int *u)
127 bf8a59fa 2004-04-11 devnull int lget8(Map *map, Loc loc, u64int *u)
130 bf8a59fa 2004-04-11 devnull int lput1(Map *map, Loc loc, uchar *a, uint n)
132 bf8a59fa 2004-04-11 devnull int lput2(Map *map, Loc loc, u16int u)
134 bf8a59fa 2004-04-11 devnull int lput4(Map *map, Loc loc, u32int u)
136 bf8a59fa 2004-04-11 devnull int lput8(Map *map, Loc loc, u64int u)
138 bf8a59fa 2004-04-11 devnull .SH DESCRIPTION
139 bf8a59fa 2004-04-11 devnull These functions provide
140 bf8a59fa 2004-04-11 devnull a processor-independent interface for accessing
141 bf8a59fa 2004-04-11 devnull executable files, core files, and running processes
143 bf8a59fa 2004-04-11 devnull .IR maps ,
144 bf8a59fa 2004-04-11 devnull data structures that provides access to an address space
145 bf8a59fa 2004-04-11 devnull and register set.
146 bf8a59fa 2004-04-11 devnull The functions described in
147 bf8a59fa 2004-04-11 devnull .IR mach-file (3)
148 bf8a59fa 2004-04-11 devnull are typically used to construct these maps.
149 bf8a59fa 2004-04-11 devnull Related library functions described in
150 bf8a59fa 2004-04-11 devnull .IR mach-symbol (3)
151 bf8a59fa 2004-04-11 devnull provide similar access to symbol tables.
155 bf8a59fa 2004-04-11 devnull comprises an optional register set and one or more
156 bf8a59fa 2004-04-11 devnull .BR segments ,
157 bf8a59fa 2004-04-11 devnull each associating a non-overlapping range of
158 bf8a59fa 2004-04-11 devnull memory addresses with a logical section of
159 bf8a59fa 2004-04-11 devnull an executable file or of a running process's address space.
160 bf8a59fa 2004-04-11 devnull Other library functions then use a map
161 bf8a59fa 2004-04-11 devnull and the architecture-specific data structures
162 bf8a59fa 2004-04-11 devnull to provide a generic interface to the
163 bf8a59fa 2004-04-11 devnull processor-dependent data.
165 bf8a59fa 2004-04-11 devnull Each segment has a name (e.g.,
168 bf8a59fa 2004-04-11 devnull .BR data )
169 bf8a59fa 2004-04-11 devnull and may be associated with a particular file.
170 bf8a59fa 2004-04-11 devnull A segment represents a range of accessible address space.
171 bf8a59fa 2004-04-11 devnull Segments may be backed an arbitary access function
174 bf8a59fa 2004-04-11 devnull pointer is non-nil),
175 bf8a59fa 2004-04-11 devnull or by the contents of an open file
176 bf8a59fa 2004-04-11 devnull (using the
178 bf8a59fa 2004-04-11 devnull file descriptor).
179 bf8a59fa 2004-04-11 devnull Each range has a starting address in the space
180 bf8a59fa 2004-04-11 devnull .RB ( base )
182 bf8a59fa 2004-04-11 devnull an extent
183 bf8a59fa 2004-04-11 devnull .RB ( size ).
184 bf8a59fa 2004-04-11 devnull In segments mapped by files,
185 bf8a59fa 2004-04-11 devnull the range begins at byte
186 bf8a59fa 2004-04-11 devnull .B offset
187 bf8a59fa 2004-04-11 devnull in the file.
190 bf8a59fa 2004-04-11 devnull function is most commonly used to provide
191 bf8a59fa 2004-04-11 devnull access to executing processes via
192 bf8a59fa 2004-04-11 devnull .IR ptrace (2)
193 bf8a59fa 2004-04-11 devnull and to zeroed segments.
195 bf8a59fa 2004-04-11 devnull .I Allocmap
196 bf8a59fa 2004-04-11 devnull creates an empty map;
197 bf8a59fa 2004-04-11 devnull .IR freemap
198 bf8a59fa 2004-04-11 devnull frees a map.
200 bf8a59fa 2004-04-11 devnull .I Addseg
201 bf8a59fa 2004-04-11 devnull adds the given segment to the map, resizing the map's
203 bf8a59fa 2004-04-11 devnull array if necessary.
204 bf8a59fa 2004-04-11 devnull A negative return value indicates an allocation error.
206 bf8a59fa 2004-04-11 devnull .I Findseg
207 bf8a59fa 2004-04-11 devnull returns the index of the segment with the given name (and, if
209 bf8a59fa 2004-04-11 devnull is non-nil, the given file),
210 bf8a59fa 2004-04-11 devnull or \-1 if no such segment is found.
212 bf8a59fa 2004-04-11 devnull .I Addrtoseg
213 bf8a59fa 2004-04-11 devnull returns the index of the segment containing
214 bf8a59fa 2004-04-11 devnull for the given address, or \-1 if that address is not mapped.
215 bf8a59fa 2004-04-11 devnull Segments may have overlapping address ranges:
216 bf8a59fa 2004-04-11 devnull .I addseg
217 bf8a59fa 2004-04-11 devnull appends segments to the end of the
219 bf8a59fa 2004-04-11 devnull array in the map, and
220 bf8a59fa 2004-04-11 devnull .I addrtoseg
221 bf8a59fa 2004-04-11 devnull searches the map backwards from the end,
222 bf8a59fa 2004-04-11 devnull so the most recently mapped segment wins.
224 bf8a59fa 2004-04-11 devnull .I Addrtosegafter
225 bf8a59fa 2004-04-11 devnull returns the index of the segment containing the lowest mapped
226 bf8a59fa 2004-04-11 devnull address greater than
227 bf8a59fa 2004-04-11 devnull .IR addr .
229 bf8a59fa 2004-04-11 devnull .I Removeseg
230 bf8a59fa 2004-04-11 devnull removes the segment at the given index.
232 bf8a59fa 2004-04-11 devnull .IR Get1 ,
233 bf8a59fa 2004-04-11 devnull .IR get2 ,
234 bf8a59fa 2004-04-11 devnull .IR get4 ,
237 bf8a59fa 2004-04-11 devnull retrieve the data stored at address
239 bf8a59fa 2004-04-11 devnull in the address space associated
241 bf8a59fa 2004-04-11 devnull .IR map .
243 bf8a59fa 2004-04-11 devnull retrieves
245 bf8a59fa 2004-04-11 devnull bytes of data beginning at
248 bf8a59fa 2004-04-11 devnull .IR buf .
249 bf8a59fa 2004-04-11 devnull .IR Get2 ,
253 bf8a59fa 2004-04-11 devnull retrieve 16-bit, 32-bit and 64-bit values respectively,
254 bf8a59fa 2004-04-11 devnull into the location pointed to by
256 bf8a59fa 2004-04-11 devnull The value is byte-swapped if the source
257 bf8a59fa 2004-04-11 devnull byte order differs from that of the current architecture.
258 bf8a59fa 2004-04-11 devnull This implies that the value returned by
259 bf8a59fa 2004-04-11 devnull .IR get2 ,
260 bf8a59fa 2004-04-11 devnull .IR get4 ,
263 bf8a59fa 2004-04-11 devnull may not be the same as the byte sequences
264 bf8a59fa 2004-04-11 devnull returned by
268 bf8a59fa 2004-04-11 devnull is two, four or eight; the former may be byte-swapped, the
269 bf8a59fa 2004-04-11 devnull latter reflects the byte order of the target architecture.
270 bf8a59fa 2004-04-11 devnull These functions return the number
271 bf8a59fa 2004-04-11 devnull of bytes read or a \-1 when there is an error.
273 bf8a59fa 2004-04-11 devnull .IR Put1 ,
274 bf8a59fa 2004-04-11 devnull .IR put2 ,
275 bf8a59fa 2004-04-11 devnull .IR put4 ,
278 bf8a59fa 2004-04-11 devnull write to
279 bf8a59fa 2004-04-11 devnull the address space associated with
280 bf8a59fa 2004-04-11 devnull .IR map .
281 bf8a59fa 2004-04-11 devnull The address is translated using the
282 bf8a59fa 2004-04-11 devnull map parameters and multi-byte quantities are
283 bf8a59fa 2004-04-11 devnull byte-swapped, if necessary, before they are written.
285 bf8a59fa 2004-04-11 devnull transfers
287 bf8a59fa 2004-04-11 devnull bytes stored at
288 bf8a59fa 2004-04-11 devnull .IR buf ;
289 bf8a59fa 2004-04-11 devnull .IR put2 ,
290 bf8a59fa 2004-04-11 devnull .IR put4 ,
293 bf8a59fa 2004-04-11 devnull write the 16-bit, 32-bit or 64-bit quantity contained in
294 bf8a59fa 2004-04-11 devnull .IR val ,
295 bf8a59fa 2004-04-11 devnull respectively. The number of bytes transferred is returned.
296 bf8a59fa 2004-04-11 devnull A \-1 return value indicates an error.
298 bf8a59fa 2004-04-11 devnull When representing core files or running programs,
299 bf8a59fa 2004-04-11 devnull maps also provide access to the register set.
300 bf8a59fa 2004-04-11 devnull .IR Rget1 ,
301 bf8a59fa 2004-04-11 devnull .IR rget2 ,
302 bf8a59fa 2004-04-11 devnull .IR rget4 ,
303 bf8a59fa 2004-04-11 devnull .IR rget8 ,
304 bf8a59fa 2004-04-11 devnull .IR rput1 ,
305 bf8a59fa 2004-04-11 devnull .IR rput2 ,
306 bf8a59fa 2004-04-11 devnull .IR rput4 ,
308 bf8a59fa 2004-04-11 devnull .IR rput8
309 bf8a59fa 2004-04-11 devnull read or write the 1-, 2-, 4-, or 8-byte register
310 bf8a59fa 2004-04-11 devnull named by
311 bf8a59fa 2004-04-11 devnull .IR reg .
312 bf8a59fa 2004-04-11 devnull If the register is not the requested size, the
313 bf8a59fa 2004-04-11 devnull behavior is undefined.
315 bf8a59fa 2004-04-11 devnull .I Fpformat
316 bf8a59fa 2004-04-11 devnull converts the contents of a floating-point register to a string.
318 bf8a59fa 2004-04-11 devnull is the address of a buffer of
320 bf8a59fa 2004-04-11 devnull bytes to hold the resulting string.
322 bf8a59fa 2004-04-11 devnull must be either
326 bf8a59fa 2004-04-11 devnull selecting double or single precision, respectively.
331 bf8a59fa 2004-04-11 devnull the contents of the specified register and the
332 bf8a59fa 2004-04-11 devnull following register are interpreted as a double-precision
333 bf8a59fa 2004-04-11 devnull floating-point number;
334 bf8a59fa 2004-04-11 devnull this is meaningful only for architectures that implement
335 bf8a59fa 2004-04-11 devnull double-precision floats by combining adjacent single-precision
336 bf8a59fa 2004-04-11 devnull registers.
339 bf8a59fa 2004-04-11 devnull .I location
340 bf8a59fa 2004-04-11 devnull represents a place in an executing image capable of
341 bf8a59fa 2004-04-11 devnull storing a value.
342 bf8a59fa 2004-04-11 devnull Note that locations are typically passed by value rather than by reference.
344 bf8a59fa 2004-04-11 devnull .I Locnone
345 bf8a59fa 2004-04-11 devnull returns an unreadable, unwritable location.
346 bf8a59fa 2004-04-11 devnull .I Locaddr
347 bf8a59fa 2004-04-11 devnull returns a location representing the memory address
348 bf8a59fa 2004-04-11 devnull .IR addr .
349 bf8a59fa 2004-04-11 devnull .I Locreg
350 bf8a59fa 2004-04-11 devnull returns a location representing the register
351 bf8a59fa 2004-04-11 devnull .IR reg .
352 bf8a59fa 2004-04-11 devnull .I Locindir
353 bf8a59fa 2004-04-11 devnull returns an location representing the memory address
355 bf8a59fa 2004-04-11 devnull .I offset
356 bf8a59fa 2004-04-11 devnull added to the value of
357 bf8a59fa 2004-04-11 devnull .IR reg .
358 bf8a59fa 2004-04-11 devnull .I Locconst
359 bf8a59fa 2004-04-11 devnull returns an imaginary unwritable location holding the constant
360 bf8a59fa 2004-04-11 devnull .IR con ;
361 bf8a59fa 2004-04-11 devnull such locations are useful for passing specific constants to
362 bf8a59fa 2004-04-11 devnull functions expect locations, such as
363 bf8a59fa 2004-04-11 devnull .I unwind
365 bf8a59fa 2004-04-11 devnull .IR mach-stack (3)).
367 bf8a59fa 2004-04-11 devnull .I Loccmp
368 bf8a59fa 2004-04-11 devnull compares two locations, returning negative, zero, or positive
369 bf8a59fa 2004-04-11 devnull values if
371 bf8a59fa 2004-04-11 devnull is less than, equal to, or greater than
372 bf8a59fa 2004-04-11 devnull .BR *b ,
373 bf8a59fa 2004-04-11 devnull respectively.
374 bf8a59fa 2004-04-11 devnull Register locations are ordered before memory addresses,
375 bf8a59fa 2004-04-11 devnull which are ordered before indirections.
377 bf8a59fa 2004-04-11 devnull .I Locfmt
379 bf8a59fa 2004-04-11 devnull .IR print (3)-verb
380 bf8a59fa 2004-04-11 devnull that formats a
382 bf8a59fa 2004-04-11 devnull structure
383 bf8a59fa 2004-04-11 devnull .RI ( not
384 bf8a59fa 2004-04-11 devnull a pointer to one).
386 bf8a59fa 2004-04-11 devnull Indirection locations are needed in some contexts (e.g., when
388 bf8a59fa 2004-04-11 devnull .I findlsym
390 bf8a59fa 2004-04-11 devnull .IR mach-symbol (3))),
391 bf8a59fa 2004-04-11 devnull but bothersome in most.
392 bf8a59fa 2004-04-11 devnull .I Locsimplify
393 bf8a59fa 2004-04-11 devnull rewrites indirections as absolute memory addresses, by evaluating
394 bf8a59fa 2004-04-11 devnull the register using the given map and adding the offset.
396 bf8a59fa 2004-04-11 devnull The functions
397 bf8a59fa 2004-04-11 devnull .IR lget1 ,
398 bf8a59fa 2004-04-11 devnull .IR lget2 ,
399 bf8a59fa 2004-04-11 devnull .IR lget4 ,
400 bf8a59fa 2004-04-11 devnull .IR lget8 ,
401 bf8a59fa 2004-04-11 devnull .IR lput1 ,
402 bf8a59fa 2004-04-11 devnull .IR lput2 ,
403 bf8a59fa 2004-04-11 devnull .IR lput4 ,
405 bf8a59fa 2004-04-11 devnull .I lput8
406 bf8a59fa 2004-04-11 devnull read and write the given locations, using the
407 bf8a59fa 2004-04-11 devnull .IR get ,
408 bf8a59fa 2004-04-11 devnull .IR put ,
409 bf8a59fa 2004-04-11 devnull .IR rget ,
412 bf8a59fa 2004-04-11 devnull function families as necessary.
413 bf8a59fa 2004-04-11 devnull .SH SOURCE
414 bf8a59fa 2004-04-11 devnull .B /sys/src/libmach
415 bf8a59fa 2004-04-11 devnull .SH "SEE ALSO"
416 905ca4e6 2004-04-19 devnull .IR mach (3),
417 905ca4e6 2004-04-19 devnull .IR mach-file (3)
418 bf8a59fa 2004-04-11 devnull .SH DIAGNOSTICS
419 bf8a59fa 2004-04-11 devnull These routines set
420 bf8a59fa 2004-04-11 devnull .IR errstr .
