a.out 7.0 KB

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