Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MACH-MAP(3)		   Library Functions Manual		   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, loce-
       val, locfmt, locsimplify, lget1,	lget2,	lget4,	lget8,	lput1,	lput2,
       lput4,  lput8 - machine-independent access to address spaces and	regis-
       ter 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)
       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 processes	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 proces-
       sor-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
       (base)  and  an	extent (size).	In segments mapped by files, the range
       begins at byte offset in	the file.  The rw function  is	most  commonly
       used  to	provide	access to executing processes via ptrace(2) and	to ze-
       roed 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 ad-
       dress, or -1 if that address is not mapped.  Segments may have overlap-
       ping address ranges: addseg appends segments to the end of the seg  ar-
       ray  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 re-
       turned 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 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, put4, and  put8  write  the
       16-bit,	32-bit or 64-bit quantity contained in val, respectively.  The
       number of bytes transferred is returned.	 A -1 return  value  indicates
       an error.

       When representing core files or running programs, maps also provide ac-
       cess to the register set.  Rget and rput	read  or  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 result-
       ing string.  Code must be either	or selecting double or	single	preci-
       sion,  respectively.  If	code is	the contents of	the specified register
       and the following register are interpreted as a double-precision	float-
       ing-point number; this is meaningful only for architectures that	imple-
       ment 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	 loca-
       tion  representing the register reg.  Locindir returns an location rep-
       resenting the memory address at offset added to the value of reg.  Loc-
       const  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 or-
       dered before indirections.

       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
       /usr/local/plan9/src/libmach

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

DIAGNOSTICS
       These routines set errstr.

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

								   MACH-MAP(3)

NAME | SYNOPSIS | DESCRIPTION | SOURCE | SEE ALSO | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mach-map&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help