object.3 5.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316
  1. .TH OBJECT 3 "$Revision$"
  2. .ad
  3. .SH NAME
  4. wr_open, wr_close, wr_ohead, wr_sect, wr_outsect, wr_emit, wr_putc, wr_relo,
  5. wr_name, wr_string, wr_arhdr, wr_ranlib, wr_int2, wr_long, wr_bytes,
  6. rd_open, rd_fdopen, rd_close, rd_ohead, rd_sect, rd_outsect,
  7. rd_emit, rd_relo, rd_rew_relo, rd_name, rd_string, rd_arhdr, rd_ranlib,
  8. rd_int2, rd_unsigned2, rd_long, rd_bytes, rd_fd\ \-\ routines to read
  9. and write ACK-object files and libraries
  10. .SH SYNOPSIS
  11. .B #include <out.h>
  12. .br
  13. .B #include <arch.h>
  14. .br
  15. .B #include <ranlib.h>
  16. .br
  17. .B #include <object.h>
  18. .PP
  19. .B int wr_open(filename)
  20. .br
  21. .B char *filename;
  22. .PP
  23. .B void wr_close()
  24. .PP
  25. .B void wr_ohead(head)
  26. .br
  27. .B struct outhead *head;
  28. .PP
  29. .B void wr_sect(sect, cnt)
  30. .br
  31. .B struct outsect *sect;
  32. .br
  33. .B unsigned int cnt;
  34. .PP
  35. .B void wr_outsect(sectionnr)
  36. .br
  37. .B int sectionnr;
  38. .PP
  39. .B void wr_emit(emit, cnt)
  40. .br
  41. .B char *emit;
  42. .br
  43. .B long cnt;
  44. .PP
  45. .B void wr_putc(ch)
  46. .PP
  47. .B void wr_relo(relo, cnt)
  48. .br
  49. .B struct outrelo *relo;
  50. .br
  51. .B unsigned int cnt;
  52. .PP
  53. .B void wr_name(name, cnt)
  54. .br
  55. .B struct outname *name;
  56. .br
  57. .B unsigned int cnt;
  58. .PP
  59. .B void wr_string(stringaddr, cnt)
  60. .br
  61. .B char *stringaddr;
  62. .br
  63. .B long cnt;
  64. .PP
  65. .B void wr_arhdr(fd, arhdr)
  66. .br
  67. .B struct ar_hdr *arhdr;
  68. .PP
  69. .B void wr_ranlib(fd, ran, cnt)
  70. .br
  71. .B struct ranlib *ran;
  72. .br
  73. .B long cnt;
  74. .PP
  75. .B void wr_int2(fd, i)
  76. .PP
  77. .B void wr_long(fd, l)
  78. .br
  79. .B long l;
  80. .PP
  81. .B void wr_bytes(fd, buf, l)
  82. .br
  83. .B char *buf;
  84. .br
  85. .B long l;
  86. .PP
  87. .B int rd_open(filename)
  88. .br
  89. .B char *filename;
  90. .PP
  91. .B int rd_fdopen(fd)
  92. .PP
  93. .B void rd_close()
  94. .PP
  95. .B void rd_ohead(head)
  96. .br
  97. .B struct outhead *head;
  98. .PP
  99. .B void rd_sect(sect, cnt)
  100. .br
  101. .B struct outsect *sect;
  102. .br
  103. .B unsigned int cnt;
  104. .PP
  105. .B void rd_outsect(sectionnr)
  106. .br
  107. .B int sectionnr;
  108. .PP
  109. .B void rd_emit(emit, cnt)
  110. .br
  111. .B char *emit;
  112. .br
  113. .B long cnt;
  114. .PP
  115. .B void rd_relo(relo, cnt)
  116. .br
  117. .B struct outrelo *relo;
  118. .br
  119. .B unsigned int cnt;
  120. .PP
  121. .B void rd_rew_relo(head)
  122. .br
  123. .B struct outhead *head;
  124. .PP
  125. .B void rd_name(name, cnt)
  126. .br
  127. .B struct outname *name;
  128. .br
  129. .B unsigned int cnt;
  130. .PP
  131. .B void rd_string(stringaddr, cnt)
  132. .br
  133. .B char *stringaddr;
  134. .br
  135. .B long cnt;
  136. .PP
  137. .B int rd_arhdr(fd, arhdr)
  138. .br
  139. .B struct ar_hdr *arhdr;
  140. .PP
  141. .B void rd_ranlib(fd, ran, cnt)
  142. .br
  143. .B struct ranlib *ran;
  144. .br
  145. .B long cnt;
  146. .PP
  147. .B int rd_int2(fd)
  148. .PP
  149. .B unsigned int rd_unsigned2(fd)
  150. .PP
  151. .B long rd_long(fd)
  152. .PP
  153. .B void rd_bytes(fd, buf, l)
  154. .br
  155. .B char *buf;
  156. .br
  157. .B long l;
  158. .PP
  159. .B int rd_fd()
  160. .SH DESCRIPTION
  161. These routines come in handy when reading or writing ACK-object files
  162. or libraries. No checking is performed.
  163. .PP
  164. .I Wr_open
  165. opens the file
  166. .I filename
  167. for writing and initializes some of this modules local variables.
  168. It must be called before writing parts of the object file.
  169. It returns 1 if it succeeds, 0 if it fails.
  170. .PP
  171. .I Wr_close
  172. closes the object file. Don't forget to call it, because it might
  173. flush internal buffers.
  174. .PP
  175. .I Wr_ohead
  176. writes the
  177. .I head
  178. header structure.
  179. This routine must be called before the routines to write the other
  180. parts.
  181. .PP
  182. .I Wr_sect
  183. writes
  184. .I cnt
  185. section headers, starting at
  186. .IB sect .
  187. Before writing a section, its section header must be written.
  188. .PP
  189. .I Wr_outsect
  190. indicates that the next section to be written is
  191. .IB sectionnr .
  192. This routine can be used to switch between sections.
  193. .PP
  194. .I Wr_emit
  195. writes
  196. .I cnt
  197. bytes, starting at
  198. .IB emit ,
  199. of the current section.
  200. .PP
  201. .I Wr_putc
  202. adds character
  203. .I ch
  204. to the current section.
  205. .PP
  206. .I Wr_relo
  207. writes
  208. .I cnt
  209. outrelo structures, indicated by
  210. .IB relo ,
  211. in the relocation information part of the object file.
  212. .PP
  213. .I Wr_name
  214. writes
  215. .I cnt
  216. outname structures, indicated by
  217. .IB name ,
  218. in the name-table part of the object file.
  219. .PP
  220. .I Wr_string
  221. writes
  222. .I cnt
  223. bytes, indicated by
  224. .IB stringaddr ,
  225. in the string table part of the object file.
  226. .PP
  227. The next few routines can be used independantly:
  228. .I Wr_arhdr
  229. writes the archive member header
  230. .I arhdr
  231. to file descriptor
  232. .IB fd .
  233. .PP
  234. .I Wr_ranlib
  235. writes
  236. .I cnt
  237. ranlib structures, indicated by
  238. .IB ran ,
  239. to file descriptor
  240. .IB fd.
  241. .PP
  242. .I Wr_int2
  243. writes a 2-byte integer
  244. .I i
  245. to file descriptor
  246. .IB fd ,
  247. low order byte first.
  248. .PP
  249. .I Wr_long
  250. writes a 4-byte integer
  251. .I l
  252. to file descriptor
  253. .IB fd ,
  254. low order word first, low order byte first.
  255. .PP
  256. .I Wr_bytes
  257. writes
  258. .I l
  259. bytes from
  260. .I buf
  261. to file descriptor
  262. .IB fd .
  263. .PP
  264. Most of the
  265. .I rd_
  266. routines are the opposite of the
  267. .I wr_
  268. routines. However, a few of them deserve special mentioning:
  269. .PP
  270. .I Rd_fdopen
  271. initialises for reading an "object file" from file descriptor
  272. .IB fd ,
  273. at its current position.
  274. This is useful for reading an object that resides in an archive.
  275. It returns 1 if it succeeds, 0 otherwise.
  276. When using this entry point for reading,
  277. .I rd_close
  278. does not have to be called.
  279. .PP
  280. .I Rd_rew_relo
  281. rewinds the relocation part, so that it can be read again.
  282. \fILed\fR(6) sometimes needs this.
  283. .PP
  284. .I Rd_unsigned2
  285. reads two bytes from file descriptor
  286. .I fd
  287. and interpretes them as an unsigned integer.
  288. .PP
  289. .I Rd_arhdr
  290. returns 1 if a header was read, and 0 on end-of-file.
  291. .PP
  292. When using any of the reading routines, a routine
  293. named
  294. .I rd_fatal
  295. must be defined.
  296. It is called when a read fails, and is not supposed to return.
  297. Likewise, a routine
  298. .I wr_fatal
  299. must be defined when using any of the writing routines.
  300. .SH FILES
  301. ~em/h/out.h
  302. .br
  303. ~em/h/arch.h
  304. .br
  305. ~em/h/ranlib.h
  306. .br
  307. ~em/modules/lib/libobject.a: the library in which these routines reside
  308. .SH "SEE ALSO"
  309. ack.out(5), arch(1), aal(1)
  310. .SH DIAGNOSTICS
  311. The routines
  312. .IB wr_open ,
  313. .IB rd_open ,
  314. and
  315. .I rd_fdopen
  316. return 0 if they fail, and 1 if they succeed.