tmach-map.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tmach-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.