Rewrite page(2) references to page(3).

Add description of new libmach.

1 files changed, 61 insertions, 371 deletions

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 <u.h>
 .br
 .B #include <libc.h>
 .br
-.B #include <bio.h>
-.br
 .B #include <mach.h>
 .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)