modules/src/object/object.3

   1 .TH OBJECT 3 "$Revision: 1.11 $"
   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.