1
0

mach 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399
  1. .TH MACH 2
  2. .SH NAME
  3. crackhdr, machbytype, machbyname, newmap, setmap, findseg, unusemap,
  4. loadmap, attachproc, get1, get2, get4, get8, geta, put1, put2, put4, put8, puta,
  5. beswab, beswal, beswav, leswab, leswal, leswav \- machine-independent access to executable files
  6. .SH SYNOPSIS
  7. .B #include <u.h>
  8. .br
  9. .B #include <libc.h>
  10. .br
  11. .B #include <bio.h>
  12. .br
  13. .B #include <mach.h>
  14. .PP
  15. .ta \w'\fLmachines 'u
  16. .B
  17. int crackhdr(int fd, Fhdr *fp)
  18. .PP
  19. .B
  20. void machbytype(int type)
  21. .PP
  22. .B
  23. int machbyname(char *name)
  24. .PP
  25. .B
  26. Map *newmap(Map *map, int n)
  27. .PP
  28. .B
  29. int setmap(Map *map, int fd, ulong base, ulong end,
  30. .PP
  31. .B
  32. ulong foffset, char *name)
  33. .PP
  34. .B
  35. int findseg(Map *map, char *name)
  36. .PP
  37. .B
  38. void unusemap(Map *map, int seg)
  39. .PP
  40. .B
  41. Map *loadmap(Map *map, int fd, Fhdr *fp)
  42. .PP
  43. .B
  44. Map *attachproc(int pid, int kflag, int corefd, Fhdr *fp)
  45. .PP
  46. .B
  47. int get1(Map *map, ulong addr, uchar *buf, int n)
  48. .PP
  49. .B
  50. int get2(Map *map, ulong addr, ushort *val)
  51. .PP
  52. .B
  53. int get4(Map *map, ulong addr, long *val)
  54. .PP
  55. .B
  56. int get8(Map *map, ulong addr, vlong *val)
  57. .PP
  58. .B
  59. int geta(Map *map, uvlong addr, uvlong *val)
  60. .PP
  61. .B
  62. int put1(Map *map, ulong addr, uchar *buf, int n)
  63. .PP
  64. .B
  65. int put2(Map *map, ulong addr, ushort val)
  66. .PP
  67. .B
  68. int put4(Map *map, ulong addr, long val)
  69. .PP
  70. .B
  71. int put8(Map *map, ulong addr, vlong val)
  72. .PP
  73. .B
  74. int puta(Map *map, uvlong addr, uvlong val)
  75. .PP
  76. .B
  77. ushort beswab(ushort val)
  78. .PP
  79. .B
  80. long beswal(long val)
  81. .PP
  82. .B
  83. long beswav(vlong val)
  84. .PP
  85. .B
  86. ushort leswab(ushort val)
  87. .PP
  88. .B
  89. long leswal(long val)
  90. .PP
  91. .B
  92. long leswav(vlong val)
  93. .PP
  94. .B
  95. extern Mach mach;
  96. .PP
  97. .B
  98. extern Machdata machdata;
  99. .SH DESCRIPTION
  100. These functions provide
  101. a processor-independent interface for accessing
  102. the executable files or executing images of all
  103. architectures.
  104. Related library functions described in
  105. .IR symbol (2)
  106. and
  107. .IR object (2)
  108. provide similar access to symbol tables and object files.
  109. .PP
  110. An
  111. .I executable
  112. is a file containing an executable program or the
  113. .B text
  114. file of the
  115. .B /proc
  116. file system associated with an executing process as
  117. described in
  118. .IR proc (3).
  119. After opening an executable, an application
  120. invokes a library function which parses the
  121. file header,
  122. determines the target architecture and
  123. initializes data structures with parameters
  124. and pointers to functions appropriate for
  125. that architecture. Next, the application
  126. invokes functions to construct one or more
  127. .IR maps ,
  128. data structures that translate references
  129. in the address space of the executable
  130. to offsets in the file. Each
  131. .I map
  132. comprises one or more
  133. .BR segments ,
  134. each associating a non-overlapping range of
  135. memory addresses with a logical section of
  136. the executable.
  137. Other library functions then use a map
  138. and the architecture-specific data structures
  139. to provide a generic interface to the
  140. processor-dependent data.
  141. .PP
  142. .I Crackhdr
  143. interprets the header of the executable
  144. associated with
  145. the open file descriptor
  146. .IR fd .
  147. It loads the data structure
  148. .I fp
  149. with a machine-independent description
  150. of the header information and
  151. points global variable
  152. .I mach
  153. to the
  154. .B Mach
  155. data structure containing processor-dependent parameters
  156. of the target architecture.
  157. .PP
  158. .I Machbytype
  159. selects architecture-specific data structures and parameter
  160. values based on
  161. the code stored in the
  162. field named
  163. .I type
  164. in the
  165. .B Fhdr
  166. data structure.
  167. .I Machbyname
  168. performs the same selection based
  169. on the name of a processor class; see
  170. .IR 8c (1)
  171. for a list of valid names.
  172. Both functions point global variables
  173. .I mach
  174. and
  175. .I machdata
  176. to the
  177. .I Mach
  178. and
  179. .I Machdata
  180. data structures appropriate for the
  181. target architecture and load global variable
  182. .I asstype
  183. with the proper disassembler type code.
  184. .PP
  185. .I Newmap
  186. creates an empty map with
  187. .I n
  188. segments.
  189. If
  190. .I map
  191. is zero, the new map is dynamically
  192. allocated, otherwise it is assumed to
  193. point to an existing dynamically allocated map whose
  194. size is adjusted, as necessary.
  195. A zero return value indicates an allocation error.
  196. .PP
  197. .I Setmap
  198. loads the first unused segment in
  199. .I map
  200. with the
  201. segment mapping parameters.
  202. .I Fd
  203. is an open file descriptor associated with
  204. an executable.
  205. .I Base
  206. and
  207. .I end
  208. contain the lowest and highest virtual addresses
  209. mapped by the segment.
  210. .I Foffset
  211. is the offset to the start of the segment in the file.
  212. .I Name
  213. is a name to be attached to the segment.
  214. .PP
  215. .I Findseg
  216. returns the index of the the
  217. segment named
  218. .I name
  219. in
  220. .IR map .
  221. A return of -1 indicates that no
  222. segment matches
  223. .IR name .
  224. .PP
  225. .I Unusemap
  226. marks segment number
  227. .I seg
  228. in map
  229. .I map
  230. unused. Other
  231. segments in the map remain unaffected.
  232. .PP
  233. .I Loadmap
  234. initializes a default map containing
  235. segments named `text' and `data' that
  236. map the instruction and data segments
  237. of the executable described in the
  238. .B Fhdr
  239. structure pointed to by
  240. .IR fp .
  241. Usually that structure was loaded by
  242. .IR crackhdr
  243. and can be passed to this function without
  244. modification.
  245. If
  246. .I map
  247. is non-zero, that map, which must have been
  248. dynamically allocated, is resized to contain two segments;
  249. otherwise a new map is allocated.
  250. This function returns zero if allocation fails.
  251. .I Loadmap
  252. is usually used to build a map for accessing
  253. a static executable, for example, an executable
  254. program file.
  255. .PP
  256. .I Attachproc
  257. constructs a map for accessing a
  258. running process. It
  259. returns the address of a
  260. .I Map
  261. containing segments mapping the
  262. address space of the running process
  263. whose process ID is
  264. .BR pid .
  265. If
  266. .B kflag
  267. is non-zero, the process is assumed to be
  268. a kernel process.
  269. .B Corefd
  270. is an file descriptor opened to
  271. .BR /proc/\fIpid\fP/mem .
  272. .B Fp
  273. points to the
  274. .I Fhdr
  275. structure describing the header
  276. of the executable. For most architectures
  277. the resulting
  278. .I Map
  279. contains four segments named `text', `data',
  280. `regs' and `fpregs'. The latter two provide access to
  281. the general and floating point registers, respectively.
  282. If the executable is a kernel process (indicated by a
  283. non-zero
  284. .B kflag
  285. argument), the data segment extends to the maximum
  286. supported address, currently 0xffffffff, and the
  287. register sets are read-only. In user-level programs,
  288. the data segment extends to the
  289. top of the stack or 0x7fffffff if the stack top
  290. cannot be found, and the register sets are readable
  291. and writable.
  292. .I Attachproc
  293. returns zero if it is unable to build the map
  294. for the specified process.
  295. .PP
  296. .IR Get1 ,
  297. .IR get2 ,
  298. .IR get4 ,
  299. and
  300. .I get8
  301. retrieve the data stored at address
  302. .I addr
  303. in the executable associated
  304. with
  305. .IR map .
  306. .I Get1
  307. retrieves
  308. .I n
  309. bytes of data beginning at
  310. .I addr
  311. into
  312. .IR buf .
  313. .IR Get2 ,
  314. .I get4
  315. and
  316. .I get8
  317. retrieve 16-bit, 32-bit and 64-bit values respectively,
  318. into the location pointed to by
  319. .IR val .
  320. The value is byte-swapped if the source
  321. byte order differs from that of the current architecture.
  322. This implies that the value returned by
  323. .IR get2 ,
  324. .IR get4 ,
  325. and
  326. .I get8
  327. may not be the same as the byte sequences
  328. returned by
  329. .I get1
  330. when
  331. .I n
  332. is two, four or eight; the former may be byte-swapped, the
  333. latter reflects the byte order of the target architecture.
  334. If the file descriptor associated with the applicable segment in
  335. .I map
  336. is negative, the address itself is placed in the
  337. return location. These functions return the number
  338. of bytes read or a \-1 when there is an error.
  339. .PP
  340. .IR Put1 ,
  341. .IR put2 ,
  342. .IR put4 ,
  343. and
  344. .I put8
  345. write to
  346. the executable associated with
  347. .IR map .
  348. The address is translated using the
  349. map parameters and multi-byte quantities are
  350. byte-swapped, if necessary, before they are written.
  351. .I Put1
  352. transfers
  353. .I n
  354. bytes stored at
  355. .IR buf ;
  356. .IR put2 ,
  357. .IR put4 ,
  358. and
  359. .I put8
  360. write the 16-bit, 32-bit or 64-bit quantity contained in
  361. .IR val ,
  362. respectively. The number of bytes transferred is returned.
  363. A \-1 return value indicates an error.
  364. .PP
  365. .IR Beswab ,
  366. .IR beswal ,
  367. and
  368. .I beswav
  369. return the
  370. .BR ushort ,
  371. .BR long ,
  372. and
  373. .B vlong
  374. big-endian representation of
  375. .IR val ,
  376. respectively.
  377. .IR Leswab ,
  378. .IR leswal ,
  379. and
  380. .I leswav
  381. return the little-endian representation of the
  382. .BR ushort ,
  383. .BR long ,
  384. and
  385. .B vlong
  386. contained in
  387. .IR val .
  388. .SH SOURCE
  389. .B /sys/src/libmach
  390. .SH "SEE ALSO"
  391. .IR 8c (1),
  392. .IR symbol (2),
  393. .IR object (2),
  394. .IR errstr (2),
  395. .IR proc (3),
  396. .IR a.out (6)
  397. .SH DIAGNOSTICS
  398. These routines set
  399. .IR errstr .