NAME

a.out − assembler and link editor output

SYNOPSIS

#include <a.out.h>

DESCRIPTION

A.out is the output file of the assembler as(1) and the link editor ld(1). Both programs make a.out executable if there were no errors and no unresolved external references.  Layout information as given in the include file for the IBM RT PC is:

/∗
∗ Header prepended to each a.out file.
∗/
struct exec {
longa_magic;/∗ magic number ∗/
unsigneda_text;/∗ size of text segment ∗/
unsigneda_data;/∗ size of initialized data ∗/
unsigneda_bss;/∗ size of uninitialized data ∗/
unsigneda_syms;/∗ size of symbol table ∗/
unsigneda_entry;/∗ entry point ∗/
unsigneda_trsize;/∗ size of text relocation ∗/
unsigneda_drsize;/∗ size of data relocation ∗/
};
 #defineOMAGIC0407/∗ old impure format ∗/
#defineNMAGIC0410/∗ read-only text ∗/
#defineZMAGIC0413/∗ demand load format ∗/
 /∗
∗ Macros which take exec structures as arguments and tell whether
∗ the file has a reasonable magic number or offsets to text|symbols|strings.
∗/
#defineN_BADMAG(x) \
    (((x).a_magic)!=OMAGIC && ((x).a_magic)!=NMAGIC && ((x).a_magic)!=ZMAGIC)
 #defineN_TXTOFF(x) \
((x).a_magic==ZMAGIC ? 2048 : sizeof (struct exec))
#define N_SYMOFF(x) \
(N_TXTOFF(x) + (x).a_text+(x).a_data + (x).a_trsize+(x).a_drsize)
#defineN_STROFF(x) \
(N_SYMOFF(x) + (x).a_syms)

The file has five sections: a header, the program text and data, relocation information, a symbol table and a string table (in that order).  The last three may be omitted if the program was loaded with the ‘−s’ option of ld(1) or if the symbols and relocation have been removed by strip(1).

In the header the sizes of each section are given in bytes.  The size of the header is not included in any of the other sizes. 

When an a.out file is executed, three logical segments are set up: the text segment, the data segment (with uninitialized data, which starts off as all 0, following initialized), and a stack.  The text segment begins at 0 in the core image; the header is not loaded.  If the magic number in the header is OMAGIC (0407), it means that the text segment is not to be write-protected and shared, so the data segment is immediately contiguous with the text segment.  This is the oldest kind of executable program and is rarely used.  If the magic number is NMAGIC (0410) or ZMAGIC (0413), the data segment is loaded at 0x10000000, and the text segment is not writable by the program; if other processes are executing the same file, they will share the text segment.  For ZMAGIC format, the text segment begins at a 0 mod 2048-byte boundary in the a.out file, the remaining bytes after the header in the first block are reserved and should be zero.  Here, the text and data sizes must both be multiples of 2048 bytes, and the pages of the file will be brought into the running image as needed, and not pre-loaded as with the other formats.  This is especially suitable for large programs and is the default format produced by ld(1).

The user stack is located near the top of segment 1, after UPAGES of kernel stack and one page of redzone.  The first page of user stack is reserved for kernel floating point use; therefore, the actual user stack starts at 0x1fffd800 (given that UPAGES = 3).  The stack is automatically extended as required.  The data segment is extended only as requested by brk(2).

After the header in the file follow the text, data, text relocation data relocation, symbol table and string table in that order.  The text begins at the byte 2048 in the file for ZMAGIC format or just after the header for the other formats.  The N_TXTOFF macro returns this absolute file position when given the name of an exec structure as argument.  The data segment is contiguous with the text and immediately followed by the text relocation and then the data relocation information.  The symbol table follows all this; its position is computed by the N_SYMOFF macro.  Finally, the string table immediately follows the symbol table at a position that can be gotten easily using N_STROFF.  The first 4 bytes of the string table are not used for string storage; instead they contain the size of the string table.  The size includes the 4 bytes, and the minimum string table size is thus 4. 

The layout of a symbol table entry and the principal flag values that distinguish symbol types are given in the include file as follows:

/∗

∗ Format of a symbol table entry.

∗/
struct nlist {
union {
char∗n_name;/∗ for use when in-core ∗/
longn_strx;/∗ index into file string table ∗/
} n_un;
unsigned charn_type;/∗ type flag, i.e. N_TEXT etc; see below ∗/
charn_other;
shortn_desc;/∗ see <stab.h> ∗/
unsignedn_value;/∗ value of this symbol (or offset) ∗/
};
#definen_hashn_desc/∗ used internally by ld ∗/
 /∗

∗ Simple values for n_type.

∗/
#defineN_UNDF0x0/∗ undefined ∗/
#defineN_ABS0x2/∗ absolute ∗/
#defineN_TEXT0x4/∗ text ∗/
#defineN_DATA0x6/∗ data ∗/
#defineN_BSS0x8/∗ bss ∗/
#defineN_COMM0x12/∗ common (internal to ld) ∗/
#defineN_FN0x1f/∗ file name symbol ∗/
 #defineN_EXT01/∗ external bit, or’ed in ∗/
#defineN_TYPE0x1e/∗ mask for all the type bits ∗/
 /∗

∗ Other permanent symbol table entries have some of the N_STAB bits set.

∗ These are given in <stab.h>

∗/
#defineN_STAB0xe0/∗ if any of these bits set, don’t discard ∗/
 /∗

∗ Format for namelist values.

∗/
#defineN_FORMAT“%08x”

In the a.out file a symbol’s n_un.n_strx field gives an index into the string table.  A n_strx value of 0 means that no name is associated with a particular symbol table entry.  The field n_un.n_name can be used to refer to the symbol name only if the program sets this up using n_strx and appropriate data from the string table. 

If a symbol’s type is undefined externally and the value field is non-zero, the loader ld interprets the symbol as the name of a common region whose size is shown by the value of the symbol. 

The value of a byte in the text or data that is not a part of a reference to an undefined external symbol will appear in memory when the file is executed.  If a byte in the text or data involves a reference to an undefined external symbol, as shown by the relocation information, then the value stored in the file is an offset from the associated external symbol.  When the file is processed by the link editor and the external symbol becomes defined, the value of the symbol will be added to the bytes in the file. 

If relocation information is present, it amounts to eight bytes per relocatable datum as in the following structure:

/∗

∗ Format of a relocation datum.

∗/
struct relocation_info {
intr_address;/∗ address which is relocated ∗/
unsignedr_symbolnum:24,/∗ local symbol ordinal ∗/
r_pcrel:1, /∗ branch address relocation ∗/
r_length:2,/∗ 1 byte, 2 bytes, 4 bytes, split address ∗/
r_extern:1,/∗ does not include value of sym referenced ∗/
:4;/∗ nothing, yet ∗/
};

A datum with (r_pcrel && r_length==2) indicates branch address relocation; r_address points to the branch opcode.  If the opcode is any of bb, bbx, bnb, bnbx, bali or balix, relocation is for a 20-bit pc-relative displacement field.  If the opcode is bala or balax, relocation is for a 24-bit absolute displacement field. 

A datum with (r_length==3) indicates split-address relocation on an instruction pair:  either
cal r,low; op r,high  or  cau r,high; op r,low. r_address points to the displacement field of the first instruction, the opcode of which indicates a high/low or low/high split address.

There is no relocation information if a_trsize+a_drsize==0.  If r_extern is 0, then r_symbolnum is really a n_type for the relocation.  (e.g. N_TEXT meaning relative to segment text origin.) 

SEE ALSO

adb(1), as(1), dbx(1), ld(1), nm(1), strip(1), stab(5)

BUGS

The size of the string table should be part of the header; many programs, however, assume the header is 32 bytes long.  Such programs would have to be changed. 

PRPQs 5799-WZQ/5799-PFF: IBM/4.3  —  July 1987