sys/man/2/object

   1 .TH OBJECT 2
   2 .SH NAME
   3 objtype, readobj, objtraverse, isar, nextar, readar \- object file interpretation functions
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .br
   9 .B #include <bio.h>
  10 .br
  11 .B #include <mach.h>
  12 .PP
  13 .ta \w'\fLmachines 'u
  14 .B
  15 int  objtype(Biobuf *bp, char **name)
  16 .PP
  17 .B
  18 int  readobj(Biobuf *bp, int objtype)
  19 .PP
  20 .B
  21 void  objtraverse(void(*)(Sym*, void*), void*)
  22 .PP
  23 .B
  24 int isar(Biobuf *bp)
  25 .PP
  26 .B
  27 int nextar(Biobuf *bp, int offset, char *buf)
  28 .PP
  29 .B
  30 int readar(Biobuf *bp, int objtype, vlong end, int doautos)
  31 .SH DESCRIPTION
  32 These functions provide machine-independent access to object files
  33 in a directory or an archive.
  34 .IR Mach (2)
  35 and
  36 .IR symbol (2)
  37 describe additional library functions
  38 for interpreting executable files and executing images.
  39 .PP
  40 Object files contain no formal symbol table; instead, references
  41 to symbols must be extracted from the encoded object representation
  42 and resolved.  The resulting symbol information is loaded
  43 into a dummy symbol table where it is available for processing by an
  44 application.  The organization of the dummy symbol
  45 table is identical
  46 to that produced by the loader and described in
  47 .IR symbol (2)
  48 and
  49 .IR a.out (6):
  50 a vector of
  51 .B Sym
  52 data structures defining the name, type and relative offset of
  53 each symbol.
  54 .PP
  55 .I Objtype
  56 reads the header at the current position of the
  57 file associated with
  58 .I bp
  59 (see
  60 .IR Bio (2))
  61 to see if it is an intermediate object file.
  62 If it is, a code indicating the architecture type of the file
  63 is returned and the second argument, if it is non-zero,
  64 is set pointing to a string describing the type of the file.
  65 If the header does not indicate an object file,
  66 \-1 is returned.
  67 The header may be at the start of an object
  68 file or at the beginning of an archive member.  The
  69 file is rewound to its starting
  70 position after decoding the header.
  71 .PP
  72 .I Readobj
  73 constructs a symbol table for the object file associated with
  74 .IR bp .
  75 The second argument contains the type code produced by
  76 function
  77 .IR objtype .
  78 The file must be positioned at the start of the object file.
  79 Each invocation of
  80 .I readobj
  81 destroys the symbol definitions for any previous file.
  82 .PP
  83 .I Objtraverse
  84 scans the symbol table previously built by
  85 .I readobj
  86 or
  87 .IR readar  .
  88 .I Objtraverse
  89 requires two arguments:
  90 the address of a call-back function and a
  91 generic pointer.  The call-back function
  92 is invoked once for each symbol in the symbol table with
  93 the address of a
  94 .I Sym
  95 data structure as the first argument and the
  96 generic pointer as the second.
  97 .PP
  98 .I Isar
  99 reads the header at the current point in the file
 100 associated with
 101 .I bp
 102 and returns 1 if it is an archive or zero otherwise.
 103 The file is positioned at the end of the archive
 104 header and at the beginning of the first member of the archive.
 105 .PP
 106 .I Nextar
 107 extracts information describing the archive member stored
 108 at
 109 .I offset
 110 in the file associated with
 111 .IR bp .
 112 If the header describing the member can be
 113 extracted and decoded, the size of the member is
 114 returned.  Adding this value to
 115 .I offset
 116 yields the offset of the beginning of the next member
 117 in the archive.  On return the input file is positioned
 118 at the end of the member header
 119 and the name of the member is stored in
 120 .IR buf ,
 121 a buffer of
 122 .B SARNAME
 123 characters.
 124 If there are no more members,
 125 .I nextar
 126 returns zero; a negative return indicates a missing
 127 or malformed header.
 128 .PP
 129 .I Readar
 130 constructs the symbol table of the object file stored
 131 at the current position in the archive associated with
 132 .IR bp .
 133 This function operates exactly as
 134 .IR readobj ;
 135 the only difference is the extra argument,
 136 .IR end ,
 137 specifying the offset to the beginning of the
 138 next member in the archive.
 139 .I Readar
 140 leaves the file positioned at that point.
 141 .SH SOURCE
 142 .B /sys/src/libmach
 143 .SH "SEE ALSO"
 144 .IR mach (2),
 145 .IR symbol (2),
 146 .IR bio (2),
 147 .IR a.out (6)
 148 .SH DIAGNOSTICS
 149 These routines set
 150 .IR errstr .