Commit | Line | Data |
---|---|---|
517c4acb KB |
1 | .\" Copyright (c) 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
2b01ef56 | 3 | .\" |
f079614e CL |
4 | .\" This man page is derived from documentation contributed to Berkeley by |
5 | .\" Donn Seeley at UUNET Technologies, Inc. | |
2b01ef56 | 6 | .\" |
f079614e CL |
7 | .\" %sccs.include.redist.roff% |
8 | .\" | |
517c4acb | 9 | .\" @(#)a.out.5 8.1 (Berkeley) %G% |
f079614e CL |
10 | .\" |
11 | .Dd | |
12 | .Dt A.OUT 5 | |
13 | .Os | |
14 | .Sh NAME | |
15 | .Nm a.out | |
16 | .Nd format of executable binary files | |
17 | .Sh SYNOPSIS | |
18 | .Fd #include <a.out.h> | |
19 | .Sh DESCRIPTION | |
20 | The include file | |
21 | .Aq Pa a.out.h | |
22 | declares three structures and several macros. | |
23 | The structures describe the format of | |
24 | executable machine code files | |
25 | .Pq Sq binaries | |
26 | on the system. | |
27 | .Pp | |
28 | A binary file consists of up to 7 sections. | |
29 | In order, these sections are: | |
30 | .Bl -tag -width "text relocations" | |
31 | .It exec header | |
32 | Contains parameters used by the kernel | |
33 | to load a binary file into memory and execute it, | |
34 | and by the link editor | |
35 | .Xr ld 1 | |
36 | to combine a binary file with other binary files. | |
37 | This section is the only mandatory one. | |
38 | .It text segment | |
39 | Contains machine code and related data | |
40 | that are loaded into memory when a program executes. | |
41 | May be loaded read-only. | |
42 | .It data segment | |
43 | Contains initialized data; always loaded into writable memory. | |
44 | .It text relocations | |
45 | Contains records used by the link editor | |
46 | to update pointers in the text segment when combining binary files. | |
47 | .It data relocations | |
48 | Like the text relocation section, but for data segment pointers. | |
49 | .It symbol table | |
50 | Contains records used by the link editor | |
51 | to cross reference the addresses of named variables and functions | |
52 | .Pq Sq symbols | |
53 | between binary files. | |
54 | .It string table | |
55 | Contains the character strings corresponding to the symbol names. | |
56 | .El | |
57 | .Pp | |
58 | Every binary file begins with an | |
59 | .Fa exec | |
60 | structure: | |
61 | .Bd -literal -offset indent | |
2b01ef56 | 62 | struct exec { |
f079614e CL |
63 | unsigned short a_mid; |
64 | unsigned short a_magic; | |
65 | unsigned long a_text; | |
66 | unsigned long a_data; | |
67 | unsigned long a_bss; | |
68 | unsigned long a_syms; | |
69 | unsigned long a_entry; | |
70 | unsigned long a_trsize; | |
71 | unsigned long a_drsize; | |
72 | }; | |
73 | .Ed | |
74 | .Pp | |
75 | The fields have the following functions: | |
76 | .Bl -tag -width a_trsize | |
77 | .It Fa a_mid | |
78 | Contains a bit pattern that | |
79 | identifies binaries that were built for | |
80 | certain sub-classes of an architecture | |
81 | .Pq Sq machine IDs | |
82 | or variants of the operating system on a given architecture. | |
83 | The kernel may not support all machine IDs | |
84 | on a given architecture. | |
85 | The | |
86 | .Fa a_mid | |
87 | field is not present on some architectures; | |
88 | in this case, the | |
89 | .Fa a_magic | |
90 | field has type | |
91 | .Em unsigned long . | |
92 | .It Fa a_magic | |
93 | Contains a bit pattern | |
94 | .Pq Sq magic number | |
95 | that uniquely identifies binary files | |
96 | and distinguishes different loading conventions. | |
97 | The field must contain one of the following values: | |
98 | .Bl -tag -width ZMAGIC | |
99 | .It Dv OMAGIC | |
100 | The text and data segments immediately follow the header | |
101 | and are contiguous. | |
102 | The kernel loads both text and data segments into writable memory. | |
103 | .It Dv NMAGIC | |
104 | As with | |
105 | .Dv OMAGIC , | |
106 | text and data segments immediately follow the header and are contiguous. | |
107 | However, the kernel loads the text into read-only memory | |
108 | and loads the data into writable memory at the next | |
109 | page boundary after the text. | |
110 | .It Dv ZMAGIC | |
111 | The kernel loads individual pages on demand from the binary. | |
112 | The header, text segment and data segment are all | |
113 | padded by the link editor to a multiple of the page size. | |
114 | Pages that the kernel loads from the text segment are read-only, | |
115 | while pages from the data segment are writable. | |
116 | .El | |
117 | .It Fa a_text | |
118 | Contains the size of the text segment in bytes. | |
119 | .It Fa a_data | |
120 | Contains the size of the data segment in bytes. | |
121 | .It Fa a_bss | |
122 | Contains the number of bytes in the | |
123 | .Sq bss segment | |
124 | and is used by the kernel to set the initial break | |
125 | .Pq Xr brk 2 | |
126 | after the data segment. | |
127 | The kernel loads the program so that this amount of writable memory | |
128 | appears to follow the data segment and initially reads as zeroes. | |
129 | .It Fa a_syms | |
130 | Contains the size in bytes of the symbol table section. | |
131 | .It Fa a_entry | |
132 | Contains the address in memory of the entry point | |
133 | of the program after the kernel has loaded it; | |
134 | the kernel starts the execution of the program | |
135 | from the machine instruction at this address. | |
136 | .It Fa a_trsize | |
137 | Contains the size in bytes of the text relocation table. | |
138 | .It Fa a_drsize | |
139 | Contains the size in bytes of the data relocation table. | |
140 | .El | |
141 | .Pp | |
142 | The | |
143 | .Pa a.out.h | |
144 | include file defines several macros which use an | |
145 | .Fa exec | |
146 | structure to test consistency or to locate section offsets in the binary file. | |
147 | .Bl -tag -width N_BADMAG(exec) | |
148 | .It Fn N_BADMAG exec | |
149 | Nonzero if the | |
150 | .Fa a_magic | |
151 | field does not contain a recognized value. | |
152 | .It Fn N_TXTOFF exec | |
153 | The byte offset in the binary file of the beginning of the text segment. | |
154 | .It Fn N_SYMOFF exec | |
155 | The byte offset of the beginning of the symbol table. | |
156 | .It Fn N_STROFF exec | |
157 | The byte offset of the beginning of the string table. | |
158 | .El | |
159 | .Pp | |
160 | Relocation records have a standard format which | |
161 | is described by the | |
162 | .Fa relocation_info | |
163 | structure: | |
164 | .Bd -literal -offset indent | |
165 | struct relocation_info { | |
166 | int r_address; | |
167 | unsigned int r_symbolnum : 24, | |
168 | r_pcrel : 1, | |
169 | r_length : 2, | |
170 | r_extern : 1, | |
171 | : 4; | |
2b01ef56 | 172 | }; |
f079614e CL |
173 | .Ed |
174 | .Pp | |
175 | The | |
176 | .Fa relocation_info | |
177 | fields are used as follows: | |
178 | .Bl -tag -width r_symbolnum | |
179 | .It Fa r_address | |
180 | Contains the byte offset of a pointer that needs to be link-edited. | |
181 | Text relocation offsets are reckoned from the start of the text segment, | |
182 | and data relocation offsets from the start of the data segment. | |
183 | The link editor adds the value that is already stored at this offset | |
184 | into the new value that it computes using this relocation record. | |
185 | .It Fa r_symbolnum | |
186 | Contains the ordinal number of a symbol structure | |
187 | in the symbol table (it is | |
188 | .Em not | |
189 | a byte offset). | |
190 | After the link editor resolves the absolute address for this symbol, | |
191 | it adds that address to the pointer that is undergoing relocation. | |
192 | (If the | |
193 | .Fa r_extern | |
194 | bit is clear, the situation is different; see below.) | |
195 | .It Fa r_pcrel | |
196 | If this is set, | |
197 | the link editor assumes that it is updating a pointer | |
198 | that is part of a machine code instruction using pc-relative addressing. | |
199 | The address of the relocated pointer is implicitly added | |
200 | to its value when the running program uses it. | |
201 | .It Fa r_length | |
202 | Contains the log base 2 of the length of the pointer in bytes; | |
203 | 0 for 1-byte displacements, 1 for 2-byte displacements, | |
204 | 2 for 4-byte displacements. | |
205 | .It Fa r_extern | |
206 | Set if this relocation requires an external reference; | |
207 | the link editor must use a symbol address to update the pointer. | |
208 | When the | |
209 | .Fa r_extern | |
210 | bit is clear, the relocation is | |
211 | .Sq local ; | |
212 | the link editor updates the pointer to reflect | |
213 | changes in the load addresses of the various segments, | |
214 | rather than changes in the value of a symbol. | |
215 | In this case, the content of the | |
216 | .Fa r_symbolnum | |
217 | field is an | |
218 | .Fa n_type | |
219 | value (see below); | |
220 | this type field tells the link editor | |
221 | what segment the relocated pointer points into. | |
222 | .El | |
223 | .Pp | |
224 | Symbols map names to addresses (or more generally, strings to values). | |
225 | Since the link-editor adjusts addresses, | |
226 | a symbol's name must be used to stand for its address | |
227 | until an absolute value has been assigned. | |
228 | Symbols consist of a fixed-length record in the symbol table | |
229 | and a variable-length name in the string table. | |
230 | The symbol table is an array of | |
231 | .Fa nlist | |
232 | structures: | |
233 | .Bd -literal -offset indent | |
2b01ef56 KM |
234 | struct nlist { |
235 | union { | |
f079614e CL |
236 | char *n_name; |
237 | long n_strx; | |
2b01ef56 | 238 | } n_un; |
f079614e CL |
239 | unsigned char n_type; |
240 | char n_other; | |
241 | short n_desc; | |
242 | unsigned long n_value; | |
2b01ef56 | 243 | }; |
f079614e CL |
244 | .Ed |
245 | .Pp | |
246 | The fields are used as follows: | |
247 | .Bl -tag -width n_un.n_strx | |
248 | .It Fa n_un.n_strx | |
249 | Contains a byte offset into the string table | |
250 | for the name of this symbol. | |
251 | When a program accesses a symbol table with the | |
252 | .Xr nlist 3 | |
253 | function, | |
254 | this field is replaced with the | |
255 | .Fa n_un.n_name | |
256 | field, which is a pointer to the string in memory. | |
257 | .It Fa n_type | |
258 | Used by the link editor to determine | |
259 | how to update the symbol's value. | |
260 | The | |
261 | .Fa n_type | |
262 | field is broken down into three sub-fields using bitmasks. | |
263 | The link editor treats symbols with the | |
264 | .Dv N_EXT | |
265 | type bit set as | |
266 | .Sq external | |
267 | symbols and permits references to them from other binary files. | |
268 | The | |
269 | .Dv N_TYPE | |
270 | mask selects bits of interest to the link editor: | |
271 | .Bl -tag -width N_TEXT | |
272 | .It Dv N_UNDF | |
273 | An undefined symbol. | |
274 | The link editor must locate an external symbol with the same name | |
275 | in another binary file to determine the absolute value of this symbol. | |
276 | As a special case, if the | |
277 | .Fa n_value | |
278 | field is nonzero and no binary file in the link-edit defines this symbol, | |
279 | the link-editor will resolve this symbol to an address | |
280 | in the bss segment, | |
281 | reserving an amount of bytes equal to | |
282 | .Fa n_value . | |
283 | If this symbol is undefined in more than one binary file | |
284 | and the binary files do not agree on the size, | |
285 | the link editor chooses the greatest size found across all binaries. | |
286 | .It Dv N_ABS | |
287 | An absolute symbol. | |
288 | The link editor does not update an absolute symbol. | |
289 | .It Dv N_TEXT | |
290 | A text symbol. | |
291 | This symbol's value is a text address and | |
292 | the link editor will update it when it merges binary files. | |
293 | .It Dv N_DATA | |
294 | A data symbol; similar to | |
295 | .Dv N_TEXT | |
296 | but for data addresses. | |
297 | The values for text and data symbols are not file offsets but | |
298 | addresses; to recover the file offsets, it is necessary | |
299 | to identify the loaded address of the beginning of the corresponding | |
300 | section and subtract it, then add the offset of the section. | |
301 | .It Dv N_BSS | |
302 | A bss symbol; like text or data symbols but | |
303 | has no corresponding offset in the binary file. | |
304 | .It Dv N_FN | |
305 | A filename symbol. | |
306 | The link editor inserts this symbol before | |
307 | the other symbols from a binary file when | |
308 | merging binary files. | |
309 | The name of the symbol is the filename given to the link editor, | |
310 | and its value is the first text address from that binary file. | |
311 | Filename symbols are not needed for link-editing or loading, | |
312 | but are useful for debuggers. | |
313 | .El | |
314 | .Pp | |
315 | The | |
316 | .Dv N_STAB | |
317 | mask selects bits of interest to symbolic debuggers | |
318 | such as | |
319 | .Xr gdb 1 ; | |
320 | the values are described in | |
321 | .Xr stab 5 . | |
322 | .It Fa n_other | |
323 | This field is currently unused. | |
324 | .It Fa n_desc | |
325 | Reserved for use by debuggers; passed untouched by the link editor. | |
326 | Different debuggers use this field for different purposes. | |
327 | .It Fa n_value | |
328 | Contains the value of the symbol. | |
329 | For text, data and bss symbols, this is an address; | |
330 | for other symbols (such as debugger symbols), | |
331 | the value may be arbitrary. | |
332 | .El | |
333 | .Pp | |
334 | The string table consists of an | |
335 | .Em unsigned long | |
336 | length followed by null-terminated symbol strings. | |
337 | The length represents the size of the entire table in bytes, | |
338 | so its minimum value (or the offset of the first string) | |
339 | is always 4 on 32-bit machines. | |
340 | .Sh SEE ALSO | |
341 | .Xr ld 1 , | |
342 | .Xr execve 2 , | |
343 | .Xr nlist 3 , | |
344 | .Xr core 5 , | |
345 | .Xr dbx 5 , | |
346 | .Xr stab 5 | |
347 | .Sh HISTORY | |
348 | The | |
349 | .Pa a.out.h | |
350 | include file appeared in | |
351 | .At v7 . | |
352 | .Sh BUGS | |
353 | Since not all of the supported architectures use the | |
354 | .Fa a_mid | |
355 | field, | |
356 | it can be difficult to determine what | |
357 | architecture a binary will execute on | |
358 | without examining its actual machine code. | |
359 | Even with a machine identifier, | |
360 | the byte order of the | |
361 | .Fa exec | |
362 | header is machine-dependent. | |
363 | .Pp | |
364 | Nobody seems to agree on what | |
365 | .Em bss | |
366 | stands for. | |
367 | .Pp | |
368 | New binary file formats may be supported in the future, | |
369 | and they probably will not be compatible at any level | |
370 | with this ancient format. |