tmach-file.3 - plan9port - [fork] Plan 9 from user space
(HTM) git clone git://src.adamsgaard.dk/plan9port
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
tmach-file.3 (3821B)
---
1 .TH MACH-FILE 3
2 .SH NAME
3 crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc,
4 procnotes \- machine-independent access to exectuable files and running processes
5 .SH SYNOPSIS
6 .B #include <u.h>
7 .br
8 .B #include <libc.h>
9 .br
10 .B #include <mach.h>
11 .PP
12 .ft B
13 .ta \w'\fBxxxxxx'u +\w'xxxxxx'u
14 int crackhdr(int fd, Fhdr *hdr)
15 .br
16 void uncrackhdr(Fhdr *hdr)
17 .PP
18 .ft B
19 int mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs)
20 .br
21 void unmapfile(Fhdr *hdr, Map *map)
22 .br
23 int mapproc(int pid, Map *map, Regs **regs)
24 .br
25 void unmapproc(Map *map)
26 .br
27 int detachproc(int pid)
28 .br
29 int ctlproc(int pid, char *msg)
30 .br
31 int procnotes(int pid, char ***notes)
32 .SH DESCRIPTION
33 These functions parse executable files and
34 provide access to those files and to running processes.
35 .PP
36 .I Crackhdr
37 opens and parses the named executable file.
38 The returned data structure
39 .I hdr
40 is initialized with a machine-independent description
41 of the header information. The following fields are the
42 most commonly used:
43 .TP
44 .B mach
45 a pointer to the
46 .B Mach
47 structure for the target architecture
48 .TP
49 .B mname
50 the name of the target architecture
51 .TP
52 .B fname
53 a description of the kind of file
54 (e.g., executable, core dump)
55 .TP
56 .B aname
57 a description of the application binary interface
58 this file uses; typically it is the name of an operating system
59 .PD
60 If the global variable
61 .I mach
62 is nil,
63 .I crackhdr
64 points it to the same
65 .B Mach
66 structure.
67 .PP
68 .I Mapfile
69 adds the segments found in
70 .I hdr
71 to
72 .IR map .
73 If
74 .I hdr
75 is an executable file, there are typically three segments:
76 .IR text ,
77 .IR data ,
78 and a zero-backed
79 .IR bss .
80 If
81 .I hdr
82 is a dynamic shared library, its segments are relocated by
83 .I base
84 before being mapping.
85 .PP
86 If
87 .I hdr
88 is a core file, there is one segment named
89 .I core
90 for each contiguous section of memory recorded in the core file.
91 There are often quite a few of these, as most operating systems
92 omit clean memory pages when writing core files
93 (Mac OS X is the only exception among the supported systems).
94 Because core files have such holes, it is typically necessary to
95 construct the core map by calling
96 .I mapfile
97 on the executable and then calling it again on the core file.
98 Newly-added segments are mapped on top of existing segments,
99 so this arrangement will use the core file for the segments it contains
100 but fall back to the executable for the rest.
101 .PP
102 .I Unmapfile
103 removes the mappings in
104 .I map
105 corresponding to
106 .IR hdr .
107 .PP
108 .I Mapproc
109 attaches to a running program and adds its segments to the given map.
110 It adds one segment for each contiguous section of
111 mapped memory.
112 On systems where this information cannot be determined, it adds
113 a single segment covering the entire address space.
114 Accessing areas of this segment that are actually not mapped
115 in the process address space will cause the get/put routines to return errors.
116 .PP
117 .I Unmapproc
118 removes the mappings in
119 .I map
120 corresponding to
121 .IR pid .
122 .I Detachproc
123 detaches from all previously attached processes.
124 .PP
125 .I Ctlproc
126 manipulates the process with id
127 .I pid
128 according to the message
129 .IR msg .
130 Valid messages include:
131 .TP
132 .B kill
133 terminate the process
134 .TP
135 .B startstop
136 start the process and wait for it to stop
137 .TP
138 .B sysstop
139 arrange for the process to stop at its next system call,
140 start the process, and then wait for it to stop
141 .TP
142 .B waitstop
143 wait for the process to stop
144 .TP
145 .B start
146 start the process
147 .PD
148 .PP
149 .I Procnotes
150 fills
151 .BI * notes
152 with a pointer to an array of strings
153 representing pending notes waiting
154 for the process.
155 (On Unix, these notes are textual descriptions
156 of any pending signals.)
157 .I Procnotes
158 returns the number of pending notes.
159 The memory at
160 .BI * notes
161 should be freed via
162 .I free
163 (see
164 .MR malloc (3) )
165 when no longer needed.
166 .SH SOURCE
167 .B \*9/src/libmach
168 .SH "SEE ALSO"
169 .MR mach (3) ,
170 .MR mach-map (3)