MACH(2)                                                   MACH(2)

     NAME
          crackhdr, machbytype, machbyname, newmap, setmap, unusemap,
          loadmap, findseg, get1, get2, get4, put1, put2, put4,
          beswab, beswal, leswab, leswal - machine-independent
          executable file access

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <bio.h>
          #include <mach.h>

          int crackhdr(int fd, Fhdr *fp)

          void machbytype(int type)

          int machbyname(char *name)

          Map *newmap(Map *map, int fd, int n)

          int setmap(Map *map, ulong base, ulong end, ulong foffset,

                     char *name)

          void unusemap(Map *map, int seg)

          Map *loadmap(Map *map, int fd, Fhdr *fp)

          int findseg(Map *map, char *name)

          int get1(Map *map, ulong addr, uchar *buf, int n)

          int get2(Map *map, ulong addr, ushort *val)

          int get4(Map *map, ulong addr, long *val)

          int put1(Map *map, ulong addr, uchar *buf, int n)

          int put2(Map *map, ulong addr, ushort val)

          int put4(Map *map, ulong addr, long val)

          ushort beswab(ushort val)

          long beswal(long val)

          ushort leswab(ushort val)

          long leswal(long val)

     MACH(2)                                                   MACH(2)

          extern Mach mach;

          extern Machdata machdata;

     DESCRIPTION
          These functions provide machine-independent access to an
          executable file or executing process image.  The latter is
          accessed by opening either /proc/pid/text or /proc/pid/mem
          as described in proc(3). Symbol(2) and object(2) describe
          other library functions for machine-independent access to
          symbol tables and object files.

          Crackhdr loads data structure fp with a machine-independent
          description of the header of the executable file or image
          associated with the open file descriptor fd. It also sets
          global variable mach pointing to the Mach data structure
          containing the machine-dependent parameters of the target
          architecture.

          Machbytype and machbyname select the data structures and
          parameter values associated with the specified architecture.
          The former selects the architecture based on the code stored
          in the field named type in the Fhdr data structure.  The
          latter selects a processor class by name; one of 68020,
          mips, mipsco, sparc, sunsparc, 386, 86, or 960. These func-
          tions point the mach and machdata global variables to the
          proper Mach and Machdata data structures and load global
          variable asstype with the disassembler type code.

          A map is a data structure used to transform an address in
          the address space of an executable to an offset in a file or
          executing image.  A map comprises one or more segments, each
          associating a range of addresses with an offset in the file
          or memory image.  The range of one segment may not overlap
          the range of another segment in the map.  Most maps define
          segments named `text' and `data' to map the instruction and
          initialized data sections of an executable file.  When the
          map is associated with the memory image of an executing pro-
          gram, the range of the `data' segment is usually extended to
          include the bss, heap, and stack of the process and an addi-
          tional segment, named `ublock', maps the page containing the
          saved registers and process state information.

          Newmap creates a map with n segments or recycles a map cur-
          rently in use.  If map is zero, a new map is dynamically
          allocated, otherwise it is assumed to point to an existing
          dynamically allocated map whose size is adjusted, as neces-
          sary.  The map is associated with the open file descriptor
          fd and all segments are marked as unused.  The address of
          the map is returned.  A zero return indicates an allocation
          error.

     MACH(2)                                                   MACH(2)

          Setmap loads the first unused segment in map with the seg-
          ment mapping parameters.  Base and end contain the lowest
          and highest virtual addresses mapped by the segment.
          Foffset contains the offset in the executable to the start
          of the segment.  Name is a name to be attached to the seg-
          ment.

          Unusemap marks segment number seg in map map unused.  Other
          segments in the map remain unaffected.

          Loadmap uses the values in a Fhdr data structure (usually
          filled by crackhdr) to initialize a default map for an exe-
          cutable file or executing image.  If map is zero, a new map
          with two segments is dynamically allocated; otherwise, map
          is initialized with the appropriate values.  This function
          returns the address of the map if successful, zero on fail-
          ure.  Two segments, named `text' and `data' are defined in
          the map; they map the instruction and initialized data sec-
          tions of the program described by the Fhdr structure.

          Get1, get2, and get4 retrieve the data stored at address
          addr in the program file or executable image associated with
          map. Get1 retrieves n bytes of data beginning at addr into
          buf. Get2 and get4 retrieve 16-bit and 32-bit values respec-
          tively, into the location pointed to by val. The value is
          byte-swapped if the source byte order differs from that of
          the current architecture.  This implies that the value
          returned by get4 may not be the same as the four-byte
          sequence returned by get1 when n is four; the former may be
          byte-swapped, the latter is independent of source and target
          byte order.  If the file descriptor associated with map is
          negative, the address itself is placed in the return loca-
          tion.  These functions return the number of bytes read.  A
          -1 indicates an error condition.

          Put1, put2, and put4 write to the file or executing image
          associated with map. The address is translated using the map
          parameters and multi-byte quantities are byte-swapped, if
          necessary, before they are written.  Put1 transfers n bytes
          stored at buf; put2 and put4 write the 16-bit and 32-bit
          quantity contained in val, respectively.  The number of
          bytes transferred is returned.  A -1 return value indicates
          an error.

          Beswab and beswal return the ushort and long big-endian rep-
          resentation of val, respectively.  Leswab and leswal return
          the little-endian representation of the ushort and long con-
          tained in val.

     SOURCE
          /sys/src/libmach

     MACH(2)                                                   MACH(2)

     SEE ALSO
          symbol(2), object(2), errstr(2), proc(3), a.out(6)

     DIAGNOSTICS
          These routines set errstr.