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