glenda.party
term% ls -F
term% pwd
$home/manuals/9front/2/mach
term% cat index.txt
MACH(2)                       System Calls Manual                      MACH(2)



NAME
       crackhdr,  machbytype,  machbyname,  newmap, setmap, findseg, unusemap,
       loadmap, attachproc, get1, get2, get4, get8, geta,  put1,  put2,  put4,
       put8, puta beswab, beswal, beswav, leswab, leswal, leswav - machine-in‐
       dependent access to executable files

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 n)

       int setmap(Map *map, int fd, uvlong base, uvlong end,

                   vlong foffset, char *name)

       int findseg(Map *map, char *name)

       void unusemap(Map *map, int seg)

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

       Map *attachproc(int pid, int kflag, int corefd, Fhdr *fp)

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

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

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

       int get8(Map *map, uvlong addr, uvlong *val)

       int geta(Map *map, uvlong addr, uvlong *val)

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

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

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

       int put8(Map *map, uvlong addr, uvlong val)

       int puta(Map *map, uvlong addr, uvlong val)

       ushort beswab(ushort val)

       long beswal(ulong val)

       long beswav(uvlong val)

       ushort leswab(ushort val)

       long leswal(ulong val)

       long leswav(uvlong val)

       extern Mach mach;

       extern Machdata machdata;

DESCRIPTION
       These functions provide a processor-independent interface for accessing
       the executable files or executing images of all architectures.  Related
       library functions described in symbol(2) and object(2) provide  similar
       access to symbol tables and object files.

       An  executable  is  a file containing an executable program or the text
       file of the /proc file system associated with an executing  process  as
       described  in proc(3).  After opening an executable, an application in‐
       vokes a library function which parses the file header,  determines  the
       target architecture and initializes data structures with parameters and
       pointers to functions appropriate for that architecture.  Next, the ap‐
       plication  invokes functions to construct one or more maps, data struc‐
       tures that translate references in the address space of the  executable
       to  offsets in the file.  Each map comprises one or more segments, each
       associating a non-overlapping range of memory addresses with a  logical
       section  of the executable.  Other library functions then use a map and
       the architecture-specific data structures to provide a  generic  inter‐
       face to the processor-dependent data.

       Crackhdr  interprets  the  header of the executable associated with the
       open file descriptor fd.  It loads the data structure  fp  with  a  ma‐
       chine-independent  description  of  the  header  information and points
       global variable mach to the Mach data structure  containing  processor-
       dependent parameters of the target architecture.

       Machbytype  selects architecture-specific data structures and parameter
       values based on the code stored in the field named  type  in  the  Fhdr
       data  structure.   Machbyname  performs the same selection based on the
       name of a processor class; see 2c(1) for a list of valid  names.   Both
       functions  point  global  variables  mach  and machdata to the Mach and
       Machdata data structures appropriate for the  target  architecture  and
       load global variable asstype with the proper disassembler type code.

       Newmap  creates  an empty map with n segments.  If map is zero, the new
       map is dynamically allocated, otherwise it is assumed to  point  to  an
       existing  dynamically  allocated  map whose size is adjusted, as neces‐
       sary.  A zero return value indicates an allocation error.

       Setmap loads the first unused segment in map with the  segment  mapping
       parameters.   Fd  is  an  open  file descriptor associated with an exe‐
       cutable.  Base and end contain the lowest and highest virtual addresses
       mapped  by the segment.  Foffset is the offset to the start of the seg‐
       ment in the file.  Name is a name to be attached to the segment.

       Findseg returns the index of the segment named name in map.   A  return
       of -1 indicates that no segment matches name.

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

       Loadmap initializes a default map containing segments named `text'  and
       `data' that map the instruction and data segments of the executable de‐
       scribed in the Fhdr structure pointed to by fp.  Usually that structure
       was loaded by crackhdr and can be passed to this function without modi‐
       fication.  If map is non-zero, that map, which must have  been  dynami‐
       cally  allocated,  is  resized to contain two segments; otherwise a new
       map is allocated.  This function  returns  zero  if  allocation  fails.
       Loadmap  is  usually  used  to  build a map for accessing a static exe‐
       cutable, for example, an executable program file.

       Attachproc constructs a map for accessing a running  process.   It  re‐
       turns  the  address  of  a  Map containing segments mapping the address
       space of the running process whose process ID is pid.  If kflag is non-
       zero, the process is assumed to be a kernel process.  Corefd is an file
       descriptor opened to /proc/pid/mem.  Fp points to  the  Fhdr  structure
       describing  the  header  of the executable.  For most architectures the
       resulting Map contains four segments named `text', `data',  `regs'  and
       `fpregs'.   The  latter  two provide access to the general and floating
       point registers, respectively.  If the executable is a  kernel  process
       (indicated  by  a non-zero kflag argument), the data segment extends to
       the maximum supported address, currently 0xffffffff, and  the  register
       sets  are  read-only.  In user-level programs, the data segment extends
       to the top of the stack or 0x7fffffff if the stack top cannot be found,
       and  the  register  sets are readable and writable.  Attachproc returns
       zero if it is unable to build the map for the specified process.

       Get1, get2, get4, and get8 retrieve the data stored at address addr  in
       the executable associated with map.  Get1 retrieves n bytes of data be‐
       ginning at addr into buf.  Get2, get4 and get8 retrieve 16-bit,  32-bit
       and  64-bit  values  respectively, 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
       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.  If  the
       file  descriptor associated with the applicable segment in map is nega‐
       tive, the address itself is placed in the return location.  These func‐
       tions return the number of bytes read or a -1 when there is an error.

       Put1, put2, put4, and put8 write to the executable associated with map.
       The address is translated using the map parameters and multi-byte quan‐
       tities  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  er‐
       ror.

       Beswab,  beswal,  and beswav return the ushort, long, and vlong big-en‐
       dian representation of val, respectively.  Leswab, leswal,  and  leswav
       return  the little-endian representation of the ushort, long, and vlong
       contained in val.

SOURCE
       /sys/src/libmach

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

DIAGNOSTICS
       These routines set errstr.



                                                                       MACH(2)