sys/man/6/a.out

   1 .TH A.OUT 6
   2 .SH NAME
   3 a.out \- object file format
   4 .SH SYNOPSIS
   5 .B #include <a.out.h>
   6 .SH DESCRIPTION
   7 An executable Plan 9 binary file has up to six sections:
   8 a header, the program text, the data,
   9 a symbol table, a PC/SP offset table (MC68020 only),
  10 and finally a PC/line number table.
  11 The header, given by a structure in
  12 .BR <a.out.h> ,
  13 contains 4-byte integers in big-endian order:
  14 .PP
  15 .EX
  16 .ta \w'#define  'u +\w'_MAGIC(b)  'u +\w'_MAGIC(10)  'u +4n +4n +4n +4n
  17 typedef struct Exec {
  18         long    magic;  /* magic number */
  19         long    text;   /* size of text segment */
  20         long    data;   /* size of initialized data */
  21         long    bss;    /* size of uninitialized data */
  22         long    syms;   /* size of symbol table */
  23         long    entry;  /* entry point */
  24         long    spsz;   /* size of pc/sp offset table */
  25         long    pcsz;   /* size of pc/line number table */
  26 } Exec;
  27
  28 #define HDR_MAGIC       0x00008000
  29
  30 #define _MAGIC(f, b)    ((f)|((((4*(b))+0)*(b))+7))
  31 #define A_MAGIC _MAGIC(0, 8)            /* 68020 */
  32 #define I_MAGIC _MAGIC(0, 11)           /* intel 386 */
  33 #define J_MAGIC _MAGIC(0, 12)           /* intel 960 (retired) */
  34 #define K_MAGIC _MAGIC(0, 13)           /* sparc */
  35 #define V_MAGIC _MAGIC(0, 16)           /* mips 3000 BE */
  36 #define X_MAGIC _MAGIC(0, 17)           /* att dsp 3210 (retired) */
  37 #define M_MAGIC _MAGIC(0, 18)           /* mips 4000 BE */
  38 #define D_MAGIC _MAGIC(0, 19)           /* amd 29000 (retired) */
  39 #define E_MAGIC _MAGIC(0, 20)           /* arm */
  40 #define Q_MAGIC _MAGIC(0, 21)           /* powerpc */
  41 #define N_MAGIC _MAGIC(0, 22)           /* mips 4000 LE */
  42 #define L_MAGIC _MAGIC(0, 23)           /* dec alpha (retired) */
  43 #define P_MAGIC _MAGIC(0, 24)           /* mips 3000 LE */
  44 #define U_MAGIC _MAGIC(0, 25)           /* sparc64 */
  45 #define S_MAGIC _MAGIC(HDR_MAGIC, 26)   /* amd64 */
  46 #define T_MAGIC _MAGIC(HDR_MAGIC, 27)   /* powerpc64 */
  47 #define R_MAGIC _MAGIC(HDR_MAGIC, 28)   /* arm64 */
  48
  49 .EE
  50 .DT
  51 .PP
  52 Sizes are expressed in bytes.
  53 The size of the header is not included in any of the other sizes.
  54 .PP
  55 When a Plan 9 binary file is executed,
  56 a memory image of three segments is
  57 set up: the text segment, the data segment, and the stack.
  58 The text segment begins at a virtual address which is
  59 a multiple of the machine-dependent page size.
  60 The text segment consists of the header and the first
  61 .B text
  62 bytes of the binary file.
  63 The
  64 .B entry
  65 field gives the virtual address of the entry point of the program.
  66 The data segment starts at the first page-rounded virtual address
  67 after the text segment.
  68 It consists of the next
  69 .B data
  70 bytes of the binary file, followed by
  71 .B bss
  72 bytes initialized to zero.
  73 The stack occupies the highest possible locations
  74 in the core image, automatically growing downwards.
  75 The bss segment may be extended by
  76 .IR brk (2).
  77 .PP
  78 The next
  79 .B syms
  80 (possibly zero)
  81 bytes of the file contain symbol table
  82 entries, each laid out as:
  83 .IP
  84 .EX
  85 uchar value[4];
  86 char  type;
  87 char  name[\f2n\fP];   /* NUL-terminated */
  88 .EE
  89 .PP
  90 The
  91 .B value
  92 is in big-endian order and
  93 the size of the
  94 .B name
  95 field is not pre-defined: it is a zero-terminated array of
  96 variable length.
  97 .PP
  98 The
  99 .B type
 100 field is one of the following characters with the high bit set:
 101 .RS
 102 .TP
 103 .B T
 104 text segment symbol
 105 .PD0
 106 .TP
 107 .B t
 108 static text segment symbol
 109 .TP
 110 .B L
 111 leaf function text segment symbol
 112 .TP
 113 .B l
 114 static leaf function text segment symbol
 115 .TP
 116 .B D
 117 data segment symbol
 118 .TP
 119 .B d
 120 static data segment symbol
 121 .TP
 122 .B B
 123 bss segment symbol
 124 .TP
 125 .B b
 126 static bss segment symbol
 127 .TP
 128 .B a
 129 automatic (local) variable symbol
 130 .TP
 131 .B p
 132 function parameter symbol
 133 .RE
 134 .PD
 135 .PP
 136 A few others are described below.
 137 The symbols in the symbol table appear in the same order
 138 as the program components they describe.
 139 .PP
 140 The Plan 9 compilers implement a virtual stack frame pointer rather
 141 than dedicating a register;
 142 moreover, on the MC680X0 architectures
 143 there is a variable offset between the stack pointer and the
 144 frame pointer.
 145 Following the symbol table,
 146 MC680X0 executable files contain a
 147 .BR spsz -byte
 148 table encoding the offset
 149 of the stack frame pointer as a function of program location;
 150 this section is not present for other architectures.
 151 The PC/SP table is encoded as a byte stream.
 152 By setting the PC to the base of the text segment
 153 and the offset to zero and interpreting the stream,
 154 the offset can be computed for any PC.
 155 A byte value of 0 is followed by four bytes that hold, in big-endian order,
 156 a constant to be added to the offset.
 157 A byte value of 1 to 64 is multiplied by four and added, without sign
 158 extension, to the offset.
 159 A byte value of 65 to 128 is reduced by 64, multiplied by four, and
 160 subtracted from the offset.
 161 A byte value of 129 to 255 is reduced by 129, multiplied by the quantum
 162 of instruction size
 163 (e.g. two on the MC680X0),
 164 and added to the current PC without changing the offset.
 165 After any of these operations, the instruction quantum is added to the PC.
 166 .PP
 167 A similar table, occupying
 168 .BR pcsz -bytes,
 169 is the next section in an executable; it is present for all architectures.
 170 The same algorithm may be run using this table to
 171 recover the absolute source line number from a given program location.
 172 The absolute line number (starting from zero) counts the newlines
 173 in the C-preprocessed source seen by the compiler.
 174 Three symbol types in the main symbol table facilitate conversion of the absolute
 175 number to source file and line number:
 176 .RS
 177 .TP
 178 .B f
 179 source file name components
 180 .TP
 181 .B z
 182 source file name
 183 .TP
 184 .B Z
 185 source file line offset
 186 .RE
 187 .PP
 188 The
 189 .B f
 190 symbol associates an integer (the
 191 .B value
 192 field of the `symbol') with
 193 a unique file path name component (the
 194 .B name
 195 of the `symbol').
 196 These path components are used by the
 197 .B z
 198 symbol to represent a file name: the
 199 first byte of the name field is always 0; the remaining
 200 bytes hold a zero-terminated array of 16-bit values (in big-endian order)
 201 that represent file name components from
 202 .B f
 203 symbols.
 204 These components, when separated by slashes, form a file name.
 205 The initial slash of a file name is recorded in the symbol table by an
 206 .B f
 207 symbol; when forming file names from
 208 .B z
 209 symbols an initial slash is not to be assumed.
 210 The
 211 .B z
 212 symbols are clustered, one set for each object file in the program,
 213 before any text symbols from that object file.
 214 The set of
 215 .B z
 216 symbols for an object file form a
 217 .I history stack
 218 of the included source files from which the object file was compiled.
 219 The value associated with each
 220 .B z
 221 symbol is the absolute line number at which that file was included in the source;
 222 if the name associated with the
 223 .B z
 224 symbol is null, the symbol represents the end of an included file, that is,
 225 a pop of the history stack.
 226 If the value of the
 227 .B z
 228 symbol is 1 (one),
 229 it represents the start of a new history stack.
 230 To recover the source file and line number for a program location,
 231 find the text symbol containing the location
 232 and then the first history stack preceding the text symbol in the symbol table.
 233 Next, interpret the PC/line offset table to discover the absolute line number
 234 for the program location.
 235 Using the line number, scan the history stack to find the set of source
 236 files open at that location.
 237 The line number within the file can be found using the line numbers
 238 in the history stack.
 239 The
 240 .B Z
 241 symbols correspond to
 242 .B #line
 243 directives in the source; they specify an adjustment to the line number
 244 to be printed by the above algorithm.  The offset is associated with the
 245 first previous
 246 .B z
 247 symbol in the symbol table.
 248 .SH "SEE ALSO"
 249 .IR db (1),
 250 .IR acid (1),
 251 .IR 2a (1),
 252 .IR 2l (1),
 253 .IR nm (1),
 254 .IR strip (1),
 255 .IR mach (2),
 256 .IR symbol (2)
 257 .SH BUGS
 258 There is no type information in the symbol table; however, the
 259 .B -a
 260 flags on the compilers will produce symbols for
 261 .IR acid (1).