1A.OUT(5)                      File Formats Manual                     A.OUT(5)
2
3
4

NAME

6       a.out - assembler and link editor output
7

SYNOPSIS

9       #include <a.out.h>
10

DESCRIPTION

12       A.out  is  the  output  file of the assembler as(1) and the link editor
13       ld(1).  Both programs make a.out executable if there were no errors and
14       no  unresolved external references.  Layout information as given in the
15       include file for the PDP11 is:
16
17       /*
18        * Header prepended to each a.out file.
19        */
20       struct   exec {
21                int           a_magic;      /* magic number */
22                unsigned int  a_text;       /* size of text segment */
23                unsigned int  a_data;       /* size of initialized data */
24                unsigned int  a_bss;        /* size of uninitialized data */
25                unsigned int  a_syms;       /* size of symbol table */
26                unsigned int  a_entry;      /* entry point */
27                unsigned int  a_unused;     /* not used */
28                unsigned int  a_flag;       /* relocation info stripped */
29       };
30
31       #define  NOVL          15            /* number of overlays */
32       struct   ovlhdr {
33                int           max_ovl;      /* maximum overlay size */
34                unsigned int  ov_siz[NOVL]; /* size of i'th overlay */
35       };
36
37       struct   xexec {
38                struct exec e;
39                struct ovlhdr o;
40       };
41
42       #define  A_MAGIC1      0407          /* normal */
43       #define  A_MAGIC2      0410          /* read-only text */
44       #define  A_MAGIC3      0411          /* separated I&D */
45       #define  A_MAGIC4      0405          /* overlay */
46       #define  A_MAGIC5      0430          /* auto-overlay (nonseparate) */
47       #define  A_MAGIC6      0431          /* auto-overlay (separate) */
48
49       /*
50        * Macros which take exec structures as arguments and tell whether
51        * the file has a reasonable magic number or offset to text.
52        */
53       #define  N_BADMAG(x) \
54                (((x).a_magic)!=A_MAGIC1 && ((x).a_magic)!=A_MAGIC2 && \
55                ((x).a_magic)!=A_MAGIC3 && ((x).a_magic)!=A_MAGIC4 && \
56                ((x).a_magic)!=A_MAGIC5 && ((x).a_magic)!=A_MAGIC6)
57
58       #define  N_TXTOFF(x) \
59                ((x).a_magic==A_MAGIC5 || (x).a_magic==A_MAGIC6 ? \
60                sizeof(struct ovlhdr) + sizeof(struct exec) : sizeof(struct exec))
61
62       /*
63        * The following were added as part of the new object file format.  They
64        * call functions because calculating the sums of overlay sizes was too
65        * messy (and verbose) to do 'inline'.
66        *
67        * NOTE: if the magic number is that of an overlaid object the program
68        * must pass an extended header ('xexec') as the argument.
69       */
70
71       off_t    n_stroff(), n_symoff(), n_datoff(), n_dreloc(), n_treloc();
72
73       #define  N_STROFF(e) (n_stroff(&e))
74       #define  N_SYMOFF(e) (n_symoff(&e))
75       #define  N_DATOFF(e) (n_datoff(&e))
76       #define  N_DRELOC(e) (n_dreloc(&e))
77       #define  N_TRELOC(e) (n_treloc(&e))
78
79       The file has five sections: a header, the program text and data,  relo‐
80       cation information, a symbol table and a strings table (in that order).
81       The last three may be omitted if the program was loaded with  the  `-s'
82       option  of  ld  or  if  the symbols and relocation have been removed by
83       strip(1).
84
85       In the header the sizes of each section are given  in  bytes,  but  are
86       even.   The  size  of  the  header  is not included in any of the other
87       sizes.
88
89       When an a.out file is executed, three or four logical segments are  set
90       up: the text segment, a possible text overlay segment, the data segment
91       (with uninitialized data, which starts off as all 0, following initial‐
92       ized),  and  a  stack.  The text segment begins at 0 in the core image;
93       the header is not loaded.
94
95       Non-overlaid objects: If the magic number in  the  header  is  A_MAGIC1
96       (0407), it indicates that the text segment is not to be write-protected
97       and shared, so the data segment is immediately contiguous with the text
98       segment.   This  is  the  oldest  kind of executable program and is the
99       default; it should not be used for production binaries.  If  the  magic
100       number  is  A_MAGIC2 (0410), the data segment begins at the first 0 mod
101       8K byte boundary following the text segment, and the  text  segment  is
102       not  writable by the program; if other processes are executing the same
103       file, they will share  the  text  segment.   If  the  magic  number  is
104       A_MAGIC3  (0411),  the text segment is again pure, write-protected, and
105       shared, and moreover instruction and data space are separated; the text
106       and  data  segment  both  begin  at  location  0.   This format is only
107       runnable on processors which  support  separate  instruction  and  data
108       space  but  can  provide significantly more data space than an A_MAGIC2
109       format of the same object.
110
111       Text replacement objects : If the magic number is A_MAGIC4 (0405),  the
112       text  segment is overlaid on an existing non-overlaid pure (A_MAGIC2 or
113       A_MAGIC3) or text replacement (A_MAGIC4) text segment and the  existing
114       data  segment  is  preserved.   The text segment of the previous memory
115       image must be the same size as that  of  the  text  replacement  object
116       being  loaded.   There  is,  unfortunately,  no  loader support to help
117       achieve this requirement.  The text replacement format  is  useful  for
118       objects  which  need  a  large amount of data space on non-separate I&D
119       processors.
120
121       Overlaid objects : If the magic number is A_MAGIC5 (0430), a base  text
122       segment is write-protected and shared and is followed by a text overlay
123       segment.  There are a maximum of NOVL overlays, all  pure  and  shared.
124       The  base  segment runs from 0 to txtsiz.  The overlay region begins at
125       the next 0 mod 8k byte boundary, which is as large as the largest over‐
126       lay.   When  running,  any  one of the overlays can be mapped into this
127       region.  The data segment begins at the following 0 mod 8k byte  bound‐
128       ary.  If the magic number is A_MAGIC6 (0431), the situation is the same
129       as for type A_MAGIC5 except that instruction and data spaces are  sepa‐
130       rated  and  both  begin at location 0.  As with the A_MAGIC3 format, an
131       a.out in A_MAGIC6 format can only be run on a processor which  supports
132       separate  I&D, but again can provide significantly more data space than
133       A_MAGIC5 format.  Both A_MAGIC5 and A_MAGIC6 executable  files  have  a
134       second header between the normal a.out header and the start of the text
135       image; it contains the maximum overlay size and the sizes  of  each  of
136       the  overlays.   The text images of the overlays follow the text in the
137       object file.
138
139       The stack segment will occupy the highest  possible  locations  in  the
140       core  image:  growing  downwards from 0177776(8).  The stack segment is
141       automatically extended as required.  The data segment is only  extended
142       as requested by brk(2).
143
144       The  include  file  a.out.h  defines  _AOUT_INCLUDE_,  the include file
145       nlist.h does not.  This permits  compile  time  initialization  of  the
146       n_name  field  for  programs  that  are  not  looking at the executable
147       header.
148
149       The layout of a symbol table entry and the principal flag  values  that
150       distinguish symbol types are given in the include file as follows:
151
152       struct   nlist {
153       #ifdef   _AOUT_INCLUDE_
154                union {
155                              char *n_name;/* In memory address of symbol name */
156                              off_t n_strx;/* String table offset (file) */
157                } n_un;
158       #else
159                char          *n_name;   /* symbol name (in memory) */
160       #endif
161                u_char        n_type;    /* Type of symbol - see below */
162                char          n_ovly;    /* Overlay number */
163                u_int         n_value;   /* Symbol value */
164       };
165
166       /*
167        * Simple values for n_type.
168        */
169       #define  N_UNDF        0x0        /* undefined */
170       #define  N_ABS         0x1        /* absolute */
171       #define  N_TEXT        0x2        /* text symbol */
172       #define  N_DATA        0x3        /* data symbol */
173       #define  N_BSS         0x4        /* bss symbol */
174       #define  N_REG         0x14       /* register name */
175       #define  N_FN          0x1f       /* file name symbol */
176
177       #define  N_EXT         0x20       /* external bit, or'ed in */
178       #define  N_TYPE        0x1f       /* mask for all the type bits */
179
180       /*
181        * Format for namelist values.
182        */
183       #define  N_FORMAT      "%06o"
184
185       If  a  symbol's type is undefined external, and the value field is non-
186       zero, the symbol is interpreted by the loader ld as the name of a  com‐
187       mon region whose size is indicated by the value of the symbol.
188
189       The  value  of  a  word in the text or data which is not a portion of a
190       reference to an undefined external symbol is exactly that  value  which
191       will appear in memory when the file is executed.  If a word in the text
192       or data involves a reference to an undefined external symbol, as  indi‐
193       cated  by the relocation information, then the value stored in the file
194       is an offset from the associated external symbol.   When  the  file  is
195       processed  by  the link editor and the external symbol becomes defined,
196       the value of the symbol will be added into the word in the file.
197
198       If relocation information is present, it amounts to one word  per  word
199       of  program  text or initialized data.  There is no relocation informa‐
200       tion if the `relocation info stripped' flag in the header is on.  Auto‐
201       matic-overlay  (A_MAGIC5  and A_MAGIC6) files do not contain relocation
202       information.
203
204       Bits 1-3 of a relocation word indicate the segment referred to  by  the
205       text or data word associated with the relocation word:
206
207       000    absolute number
208       002    reference to text segment
209       004    reference to initialized data
210       006    reference to uninitialized data (bss)
211       010    reference to undefined external symbol
212
213       Bit  0  of  the  relocation word indicates, if 1, that the reference is
214       relative to the pc (e.g. `clr x'); if 0, that the reference is  to  the
215       actual symbol (e.g., `clr *$x').
216
217       The remainder of the relocation word (bits 15-4) contains a symbol num‐
218       ber in the case of external references, and is unused otherwise.
219
220       The string table begins with a longword containing the  length  of  the
221       string  table  (including  the  longword itself).  All strings are null
222       terminated.
223
224       The first symbol is numbered 0, the second 1, etc.
225

SEE ALSO

227       as(1), ld(1), nm(1), strip(1), nlist(3)
228

BUGS

230       The current implementation places a maximum length of 32 characters for
231       symbol  names  in a.out files.  This is (relatively) easily raised with
232       the caveat that the linker and other  programs  which  look  at  symbol
233       tables will slow down even more than they already have.
234
235       The 4BSD a.out format has been implemented. This involved modifying the
236       first phase of the C compiler (/lib/c0), the assembler  (/bin/as),  the
237       debugger  adb(1),  the  linker  ld(1),  and  then  simply  porting  the
238       4.3BSD/Net-2 ar(1), nm(1), ranlib(1), strip(1) and nlist(3).
239
240       As part of this effort the include file short_names.h has gone away.
241
242
243
244
2453rd Berkeley Distribution       January 9, 1994                       A.OUT(5)
Impressum