mach-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)