OBJECT(2)                                               OBJECT(2)

     NAME
          objtype, readobj, objtraverse, isar, nextar, readar - object
          file interpretation functions

     SYNOPSIS
          #include <u.h>
          #include <libc.h>
          #include <bio.h>
          #include <mach.h>

          int  objtype(Biobuf *bp, char **name)

          int  readobj(Biobuf *bp, int objtype)

          void  objtraverse(void(*)(Sym*, void*), void*)

          int isar(Biobuf *bp)

          int nextar(Biobuf *bp, int offset, char *buf)

          int readar(Biobuf *bp, int objtype, vlong end, int doautos)

     DESCRIPTION
          These functions provide machine-independent access to object
          files in a directory or an archive.  Mach(2) and symbol(2)
          describe additional library functions for interpreting exe-
          cutable files and executing images.

          Object files contain no formal symbol table; instead, refer-
          ences to symbols must be extracted from the encoded object
          representation and resolved.  The resulting symbol informa-
          tion is loaded into a dummy symbol table where it is avail-
          able for processing by an application.  The organization of
          the dummy symbol table is identical to that produced by the
          loader and described in symbol(2) and a.out(6): a vector of
          Sym data structures defining the name, type and relative
          offset of each symbol.

          Objtype reads the header at the current position of the file
          associated with bp (see Bio(2)) to see if it is an interme-
          diate object file.  If it is, a code indicating the archi-
          tecture type of the file is returned and the second argu-
          ment, if it is non-zero, is set pointing to a string
          describing the type of the file.  If the header does not
          indicate an object file, -1 is returned.  The header may be
          at the start of an object file or at the beginning of an
          archive member.  The file is rewound to its starting posi-
          tion after decoding the header.

          Readobj constructs a symbol table for the object file

     Page 1                       Plan 9             (printed 3/19/24)

     OBJECT(2)                                               OBJECT(2)

          associated with bp. The second argument contains the type
          code produced by function objtype. The file must be posi-
          tioned at the start of the object file.  Each invocation of
          readobj destroys the symbol definitions for any previous
          file.

          Objtraverse scans the symbol table previously built by
          readobj or readar. Objtraverse requires two arguments: the
          address of a call-back function and a generic pointer.  The
          call-back function is invoked once for each symbol in the
          symbol table with the address of a Sym data structure as the
          first argument and the generic pointer as the second.

          Isar reads the header at the current point in the file asso-
          ciated with bp and returns 1 if it is an archive or zero
          otherwise.  The file is positioned at the end of the archive
          header and at the beginning of the first member of the
          archive.

          Nextar extracts information describing the archive member
          stored at offset in the file associated with bp. If the
          header describing the member can be extracted and decoded,
          the size of the member is returned.  Adding this value to
          offset yields the offset of the beginning of the next member
          in the archive.  On return the input file is positioned at
          the end of the member header and the name of the member is
          stored in buf, a buffer of SARNAME characters.  If there are
          no more members, nextar returns zero; a negative return
          indicates a missing or malformed header.

          Readar constructs the symbol table of the object file stored
          at the current position in the archive associated with bp.
          This function operates exactly as readobj; the only differ-
          ence is the extra argument, end, specifying the offset to
          the beginning of the next member in the archive.  Readar
          leaves the file positioned at that point.

     SOURCE
          /sys/src/libmach

     SEE ALSO
          mach(2), symbol(2), bio(2), a.out(6)

     DIAGNOSTICS
          These routines set errstr.

     Page 2                       Plan 9             (printed 3/19/24)