From bf8a59fa013f5c705369fbe14e23ca78c4d09cb8 Mon Sep 17 00:00:00 2001 From: rsc Date: Sun, 11 Apr 2004 03:42:27 +0000 Subject: Rewrite page(2) references to page(3). Add description of new libmach. --- man/man3/mach.3 | 432 ++++++++------------------------------------------------ 1 file changed, 61 insertions(+), 371 deletions(-) (limited to 'man/man3/mach.3') diff --git a/man/man3/mach.3 b/man/man3/mach.3 index 82313e62..62807e82 100644 --- a/man/man3/mach.3 +++ b/man/man3/mach.3 @@ -1,20 +1,13 @@ .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 +machbytype, machbyname \- machine-independent access to executables and programs .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) @@ -23,371 +16,68 @@ void machbytype(int type) 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; +extern Mach *mach; .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 +.I Libmach +provides an interface for accessing +the executable files and executing images of various architectures +and operating systems. +The interface is machine-independent, meaning that, for example, +Mac OS X core dumps may be inspected using an x86 Linux machine +and vice versa. +In its current form, +the library is mainly useful for writing debuggers +of one sort or another. +.PP +An architecture is described primarily by a .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 +structure, which contains +data structures and parameters describing the +particular architecture. +Most library functions assume that the global variable .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 . +points at the structure for the architecture being debugged. +It is set implicitly by +.I crackhdr +(see +.IR mach-file (3)) +and can be set explicitly by calling +.I machbyname +or +.IR machbytype . +.PP +There is no operating system-specific structure akin to +.IR mach . +Typically the choice of operating system on a particular +architecture affects only the executable and core dump formats; +the various file parsers deduce the operating system from +information in the binary files themselves and adjust +accordingly. +.PP +Other manual pages +describe the library functions in detail. +.PP +.I Mach-file (3) +describes the manipulation of binary files. +.PP +.I Mach-map (3) +describes the interface to address spaces and register sets +in executable files and executing programs. +.PP +.I Mach-stack (3) +describes support for unwinding the stack. +.PP +.I Mach-swap (3) +describes helper functions for accessing data +in a particular byte order. +.PP +.I Mach-symbol (3) +describes the interface to debugging symbol information. .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 . +.SH "SEE ALSO +.IR mach-file (3), +.IR mach-map (3), +.IR mach-stack (3), +.IR mach-swap (3), +.IR mach-symbol (3) -- cgit v1.2.3