mach 7.8 KB

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