1 bf8a59fa 2004-04-11 devnull .TH MACH-FILE 3
3 bf8a59fa 2004-04-11 devnull crackhdr, uncrackhdr, mapfile, mapproc, 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 bf8a59fa 2004-04-11 devnull int mapfile(Map *map, ulong base, Fhdr *hdr)
21 bf8a59fa 2004-04-11 devnull int mapproc(Map *map, int pid)
23 bf8a59fa 2004-04-11 devnull int detachproc(int pid)
25 bf8a59fa 2004-04-11 devnull int ctlproc(int pid, char *msg)
27 bf8a59fa 2004-04-11 devnull int procnotes(int pid, char ***notes)
28 bf8a59fa 2004-04-11 devnull .SH DESCRIPTION
29 bf8a59fa 2004-04-11 devnull These functions parse executable files and
30 bf8a59fa 2004-04-11 devnull provide access to those files and to running processes.
32 bf8a59fa 2004-04-11 devnull .I Crackhdr
33 bf8a59fa 2004-04-11 devnull opens and parses the named executable file.
34 bf8a59fa 2004-04-11 devnull The returned data structure
36 bf8a59fa 2004-04-11 devnull is initialized with a machine-independent description
37 bf8a59fa 2004-04-11 devnull of the header information. The following fields are the
38 bf8a59fa 2004-04-11 devnull most commonly used:
41 bf8a59fa 2004-04-11 devnull a pointer to the
43 bf8a59fa 2004-04-11 devnull structure for the target architecture
46 bf8a59fa 2004-04-11 devnull the name of the target architecture
49 bf8a59fa 2004-04-11 devnull a description of the kind of file
50 bf8a59fa 2004-04-11 devnull (e.g., executable, core dump)
53 bf8a59fa 2004-04-11 devnull a description of the application binary interface
54 bf8a59fa 2004-04-11 devnull this file uses; typically it is the name of an operating system
56 bf8a59fa 2004-04-11 devnull If the global variable
59 bf8a59fa 2004-04-11 devnull .I crackhdr
60 bf8a59fa 2004-04-11 devnull points it to the same
62 bf8a59fa 2004-04-11 devnull structure.
64 bf8a59fa 2004-04-11 devnull .I Mapfile
65 bf8a59fa 2004-04-11 devnull adds the segments found in
68 bf8a59fa 2004-04-11 devnull .IR map .
71 bf8a59fa 2004-04-11 devnull is an executable file, there are typically three segments:
72 bf8a59fa 2004-04-11 devnull .IR text ,
73 bf8a59fa 2004-04-11 devnull .IR data ,
74 bf8a59fa 2004-04-11 devnull and a zero-backed
75 bf8a59fa 2004-04-11 devnull .IR bss .
78 bf8a59fa 2004-04-11 devnull is a dynamic shared library, its segments are relocated by
80 bf8a59fa 2004-04-11 devnull before being mapping.
84 bf8a59fa 2004-04-11 devnull is a core file, there is one segment named
86 bf8a59fa 2004-04-11 devnull for each contiguous section of memory recorded in the core file.
87 bf8a59fa 2004-04-11 devnull There are often quite a few of these, as most operating systems
88 bf8a59fa 2004-04-11 devnull omit clean memory pages when writing core files
89 bf8a59fa 2004-04-11 devnull (Mac OS X is the only exception among the supported systems).
90 bf8a59fa 2004-04-11 devnull Because core files have such holes, it is typically necessary to
91 bf8a59fa 2004-04-11 devnull construct the core map by calling
92 bf8a59fa 2004-04-11 devnull .I mapfile
93 bf8a59fa 2004-04-11 devnull on the executable and then calling it again on the core file.
94 bf8a59fa 2004-04-11 devnull Newly-added segments are mapped on top of existing segments,
95 bf8a59fa 2004-04-11 devnull so this arrangement will use the core file for the segments it contains
96 bf8a59fa 2004-04-11 devnull but fall back to the executable for the rest.
98 bf8a59fa 2004-04-11 devnull .I Mapproc
99 bf8a59fa 2004-04-11 devnull attaches to a running program and adds its segments to the given map.
100 bf8a59fa 2004-04-11 devnull It adds one segment for each contiguous section of
101 bf8a59fa 2004-04-11 devnull mapped memory.
102 bf8a59fa 2004-04-11 devnull On systems where this information cannot be determined, it adds
103 bf8a59fa 2004-04-11 devnull a single segment covering the entire address space.
104 bf8a59fa 2004-04-11 devnull Accessing areas of this segment that are actually not mapped
105 bf8a59fa 2004-04-11 devnull in the process address space will cause the get/put routines to return errors.
106 bf8a59fa 2004-04-11 devnull .I Detachproc
107 bf8a59fa 2004-04-11 devnull detaches from a previously-attached program.
109 bf8a59fa 2004-04-11 devnull .I Ctlproc
110 bf8a59fa 2004-04-11 devnull manipulates the process with id
112 bf8a59fa 2004-04-11 devnull according to the message
113 bf8a59fa 2004-04-11 devnull .IR msg .
114 bf8a59fa 2004-04-11 devnull Valid messages include:
117 bf8a59fa 2004-04-11 devnull terminate the process
119 bf8a59fa 2004-04-11 devnull .B startstop
120 bf8a59fa 2004-04-11 devnull start the process and wait for it to stop
122 bf8a59fa 2004-04-11 devnull .B sysstop
123 bf8a59fa 2004-04-11 devnull arrange for the process to stop at its next system call,
124 bf8a59fa 2004-04-11 devnull start the process, and then wait for it to stop
126 bf8a59fa 2004-04-11 devnull .B waitstop
127 bf8a59fa 2004-04-11 devnull wait for the process to stop
129 bf8a59fa 2004-04-11 devnull .B start
130 bf8a59fa 2004-04-11 devnull start the process
133 bf8a59fa 2004-04-11 devnull .I Procnotes
135 bf8a59fa 2004-04-11 devnull .BI * notes
136 bf8a59fa 2004-04-11 devnull with a pointer to an array of strings
137 bf8a59fa 2004-04-11 devnull representing pending notes waiting
138 bf8a59fa 2004-04-11 devnull for the process.
139 bf8a59fa 2004-04-11 devnull (On Unix, these notes are textual descriptions
140 bf8a59fa 2004-04-11 devnull of any pending signals.)
141 bf8a59fa 2004-04-11 devnull .I Procnotes
142 bf8a59fa 2004-04-11 devnull returns the number of pending notes.
143 bf8a59fa 2004-04-11 devnull The memory at
144 bf8a59fa 2004-04-11 devnull .BI * notes
145 bf8a59fa 2004-04-11 devnull should be freed via
146 bf8a59fa 2004-04-11 devnull .IR free (3)
147 bf8a59fa 2004-04-11 devnull when no longer needed.
148 bf8a59fa 2004-04-11 devnull .SH SOURCE
149 b5fdffee 2004-04-19 devnull .B /usr/local/plan9/src/libmach
150 bf8a59fa 2004-04-11 devnull .SH "SEE ALSO"
151 bf8a59fa 2004-04-11 devnull .IR mach (3),
152 bf8a59fa 2004-04-11 devnull .IR mach-map (3)
