sys/man/2/mach

   1 .TH MACH 2
   2 .SH NAME
   3 crackhdr, machbytype, machbyname, newmap, setmap, findseg, unusemap,
   4 loadmap, attachproc, get1, get2, get4, get8, geta, put1, put2, put4, put8, puta
   5 beswab, beswal, beswav, leswab, leswal, leswav \- machine-independent access to executable files
   6 .SH SYNOPSIS
   7 .B #include <u.h>
   8 .br
   9 .B #include <libc.h>
  10 .br
  11 .B #include <bio.h>
  12 .br
  13 .B #include <mach.h>
  14 .PP
  15 .ta \w'\fLmachines 'u
  16 .B
  17 int crackhdr(int fd, Fhdr *fp)
  18 .PP
  19 .B
  20 void machbytype(int type)
  21 .PP
  22 .B
  23 int machbyname(char *name)
  24 .PP
  25 .B
  26 Map *newmap(Map *map, int n)
  27 .PP
  28 .B
  29 int setmap(Map *map, int fd, uvlong base, uvlong end,
  30 .PP
  31 .B
  32             vlong foffset, char *name)
  33 .PP
  34 .B
  35 int findseg(Map *map, char *name)
  36 .PP
  37 .B
  38 void unusemap(Map *map, int seg)
  39 .PP
  40 .B
  41 Map *loadmap(Map *map, int fd, Fhdr *fp)
  42 .PP
  43 .B
  44 Map *attachproc(int pid, int kflag, int corefd, Fhdr *fp)
  45 .PP
  46 .B
  47 int get1(Map *map, uvlong addr, uchar *buf, int n)
  48 .PP
  49 .B
  50 int get2(Map *map, uvlong addr, ushort *val)
  51 .PP
  52 .B
  53 int get4(Map *map, uvlong addr, ulong *val)
  54 .PP
  55 .B
  56 int get8(Map *map, uvlong addr, uvlong *val)
  57 .PP
  58 .B
  59 int geta(Map *map, uvlong addr, uvlong *val)
  60 .PP
  61 .B
  62 int put1(Map *map, uvlong addr, uchar *buf, int n)
  63 .PP
  64 .B
  65 int put2(Map *map, uvlong addr, ushort val)
  66 .PP
  67 .B
  68 int put4(Map *map, uvlong addr, ulong val)
  69 .PP
  70 .B
  71 int put8(Map *map, uvlong addr, uvlong val)
  72 .PP
  73 .B
  74 int puta(Map *map, uvlong addr, uvlong val)
  75 .PP
  76 .B
  77 ushort beswab(ushort val)
  78 .PP
  79 .B
  80 long beswal(ulong val)
  81 .PP
  82 .B
  83 long beswav(uvlong val)
  84 .PP
  85 .B
  86 ushort leswab(ushort val)
  87 .PP
  88 .B
  89 long leswal(ulong val)
  90 .PP
  91 .B
  92 long leswav(uvlong val)
  93 .PP
  94 .B
  95 extern Mach mach;
  96 .PP
  97 .B
  98 extern Machdata machdata;
  99 .SH DESCRIPTION
 100 These functions provide
 101 a processor-independent interface for accessing
 102 the executable files or executing images of all
 103 architectures.
 104 Related library functions described in
 105 .IR symbol (2)
 106 and
 107 .IR object (2)
 108 provide similar access to symbol tables and object files.
 109 .PP
 110 An
 111 .I executable
 112 is a file containing an executable program or the
 113 .B text
 114 file of the
 115 .B /proc
 116 file system associated with an executing process as
 117 described in
 118 .IR proc (3).
 119 After opening an executable, an application
 120 invokes a library function which parses the
 121 file header,
 122 determines the target architecture and
 123 initializes data structures with parameters
 124 and pointers to functions appropriate for
 125 that architecture.  Next, the application
 126 invokes functions to construct one or more
 127 .IR maps ,
 128 data structures that translate references
 129 in the address space of the executable
 130 to offsets in the file.  Each
 131 .I map
 132 comprises one or more
 133 .BR segments ,
 134 each associating a non-overlapping range of
 135 memory addresses with a logical section of
 136 the executable.
 137 Other library functions then use a map
 138 and the architecture-specific data structures
 139 to provide a generic interface to the
 140 processor-dependent data.
 141 .PP
 142 .I Crackhdr
 143 interprets the header of the executable
 144 associated with
 145 the open file descriptor
 146 .IR fd .
 147 It loads the data structure
 148 .I fp
 149 with a machine-independent description
 150 of the header information and
 151 points global variable
 152 .I mach
 153 to the
 154 .B Mach
 155 data structure containing processor-dependent parameters
 156 of the target architecture.
 157 .PP
 158 .I Machbytype
 159 selects architecture-specific data structures and parameter
 160 values based on
 161 the code stored in the
 162 field named
 163 .I type
 164 in the
 165 .B Fhdr
 166 data structure.
 167 .I Machbyname
 168 performs the same selection based
 169 on the name of a processor class; see
 170 .IR 2c (1)
 171 for a list of valid names.
 172 Both functions point global variables
 173 .I mach
 174 and
 175 .I machdata
 176 to the
 177 .I Mach
 178 and
 179 .I Machdata
 180 data structures appropriate for the
 181 target architecture and load global variable
 182 .I asstype
 183 with the proper disassembler type code.
 184 .PP
 185 .I Newmap
 186 creates an empty map with
 187 .I n
 188 segments.
 189 If
 190 .I map
 191 is zero, the new map is dynamically
 192 allocated, otherwise it is assumed to
 193 point to an existing dynamically allocated map whose
 194 size is adjusted, as necessary.
 195 A zero return value indicates an allocation error.
 196 .PP
 197 .I Setmap
 198 loads the first unused segment in
 199 .I map
 200 with the
 201 segment mapping parameters.
 202 .I Fd
 203 is an open file descriptor associated with
 204 an executable.
 205 .I Base
 206 and
 207 .I end
 208 contain the lowest and highest virtual addresses
 209 mapped by the segment.
 210 .I Foffset
 211 is the offset to the start of the segment in the file.
 212 .I Name
 213 is a name to be attached to the segment.
 214 .PP
 215 .I Findseg
 216 returns the index of the
 217 segment named
 218 .I name
 219 in
 220 .IR map .
 221 A return of -1 indicates that no
 222 segment matches
 223 .IR name .
 224 .PP
 225 .I Unusemap
 226 marks segment number
 227 .I seg
 228 in map
 229 .I map
 230 unused.  Other
 231 segments in the map remain unaffected.
 232 .PP
 233 .I Loadmap
 234 initializes a default map containing
 235 segments named `text' and `data' that
 236 map the instruction and data segments
 237 of the executable described in the
 238 .B Fhdr
 239 structure pointed to by
 240 .IR fp .
 241 Usually that structure was loaded by
 242 .IR crackhdr
 243 and can be passed to this function without
 244 modification.
 245 If
 246 .I map
 247 is non-zero, that map, which must have been
 248 dynamically allocated, is resized to contain two segments;
 249 otherwise a new map is allocated.
 250 This function returns zero if allocation fails.
 251 .I Loadmap
 252 is usually used to build a map for accessing
 253 a static executable, for example, an executable
 254 program file.
 255 .PP
 256 .I Attachproc
 257 constructs a map for accessing a
 258 running process.  It
 259 returns the address of a
 260 .I Map
 261 containing segments mapping the
 262 address space of the running process
 263 whose process ID is
 264 .BR pid .
 265 If
 266 .B kflag
 267 is non-zero, the process is assumed to be
 268 a kernel process.
 269 .B Corefd
 270 is an file descriptor opened to
 271 .BR /proc/\fIpid\fP/mem .
 272 .B Fp
 273 points to the
 274 .I Fhdr
 275 structure describing the header
 276 of the executable.  For most architectures
 277 the resulting
 278 .I Map
 279 contains four segments named `text', `data',
 280 `regs' and `fpregs'.  The latter two provide access to
 281 the general and floating point registers, respectively.
 282 If the executable is a kernel process (indicated by a
 283 non-zero
 284 .B kflag
 285 argument), the data segment extends to the maximum
 286 supported address, currently 0xffffffff, and the
 287 register sets are read-only.  In user-level programs,
 288 the data segment extends to the
 289 top of the stack or 0x7fffffff if the stack top
 290 cannot be found, and the register sets are readable
 291 and writable.
 292 .I Attachproc
 293 returns zero if it is unable to build the map
 294 for the specified process.
 295 .PP
 296 .IR Get1 ,
 297 .IR get2 ,
 298 .IR get4 ,
 299 and
 300 .I get8
 301 retrieve the data stored at address
 302 .I addr
 303 in the executable associated
 304 with
 305 .IR map .
 306 .I Get1
 307 retrieves
 308 .I n
 309 bytes of data beginning at
 310 .I addr
 311 into
 312 .IR buf .
 313 .IR Get2 ,
 314 .I get4
 315 and
 316 .I get8
 317 retrieve 16-bit, 32-bit and 64-bit values respectively,
 318 into the location pointed to by
 319 .IR val .
 320 The value is byte-swapped if the source
 321 byte order differs from that of the current architecture.
 322 This implies that the value returned by
 323 .IR get2 ,
 324 .IR get4 ,
 325 and
 326 .I get8
 327 may not be the same as the byte sequences
 328 returned by
 329 .I get1
 330 when
 331 .I n
 332 is two, four or eight; the former may be byte-swapped, the
 333 latter reflects the byte order of the target architecture.
 334 If the file descriptor associated with the applicable segment in
 335 .I map
 336 is negative, the address itself is placed in the
 337 return location.  These functions return the number
 338 of bytes read or a \-1 when there is an error.
 339 .PP
 340 .IR Put1 ,
 341 .IR put2 ,
 342 .IR put4 ,
 343 and
 344 .I put8
 345 write to
 346 the executable associated with
 347 .IR map .
 348 The address is translated using the
 349 map parameters and multi-byte quantities are
 350 byte-swapped, if necessary, before they are written.
 351 .I Put1
 352 transfers
 353 .I n
 354 bytes stored at
 355 .IR buf ;
 356 .IR put2 ,
 357 .IR put4 ,
 358 and
 359 .I put8
 360 write the 16-bit, 32-bit or 64-bit quantity contained in
 361 .IR val ,
 362 respectively.  The number of bytes transferred is returned.
 363 A \-1 return value indicates an error.
 364 .PP
 365 .IR Beswab ,
 366 .IR beswal ,
 367 and
 368 .I beswav
 369 return the
 370 .BR ushort ,
 371 .BR long ,
 372 and
 373 .B vlong
 374 big-endian representation of
 375 .IR val ,
 376 respectively.
 377 .IR Leswab ,
 378 .IR leswal ,
 379 and
 380 .I leswav
 381 return the little-endian representation of the
 382 .BR ushort ,
 383 .BR long ,
 384 and
 385 .B vlong
 386 contained in
 387 .IR val .
 388 .SH SOURCE
 389 .B /sys/src/libmach
 390 .SH "SEE ALSO"
 391 .IR 2c (1),
 392 .IR symbol (2),
 393 .IR object (2),
 394 .IR errstr (2),
 395 .IR proc (3),
 396 .IR a.out (6)
 397 .SH DIAGNOSTICS
 398 These routines set
 399 .IR errstr .