1 .TH MACH-CMD 3
2 .SH NAME
3 attachargs, attachcore, attachdynamic, attachproc, proctextfile \- debugging processes and core files
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .br
9 .B #include <mach.h>
10 .PP
11 .ta +\w'\fLextern 'u +\w'\fLchar *'u
12 .B
13 int	attachcore(Fhdr *hdr)
14 .PP
15 .B
16 int	attachproc(int pid)
17 .PP
18 .B
19 int	attachdynamic(void)
20 .PP
21 .B
22 char*	proctextfile(int pid)
23 .PP
24 .B
25 int	attachargs(int argc, char **argv, int omode)
26 .PP
27 .B
28 .nf
29 extern	Fhdr*	symhdr;
30 extern	char*	symfil;
31 extern	Map*	symmap;
32 extern	Fhdr*	fhdrlist;
33 .ift .sp .5
34 .ifn .sp
35 extern	Fhdr*	corhdr;
36 extern	char*	corfil;
37 extern	Map*	cormap;
38 .ift .sp .5
39 .ifn .sp
40 extern	int	corpid;
41 extern	Regs*	correg;
42 .SH DESCRIPTION
43 These routines provide access to the objects
44 a typical debugger manipulates: an executable binary,
45 some number of shared libraries, a memory image 
46 in the form of a core dump or active process,
47 and a register set.
48 .PP
49 The maintained state is:
50 .TP
51 .I symhdr
52 The file header for the main binary.
53 .TP
54 .I symfil
55 The file name of the main binary.
56 .TP
57 .I symmap
58 The memory map of the main binary.
59 .TP
60 .I fhdrlist
61 A linked list (via the
62 .B Fhdr.next
63 fields) of all currently open headers
64 (see
65 .I symopen
66 in
67 .MR mach-symbol (3) ).
68 When dynamically linked objects have been attached,
69 they are present in this linked list,
70 and therefore included in searches by
71 .IR indexsym ,
72 .IR lookupsym ,
73 and
74 .I findsym
75 (see
76 .MR mach-symbol (3) ).
77 .TP
78 .I corhdr
79 The file header for the core dump, if any.
80 .TP
81 .I corfil
82 The file name of the core dump, if any.
83 .TP
84 .I cormap
85 The memory map of the core dump or attached process.
86 .TP
87 .I corpid
88 The process id of the attached process, if any.
89 .TP
90 .I correg
91 The register set of the core dump or attached process.
92 .PD
93 If these fields are not valid, they are zeroed.
94 .PP
95 .I Attachcore
96 and
97 .I attachproc
98 attach to an opened core file or an executing process.
99 They set
100 .IR corhdr ,
101 .IR corfil ,
102 .IR cormap ,
103 .IR corpid ,
104 and
105 .IR correg .
106 .PP
107 .I Proctextfile
108 returns the name of the main binary for the process with id
109 .IR pid .
110 .PP
111 .I Attachdynamic
112 requires that the memory image already be attached.
113 It reads the dynamic linker's internal run-time data structures
114 and then opens all the dynamic objects that are currently
115 loaded.
116 .PP
117 .I Attachargs
118 uses all of these functions while
119 parsing an argument vector as would be passed to
120 a debugger like
121 .MR db (1)
122 or
123 .MR acid (1) .
124 It expects a list of executable files, core dump files, or process ids,
125 given in any order.
126 If extra arguments are given (for example, more than one executable, or both
127 a core dump and a process id), they are ignored and diagnostics are printed to 
128 standard error.
129 If arguments are missing (for example, the process id is given without an
130 executable file),
131 .I attachargs
132 fills them in as best it can.
133 .SH SOURCE
134 .B \*9/src/libmach
135 .SH "SEE ALSO
136 .MR mach (3) ,
137 .MR mach-file (3) ,
138 .MR mach-map (3)
139 .SH BUGS
140 The interface needs to be changed to support
141 multiple threads, each with its own register set.