man(1) Manual page archive


     A.OUT(6)                                                 A.OUT(6)

     NAME
          a.out - object file format

     SYNOPSIS
          #include <a.out.h>

     DESCRIPTION
          An executable Plan 9 binary file has six sections: a header,
          the program text, the data, a symbol table, an PC/SP offset
          table, and finally a PC/line number table.  The header for-
          mat, given in <a.out.h>, contains 4-byte integers in big-
          endian order:

          typedef struct Exec Exec;
          struct Exec {
                   long       magic;      /* magic number */
                   long       text;       /* size of text segment */
                   long       data;       /* size of initialized data */
                   long       bss;        /* size of uninitialized data */
                   long       syms;       /* size of symbol table */
                   long       entry;      /* entry point */
                   long       spsz;       /* size of pc/sp offset table */
                   long       pcsz;       /* size of pc/line number table */
          };
          #define  _MAGIC(b)  ((((4*b)+0)*b)+7)
          #define  A_MAGIC    _MAGIC(8)   /* vax */
          #define  Z_MAGIC    _MAGIC(10)  /* hobbit */
          #define  I_MAGIC    _MAGIC(11)  /* intel 386 */
          #define  J_MAGIC    _MAGIC(12)  /* intel 960 */
          #define  K_MAGIC    _MAGIC(13)  /* sparc */
          #define  P_MAGIC    _MAGIC(14)  /* hp-pa */
          #define  V_MAGIC    _MAGIC(16)  /* mips 3000 */

          Sizes are expressed in bytes.  The size of the header is not
          included in any of the other sizes.

          When a Plan 9 binary file is executed, a memory image of
          three segments is set up: the text segment, the data seg-
          ment, and a stack.  The text segment begins at virtual
          address p, a multiple of the machine-dependent page size.
          The text segment consists of the header and the first text
          bytes of the binary file.  The entry field gives the virtual
          address of the start of the program, usually p+sizeof(struct
          exec).  The data segment starts at the first page-rounded
          virtual address after the text segment.  It consists of the
          next data bytes of the binary file, followed by bss bytes
          initialized to zero.  The stack occupies the highest possi-
          ble locations in the core image, automatically growing down-
          wards.  The data segment may be extended by brk(2).

     A.OUT(6)                                                 A.OUT(6)

          The next syms (possibly zero) bytes of the binary file con-
          tain symbol table entries.  The layout of a symbol table
          entry, also in big-endian order, is also in <a.out.h>:

               #define  NNAME   20
               typedef  struct  Sym Sym;
               struct   Sym {
                        long    value;
                        char    type;
                        char    name[NNAME];   /* NUL-terminated */
                        char    pad[3];
               };

          The type field is one of the following characters:

               T    text segment symbol
               t    static text segment symbol
               L    leaf function text segment symbol
               l    static leaf function text segment symbol
               D    data segment symbol
               d    static data segment symbol
               B    bss segment symbol
               b    static bss segment symbol
               a    automatic (local) variable symbol
               p    function parameter symbol
          A few others are described below.  The symbols in the symbol
          table appear in the same order as the program components
          they describe.
          After the symbol table comes a spsz-byte SP offset table and
          a pcsz-byte source code line number table.  Both tables may
          be empty.  The Plan 9 compilers implement a virtual frame
          pointer rather than dedicating a register; moreover, on the
          MC68020 and i386 there is a variable offset between the
          stack pointer and the frame pointer.  The PC/SP offset table
          encodes this offset as a function of program location.
          The table is encoded as a byte stream.  By interpreting the
          stream setting the PC to the base of the text segment and
          the offset to zero, the offset can be computed for any PC.
          A byte value of 0 is followed by four bytes that hold, in
          big-endian order, a constant to be added to the offset.  A
          byte value of 1 to 64 is multiplied by four and added, with-
          out sign extension, to the offset.  A byte value of 65 to
          128 is reduced by 64, multiplied by four, and subtracted
          from the offset.  A byte value of 129 to 255 is reduced by
          129, multiplied by the quantum of instruction size (e.g.
          four bytes on the RISC machines, two on the MC68020, one on
          the i386), and added to the current PC without changing the
          offset.  After any of these operations, the instruction
          quantum is added to the PC.
          The same algorithm may be run over the PC/line number table
          to recover the absolute source line number from a given pro-
          gram location.  The absolute line number (starting from

     A.OUT(6)                                                 A.OUT(6)

          zero) counts the newlines in the C-preprocessed source seen
          by the compiler.  Three symbol types in the main symbol
          table facilitate conversion of the absolute number to source
          file and line number:
               f    source file name components
               z    source file name
               Z    source file line offset
          The f symbol identifies an integer (the value of the `sym-
          bol') to represent a unique file path name component (the
          name of the `symbol').  These path components are used by
          the z symbol to represent a file name: the first byte of the
          name field is always 0; the remaining NNAME-1 bytes hold a
          zero-terminated array of 16-bit values (in big-endian order)
          that represent file name components from f symbols.  These
          components, when separated by slashes, form a file name.
          The initial slash of a file name is recorded in the symbol
          table by an f symbol; when forming file names from z symbols
          an initial slash is not to be assumed.
          The z symbols are clustered, one set for each object file
          from which the program was assembled, before any text sym-
          bols from that object file.  The set of z symbols for an
          object file form a history stack of the included source
          files from which the object file was compiled.  The value
          associated with each z symbol is the absolute line number at
          which that file was included in the source; if the name
          associated with the z symbol is null, the symbol represents
          the end of an included file, that is, a pop of the history
          stack.  If the value of the z symbol is 1 (one), it repre-
          sents the start of a new history stack.
          To recover the source file and line number for a program
          location, find the text symbol containing the location and
          then the first history stack preceding the text symbol in
          the symbol table.  Next, interpret the PC/line offset table
          to discover the absolute line number for the program loca-
          tion.  Using the line number, scan the history stack to find
          the set of source files open at that location.  The line
          number within the file can be found using the line numbers
          in the history stack.
          The Z symbols correspond to #line directives in the source;
          they specify an adjustment to the line number to be printed
          by the above algorithm.  The offset is associated with the
          first previous z symbol in the symbol table.

     SEE ALSO
          db(1), 2a(1), 2l(1), nm(1), strip(1)

     BUGS
          There is no type information in the symbol table.