object.3 5.3 KB

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