MACH-MAP(3)                                           MACH-MAP(3)

     NAME
          allocmap, addseg, findseg, addrtoseg, addrtosegafter,
          removeseg, freemap, get1, get2, get4, get8, put1, put2,
          put4, put8, rget, rput, fpformat, locnone, locaddr,
          locconst, locreg, locindir, loccmp, loceval, locfmt,
          locsimplify, lget1, lget2, lget4, lget8, lput1, lput2,
          lput4, lput8 - machine-independent access to address spaces
          and register sets

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

          typedef struct Map Map;
          typedef struct Seg Seg;

          struct Seg
          {
                char   *name;
                char   *file;
                int    fd;
                ulong  base;
                ulong  size;
                ulong  offset;
                int    (*rw)(Map*, Seg*, ulong, void*, uint, int);
          };

          struct Map
          {
                Seg    *seg;
                int    nseg;
                ...
          };

          Map   *allocmap(void)
          int   addseg(Map *map, Seg seg)
          int   findseg(Map *map, char *name, char *file)
          int   addrtoseg(Map *map, ulong addr, Seg *seg)
          int   addrtosegafter(Map *map, ulong addr, Seg *seg)
          void  removeseg(Map *map, int i)
          void  freemap(Map *map)

          int   get1(Map *map, ulong addr, uchar *a, uint n)
          int   get2(Map *map, ulong addr, u16int *u)
          int   get4(Map *map, ulong addr, u32int *u)
          int   get8(Map *map, ulong addr, u64int *u)

          int   put1(Map *map, ulong addr, uchar *a, uint n)
          int   put2(Map *map, ulong addr, u16int u)

     MACH-MAP(3)                                           MACH-MAP(3)

          int   put4(Map *map, ulong addr, u32int u)
          int   put8(Map *map, ulong addr, u64int u)

          int   rget(Regs *regs, char *reg, ulong *u)
          int   fpformat(Map *map, char *reg, char *a, uint n, char code);

          int   rput(Regs *regs, char *name, ulong u)

          Loc   locnone(void)
          Loc   locaddr(ulong addr)
          Loc   locconst(ulong con)
          Loc   locreg(char *reg)
          Loc   locindir(char *reg, long offset)

          int   loccmp(Loc *a, Loc *b)
          int   loceval(Map *map, Loc loc, ulong *addr)
          int   locfmt(Fmt *fmt)
          int   locsimplify(Map *map, Loc *regs, Loc loc, Loc *newloc)

          int   lget1(Map *map, Loc loc, uchar *a, uint n)
          int   lget2(Map *map, Loc loc, u16int *u)
          int   lget4(Map *map, Loc loc, u32int *u)
          int   lget8(Map *map, Loc loc, u64int *u)

          int   lput1(Map *map, Loc loc, uchar *a, uint n)
          int   lput2(Map *map, Loc loc, u16int u)
          int   lput4(Map *map, Loc loc, u32int u)
          int   lput8(Map *map, Loc loc, u64int u)

     DESCRIPTION
          These functions provide a processor-independent interface
          for accessing executable files, core files, and running pro-
          cesses via maps, data structures that provides access to an
          address space and register set.  The functions described in
          mach-file(3) are typically used to construct these maps.
          Related library functions described in mach-symbol(3) pro-
          vide similar access to symbol tables.

          Each map comprises an optional register set and one or more
          segments, each associating a non-overlapping range of memory
          addresses with a logical section of an executable file or of
          a running process's address space.  Other library functions
          then use a map and the architecture-specific data structures
          to provide a generic interface to the processor-dependent
          data.

          Each segment has a name (e.g., text or data) and may be
          associated with a particular file.  A segment represents a
          range of accessible address space.  Segments may be backed
          an arbitary access function (if the rw pointer is non-nil),
          or by the contents of an open file (using the fd file
          descriptor).  Each range has a starting address in the space

     MACH-MAP(3)                                           MACH-MAP(3)

          (base) and an extent (size).  In segments mapped by files,
          the range begins at byte offset in the file.  The rw func-
          tion is most commonly used to provide access to executing
          processes via ptrace(2) and to zeroed segments.

          Allocmap creates an empty map; freemap frees a map.

          Addseg adds the given segment to the map, resizing the map's
          seg array if necessary.  A negative return value indicates
          an allocation error.

          Findseg returns the index of the segment with the given name
          (and, if file is non-nil, the given file), or -1 if no such
          segment is found.

          Addrtoseg returns the index of the segment containing for
          the given address, or -1 if that address is not mapped.
          Segments may have overlapping address ranges: addseg appends
          segments to the end of the seg array in the map, and
          addrtoseg searches the map backwards from the end, so the
          most recently mapped segment wins.

          Addrtosegafter returns the index of the segment containing
          the lowest mapped address greater than addr.

          Removeseg removes the segment at the given index.

          Get1, get2, get4, and get8 retrieve the data stored at
          address addr in the address space associated with map. Get1
          retrieves n bytes of data beginning at addr into buf. Get2,
          get4 and get8 retrieve 16-bit, 32-bit and 64-bit values
          respectively, into the location pointed to by u. The value
          is byte-swapped if the source byte order differs from that
          of the current architecture.  This implies that the value
          returned by get2, get4, and get8 may not be the same as the
          byte sequences returned by get1 when n is two, four or
          eight; the former may be byte-swapped, the latter reflects
          the byte order of the target architecture.  These functions
          return the number of bytes read or a -1 when there is an
          error.

          Put1, put2, put4, and put8 write to the address space asso-
          ciated 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, put4, and put8 write the 16-bit, 32-bit
          or 64-bit quantity contained in val, respectively.  The num-
          ber of bytes transferred is returned.  A -1 return value
          indicates an error.

          When representing core files or running programs, maps also
          provide access to the register set.  Rget and rput read or

     MACH-MAP(3)                                           MACH-MAP(3)

          write the register named by reg. If the register is smaller
          than a ulong, the high bits are ignored.

          Fpformat converts the contents of a floating-point register
          to a string.  Buf is the address of a buffer of n bytes to
          hold the resulting string.  Code must be either `F' or `f',
          selecting double or single precision, respectively.  If code
          is `F', the contents of the specified register and the fol-
          lowing register are interpreted as a double-precision
          floating-point number; this is meaningful only for architec-
          tures that implement double-precision floats by combining
          adjacent single-precision registers.

          A location represents a place in an executing image capable
          of storing a value.  Note that locations are typically
          passed by value rather than by reference.

          Locnone returns an unreadable, unwritable location.  Locaddr
          returns a location representing the memory address addr.
          Locreg returns a location representing the register reg.
          Locindir returns an location representing the memory address
          at offset added to the value of reg. Locconst returns an
          imaginary unwritable location holding the constant con; such
          locations are useful for passing specific constants to func-
          tions expect locations, such as unwind (see mach-stack(3)).

          Loccmp compares two locations, returning negative, zero, or
          positive values if *a is less than, equal to, or greater
          than *b, respectively.  Register locations are ordered
          before memory addresses, which are ordered before indirec-
          tions.

          Locfmt is a print(3)-verb that formats a Loc structure (not
          a pointer to one).

          Indirection locations are needed in some contexts (e.g.,
          when using findlsym (see mach-symbol(3))), but bothersome in
          most.  Locsimplify rewrites indirections as absolute memory
          addresses, by evaluating the register using the given map
          and adding the offset.

          The functions lget1, lget2, lget4, lget8, lput1, lput2,
          lput4, and lput8 read and write the given locations, using
          the get, put, rget, and rput function families as necessary.

     SOURCE
          /src/libmach

     SEE ALSO
          mach(3), mach-file(3)

     DIAGNOSTICS

     MACH-MAP(3)                                           MACH-MAP(3)

          These routines set errstr.

     BUGS
          This man page needs to describe Regs and Regdesc and
          coreregs.