From cfa37a7b1131abbab2e7d339b451f5f0e3198cc8 Mon Sep 17 00:00:00 2001 From: rsc Date: Sat, 10 Apr 2004 18:53:55 +0000 Subject: Lots of man pages. --- man/man3/mach.3 | 393 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 393 insertions(+) create mode 100644 man/man3/mach.3 (limited to 'man/man3/mach.3') diff --git a/man/man3/mach.3 b/man/man3/mach.3 new file mode 100644 index 00000000..82313e62 --- /dev/null +++ b/man/man3/mach.3 @@ -0,0 +1,393 @@ +.TH MACH 3 +.SH NAME +crackhdr, machbytype, machbyname, newmap, setmap, findseg, unusemap, +loadmap, attachproc, get1, get2, get4, get8, put1, put2, put4, put8, +beswab, beswal, beswav, leswab, leswal, leswav \- machine-independent access to executable files +.SH SYNOPSIS +.B #include +.br +.B #include +.br +.B #include +.br +.B #include +.PP +.ta \w'\fLmachines 'u +.B +int crackhdr(int fd, Fhdr *fp) +.PP +.B +void machbytype(int type) +.PP +.B +int machbyname(char *name) +.PP +.B +Map *newmap(Map *map, int n) +.PP +.B +int setmap(Map *map, int fd, ulong base, ulong end, +.PP +.B + ulong foffset, char *name) +.PP +.B +int findseg(Map *map, char *name) +.PP +.B +void unusemap(Map *map, int seg) +.PP +.B +Map *loadmap(Map *map, int fd, Fhdr *fp) +.PP +.B +Map *attachproc(int pid, int kflag, int corefd, Fhdr *fp) +.PP +.B +int get1(Map *map, ulong addr, uchar *buf, int n) +.PP +.B +int get2(Map *map, ulong addr, ushort *val) +.PP +.B +int get4(Map *map, ulong addr, long *val) +.PP +.B +int get8(Map *map, ulong addr, vlong *val) +.PP +.B +int put1(Map *map, ulong addr, uchar *buf, int n) +.PP +.B +int put2(Map *map, ulong addr, ushort val) +.PP +.B +int put4(Map *map, ulong addr, long val) +.PP +.B +int put8(Map *map, ulong addr, vlong val) +.PP +.B +ushort beswab(ushort val) +.PP +.B +long beswal(long val) +.PP +.B +long beswav(vlong val) +.PP +.B +ushort leswab(ushort val) +.PP +.B +long leswal(long val) +.PP +.B +long leswav(vlong val) +.PP +.B +extern Mach mach; +.PP +.B +extern Machdata machdata; +.SH DESCRIPTION +These functions provide +a processor-independent interface for accessing +the executable files or executing images of all +architectures. +Related library functions described in +.IR symbol (2) +and +.IR object (2) +provide similar access to symbol tables and object files. +.PP +An +.I executable +is a file containing an executable program or the +.B text +file of the +.B /proc +file system associated with an executing process as +described in +.IR proc (3). +After opening an executable, an application +invokes 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 application +invokes functions to construct one or more +.IR maps , +data structures that translate references +in the address space of the executable +to offsets in the file. Each +.I map +comprises one or more +.BR 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 interface to the +processor-dependent data. +.PP +.I Crackhdr +interprets the header of the executable +associated with +the open file descriptor +.IR fd . +It loads the data structure +.I fp +with a machine-independent description +of the header information and +points global variable +.I mach +to the +.B Mach +data structure containing processor-dependent parameters +of the target architecture. +.PP +.I Machbytype +selects architecture-specific data structures and parameter +values based on +the code stored in the +field named +.I type +in the +.B Fhdr +data structure. +.I Machbyname +performs the same selection based +on the name of a processor class; see +.IR 2c (1) +for a list of valid names. +Both functions point global variables +.I mach +and +.I machdata +to the +.I Mach +and +.I Machdata +data structures appropriate for the +target architecture and load global variable +.I asstype +with the proper disassembler type code. +.PP +.I Newmap +creates an empty map with +.I n +segments. +If +.I 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 necessary. +A zero return value indicates an allocation error. +.PP +.I Setmap +loads the first unused segment in +.I map +with the +segment mapping parameters. +.I Fd +is an open file descriptor associated with +an executable. +.I Base +and +.I end +contain the lowest and highest virtual addresses +mapped by the segment. +.I Foffset +is the offset to the start of the segment in the file. +.I Name +is a name to be attached to the segment. +.PP +.I Findseg +returns the index of the the +segment named +.I name +in +.IR map . +A return of -1 indicates that no +segment matches +.IR name . +.PP +.I Unusemap +marks segment number +.I seg +in map +.I map +unused. Other +segments in the map remain unaffected. +.PP +.I Loadmap +initializes a default map containing +segments named `text' and `data' that +map the instruction and data segments +of the executable described in the +.B Fhdr +structure pointed to by +.IR fp . +Usually that structure was loaded by +.IR crackhdr +and can be passed to this function without +modification. +If +.I map +is non-zero, that map, which must have been +dynamically allocated, is resized to contain two segments; +otherwise a new map is allocated. +This function returns zero if allocation fails. +.I Loadmap +is usually used to build a map for accessing +a static executable, for example, an executable +program file. +.PP +.I Attachproc +constructs a map for accessing a +running process. It +returns the address of a +.I Map +containing segments mapping the +address space of the running process +whose process ID is +.BR pid . +If +.B kflag +is non-zero, the process is assumed to be +a kernel process. +.B Corefd +is an file descriptor opened to +.BR /proc/\fIpid\fP/mem . +.B Fp +points to the +.I Fhdr +structure describing the header +of the executable. For most architectures +the resulting +.I 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 +.B 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. +.I Attachproc +returns zero if it is unable to build the map +for the specified process. +.PP +.IR Get1 , +.IR get2 , +.IR get4 , +and +.I get8 +retrieve the data stored at address +.I addr +in the executable associated +with +.IR map . +.I Get1 +retrieves +.I n +bytes of data beginning at +.I addr +into +.IR buf . +.IR Get2 , +.I get4 +and +.I get8 +retrieve 16-bit, 32-bit and 64-bit values respectively, +into the location pointed to by +.IR 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 +.IR get2 , +.IR get4 , +and +.I get8 +may not be the same as the byte sequences +returned by +.I get1 +when +.I 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 +.I map +is negative, the address itself is placed in the +return location. These functions return the number +of bytes read or a \-1 when there is an error. +.PP +.IR Put1 , +.IR put2 , +.IR put4 , +and +.I put8 +write to +the executable associated with +.IR map . +The address is translated using the +map parameters and multi-byte quantities are +byte-swapped, if necessary, before they are written. +.I Put1 +transfers +.I n +bytes stored at +.IR buf ; +.IR put2 , +.IR put4 , +and +.I put8 +write the 16-bit, 32-bit or 64-bit quantity contained in +.IR val , +respectively. The number of bytes transferred is returned. +A \-1 return value indicates an error. +.PP +.IR Beswab , +.IR beswal , +and +.I beswav +return the +.BR ushort , +.BR long , +and +.B vlong +big-endian representation of +.IR val , +respectively. +.IR Leswab , +.IR leswal , +and +.I leswav +return the little-endian representation of the +.BR ushort , +.BR long , +and +.B vlong +contained in +.IR val . +.SH SOURCE +.B /sys/src/libmach +.SH "SEE ALSO" +.IR 2c (1), +.IR symbol (2), +.IR object (2), +.IR errstr (2), +.IR proc (3), +.IR a.out (6) +.SH DIAGNOSTICS +These routines set +.IR errstr . -- cgit v1.2.3