1 bf8a59fa 2004-04-11 devnull .TH MACH-FILE 3
3 058b0118 2005-01-03 devnull crackhdr, uncrackhdr, mapfile, unmapfile, mapproc, unmapproc, detachproc, ctlproc,
4 bf8a59fa 2004-04-11 devnull procnotes \- machine-independent access to exectuable files and running processes
5 bf8a59fa 2004-04-11 devnull .SH SYNOPSIS
6 bf8a59fa 2004-04-11 devnull .B #include <u.h>
8 bf8a59fa 2004-04-11 devnull .B #include <libc.h>
10 bf8a59fa 2004-04-11 devnull .B #include <mach.h>
13 bf8a59fa 2004-04-11 devnull .ta \w'\fBxxxxxx'u +\w'xxxxxx'u
14 bf8a59fa 2004-04-11 devnull int crackhdr(int fd, Fhdr *hdr)
16 bf8a59fa 2004-04-11 devnull void uncrackhdr(Fhdr *hdr)
19 058b0118 2005-01-03 devnull int mapfile(Fhdr *hdr, ulong base, Map *map, Regs **regs)
21 058b0118 2005-01-03 devnull void unmapfile(Fhdr *hdr, Map *map)
23 058b0118 2005-01-03 devnull int mapproc(int pid, Map *map, Regs **regs)
25 058b0118 2005-01-03 devnull void unmapproc(Map *map)
27 bf8a59fa 2004-04-11 devnull int detachproc(int pid)
29 bf8a59fa 2004-04-11 devnull int ctlproc(int pid, char *msg)
31 bf8a59fa 2004-04-11 devnull int procnotes(int pid, char ***notes)
32 bf8a59fa 2004-04-11 devnull .SH DESCRIPTION
33 bf8a59fa 2004-04-11 devnull These functions parse executable files and
34 bf8a59fa 2004-04-11 devnull provide access to those files and to running processes.
36 bf8a59fa 2004-04-11 devnull .I Crackhdr
37 bf8a59fa 2004-04-11 devnull opens and parses the named executable file.
38 bf8a59fa 2004-04-11 devnull The returned data structure
40 bf8a59fa 2004-04-11 devnull is initialized with a machine-independent description
41 bf8a59fa 2004-04-11 devnull of the header information. The following fields are the
42 bf8a59fa 2004-04-11 devnull most commonly used:
45 bf8a59fa 2004-04-11 devnull a pointer to the
47 bf8a59fa 2004-04-11 devnull structure for the target architecture
50 bf8a59fa 2004-04-11 devnull the name of the target architecture
53 bf8a59fa 2004-04-11 devnull a description of the kind of file
54 bf8a59fa 2004-04-11 devnull (e.g., executable, core dump)
57 bf8a59fa 2004-04-11 devnull a description of the application binary interface
58 bf8a59fa 2004-04-11 devnull this file uses; typically it is the name of an operating system
60 bf8a59fa 2004-04-11 devnull If the global variable
63 bf8a59fa 2004-04-11 devnull .I crackhdr
64 bf8a59fa 2004-04-11 devnull points it to the same
66 bf8a59fa 2004-04-11 devnull structure.
68 bf8a59fa 2004-04-11 devnull .I Mapfile
69 bf8a59fa 2004-04-11 devnull adds the segments found in
72 bf8a59fa 2004-04-11 devnull .IR map .
75 bf8a59fa 2004-04-11 devnull is an executable file, there are typically three segments:
76 bf8a59fa 2004-04-11 devnull .IR text ,
77 bf8a59fa 2004-04-11 devnull .IR data ,
78 bf8a59fa 2004-04-11 devnull and a zero-backed
79 bf8a59fa 2004-04-11 devnull .IR bss .
82 bf8a59fa 2004-04-11 devnull is a dynamic shared library, its segments are relocated by
84 bf8a59fa 2004-04-11 devnull before being mapping.
88 bf8a59fa 2004-04-11 devnull is a core file, there is one segment named
90 bf8a59fa 2004-04-11 devnull for each contiguous section of memory recorded in the core file.
91 bf8a59fa 2004-04-11 devnull There are often quite a few of these, as most operating systems
92 bf8a59fa 2004-04-11 devnull omit clean memory pages when writing core files
93 bf8a59fa 2004-04-11 devnull (Mac OS X is the only exception among the supported systems).
94 bf8a59fa 2004-04-11 devnull Because core files have such holes, it is typically necessary to
95 bf8a59fa 2004-04-11 devnull construct the core map by calling
96 bf8a59fa 2004-04-11 devnull .I mapfile
97 bf8a59fa 2004-04-11 devnull on the executable and then calling it again on the core file.
98 bf8a59fa 2004-04-11 devnull Newly-added segments are mapped on top of existing segments,
99 bf8a59fa 2004-04-11 devnull so this arrangement will use the core file for the segments it contains
100 bf8a59fa 2004-04-11 devnull but fall back to the executable for the rest.
102 058b0118 2005-01-03 devnull .I Unmapfile
103 058b0118 2005-01-03 devnull removes the mappings in
105 058b0118 2005-01-03 devnull corresponding to
106 058b0118 2005-01-03 devnull .IR hdr .
108 bf8a59fa 2004-04-11 devnull .I Mapproc
109 bf8a59fa 2004-04-11 devnull attaches to a running program and adds its segments to the given map.
110 bf8a59fa 2004-04-11 devnull It adds one segment for each contiguous section of
111 bf8a59fa 2004-04-11 devnull mapped memory.
112 bf8a59fa 2004-04-11 devnull On systems where this information cannot be determined, it adds
113 bf8a59fa 2004-04-11 devnull a single segment covering the entire address space.
114 bf8a59fa 2004-04-11 devnull Accessing areas of this segment that are actually not mapped
115 bf8a59fa 2004-04-11 devnull in the process address space will cause the get/put routines to return errors.
117 058b0118 2005-01-03 devnull .I Unmapproc
118 058b0118 2005-01-03 devnull removes the mappings in
120 058b0118 2005-01-03 devnull corresponding to
121 058b0118 2005-01-03 devnull .IR pid .
122 bf8a59fa 2004-04-11 devnull .I Detachproc
123 058b0118 2005-01-03 devnull detaches from all previously attached processes.
125 bf8a59fa 2004-04-11 devnull .I Ctlproc
126 bf8a59fa 2004-04-11 devnull manipulates the process with id
128 bf8a59fa 2004-04-11 devnull according to the message
129 bf8a59fa 2004-04-11 devnull .IR msg .
130 bf8a59fa 2004-04-11 devnull Valid messages include:
133 bf8a59fa 2004-04-11 devnull terminate the process
135 bf8a59fa 2004-04-11 devnull .B startstop
136 bf8a59fa 2004-04-11 devnull start the process and wait for it to stop
138 bf8a59fa 2004-04-11 devnull .B sysstop
139 bf8a59fa 2004-04-11 devnull arrange for the process to stop at its next system call,
140 bf8a59fa 2004-04-11 devnull start the process, and then wait for it to stop
142 bf8a59fa 2004-04-11 devnull .B waitstop
143 bf8a59fa 2004-04-11 devnull wait for the process to stop
145 bf8a59fa 2004-04-11 devnull .B start
146 bf8a59fa 2004-04-11 devnull start the process
149 bf8a59fa 2004-04-11 devnull .I Procnotes
151 bf8a59fa 2004-04-11 devnull .BI * notes
152 bf8a59fa 2004-04-11 devnull with a pointer to an array of strings
153 bf8a59fa 2004-04-11 devnull representing pending notes waiting
154 bf8a59fa 2004-04-11 devnull for the process.
155 bf8a59fa 2004-04-11 devnull (On Unix, these notes are textual descriptions
156 bf8a59fa 2004-04-11 devnull of any pending signals.)
157 bf8a59fa 2004-04-11 devnull .I Procnotes
158 bf8a59fa 2004-04-11 devnull returns the number of pending notes.
159 bf8a59fa 2004-04-11 devnull The memory at
160 bf8a59fa 2004-04-11 devnull .BI * notes
161 bf8a59fa 2004-04-11 devnull should be freed via
164 058b0118 2005-01-03 devnull .IR malloc (3))
165 bf8a59fa 2004-04-11 devnull when no longer needed.
166 bf8a59fa 2004-04-11 devnull .SH SOURCE
167 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libmach
168 bf8a59fa 2004-04-11 devnull .SH "SEE ALSO"
169 bf8a59fa 2004-04-11 devnull .IR mach (3),
170 bf8a59fa 2004-04-11 devnull .IR mach-map (3)