BSD 4_3 release

[unix-history] / usr / man / man5 / a.out.5

diff --git a/usr/man/man5/a.out.5 b/usr/man/man5/a.out.5
index adb2c35..b0427c3 100644 (file)
--- a/usr/man/man5/a.out.5
+++ b/usr/man/man5/a.out.5
@@ -1,4 +1,11 @@
-.TH A.OUT 5 
+.\" Copyright (c) 1980 Regents of the University of California.
+.\" All rights reserved.  The Berkeley software License Agreement
+.\" specifies the terms and conditions for redistribution.
+.\"
+.\"    @(#)a.out.5     6.2 (Berkeley) 5/19/86
+.\"
+.TH A.OUT 5 "May 19, 1986"
+.UC 4

 .SH NAME
 a.out \- assembler and link editor output
 .SH SYNOPSIS
 .SH NAME
 a.out \- assembler and link editor output
 .SH SYNOPSIS


@@ -13,19 +20,53 @@ Both programs make
 .I a.out
 executable if there were no
 errors and no unresolved external references.
 .I a.out
 executable if there were no
 errors and no unresolved external references.

-Layout information as given in the include file for the PDP11 is:
-.PP
+Layout information as given in the include file for the VAX-11 is:

 .nf
 .nf

-.ta 8n +9n +11n
+.ta \w'#define  'u +\w'unsigned  'u +\w'a_dirsize  'u +4n

 .PP
 .PP

-.so /usr/include/a.out.h
+/*
+.ti +\w'/'u
+* Header prepended to each a.out file.
+.ti +\w'/'u
+*/
+struct exec {
+       long    a_magic;        /* magic number */
+       unsigned        a_text; /* size of text segment */
+       unsigned        a_data; /* size of initialized data */
+       unsigned        a_bss;  /* size of uninitialized data */
+       unsigned        a_syms; /* size of symbol table */
+       unsigned        a_entry;        /* entry point */
+       unsigned        a_trsize;       /* size of text relocation */
+       unsigned        a_drsize;       /* size of data relocation */
+};
+
+#define        OMAGIC  0407    /* old impure format */
+#define        NMAGIC  0410    /* read-only text */
+#define        ZMAGIC  0413    /* demand load format */
+
+/*
+.ti +\w'/'u
+* Macros which take exec structures as arguments and tell whether
+.ti +\w'/'u
+* the file has a reasonable magic number or offsets to text\||\|symbols\||\|strings.
+.ti +\w'/'u
+*/
+#define        N_BADMAG(x) \e
+    (((x).a_magic)!=OMAGIC && ((x).a_magic)!=NMAGIC && ((x).a_magic)!=ZMAGIC)
+
+#define        N_TXTOFF(x) \e
+       ((x).a_magic==ZMAGIC ? 1024 : sizeof (struct exec))
+#define N_SYMOFF(x) \e
+       (N_TXTOFF(x) + (x).a_text+(x).a_data + (x).a_trsize+(x).a_drsize)
+#define        N_STROFF(x) \e
+       (N_SYMOFF(x) + (x).a_syms)
+.DT

 .fi
 .PP
 .fi
 .PP

-The file has four sections:
-a header, the program and data text,
-relocation information, and a symbol table
-(in that order).
-The last two may be empty
+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
 if the program was loaded
 with the `\-s' option
 of


@@ -34,57 +75,125 @@ or if the symbols and relocation have been
 removed by
 .IR strip (1).
 .PP
 removed by
 .IR strip (1).
 .PP

-In the header the sizes of each section are given in bytes, but are even.
+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.
 .PP
 When an
 .I a.out
 The size of the header is not included in any of the other sizes.
 .PP
 When an
 .I a.out

-file is loaded into core for execution, three logical segments are
+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.
 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 0407(8), it indicates that the text
+If the magic number in the header is OMAGIC (0407),
+it indicates that the text

 segment is not to be write-protected and shared,
 so the data segment is immediately contiguous
 with the text segment.
 segment is not to be write-protected and shared,
 so the data segment is immediately contiguous
 with the text segment.

-If the magic number is 0410,
-the data segment begins at the first 0 mod 8K byte
+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 begins at the first 0 mod 1024 byte

 boundary following the text segment,
 and the text segment is not writable by the program;
 if other processes are executing the same file,
 they will share the text segment.
 boundary following the text segment,
 and the text segment is not writable by the program;
 if other processes are executing the same file,
 they will share the text segment.

-If the magic number is 411,
-the text segment is again pure, write-protected, and shared,
-and moreover instruction and data space are separated;
-the text and data segment both begin at location 0.
-If the magic number is 0405, the text segment
-is overlaid on an existing (0411 or 0405) text segment
-and the existing data segment is preserved.
+For ZMAGIC format, the text segment begins at a 0 mod 1024 byte boundary
+in the
+.I a.out
+file, the remaining bytes after the header in the first block are
+reserved and should be zero.
+In this case the text and data sizes must both be multiples of 1024 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 very large programs and is the default format produced by
+.IR ld (1).

 .PP
 The stack will occupy the highest possible locations
 .PP
 The stack will occupy the highest possible locations

-in the core image: from 0177776(8) and growing downwards.
+in the core image, growing downwards from USRSTACK (from
+.IR <machine/vmparam.h> ).

 The stack is automatically extended as required.
 The data segment is only extended as requested by
 .IR brk (2).
 .PP
 The stack is automatically extended as required.
 The data segment is only extended as requested by
 .IR brk (2).
 .PP

-The start of the text segment in the file is 020(8);
-the start of the data segment is 020+S\s6\dt\u\s10 (the size of the text)
-the start of the relocation information is
-020+S\s6\dt\u\s10+S\s6\dd\u\s10;
-the start of the symbol table is
-020+2(S\s6\dt\u\s10+S\s6\dd\u\s10)
-if the
-relocation information is present,
-020+S\s6\dt\u\s10+S\s6\dd\u\s10
-if not.
+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 1024 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 which can be gotten easily using N_STROFF.
+The first 4 bytes of the string table are not used for string storage,
+but rather contain the size of the string table; this size INCLUDES
+the 4 bytes, the minimum string table size is thus 4.

 .PP
 The layout of a symbol table entry and the principal flag values
 .PP
 The layout of a symbol table entry and the principal flag values

-that distinguish symbol types are given in the include file.
-Other flag values may occur if an assembly language program
-defines machine instructions.
+that distinguish symbol types are given in the include file as follows:
+.PP
+.nf
+.ta \w'#define  'u +\w'char'u-1u +\w'unsigned  'u+1u +\w'*n_name  'u
+/*
+.ti +\w'/'u
+* Format of a symbol table entry.
+.ti +\w'/'u
+*/
+struct nlist {
+       union {
+               char    *n_name;        /* for use when in-core */
+               long    n_strx; /* index into file string table */
+       } n_un;
+       unsigned char   n_type; /* type flag, i.e. N_TEXT etc; see below */
+       char    n_other;
+       short   n_desc; /* see <stab.h> */
+       unsigned        n_value;        /* value of this symbol (or offset) */
+};
+#define        n_hash  n_desc  /* used internally by ld */
+
+/*
+.ti +\w'/'u
+* Simple values for n_type.
+.ti +\w'/'u
+*/
+#define        N_UNDF  0x0     /* undefined */
+#define        N_ABS   0x2     /* absolute */
+#define        N_TEXT  0x4     /* text */
+#define        N_DATA  0x6     /* data */
+#define        N_BSS   0x8     /* bss */
+#define        N_COMM  0x12    /* common (internal to ld) */
+#define        N_FN    0x1f    /* file name symbol */
+
+#define        N_EXT   01      /* external bit, or'ed in */
+#define        N_TYPE  0x1e    /* mask for all the type bits */
+
+/*
+.ti +\w'/'u
+* Other permanent symbol table entries have some of the N_STAB bits set.
+.ti +\w'/'u
+* These are given in <stab.h>
+.ti +\w'/'u
+*/
+#define        N_STAB  0xe0    /* if any of these bits set, don't discard */
+
+/*
+.ti +\w'/'u
+* Format for namelist values.
+.ti +\w'/'u
+*/
+#define        N_FORMAT        "%08x"
+.fi
+.DT
+.PP
+In the
+.I a.out
+file a symbol's n_un.n_strx field gives an index into the
+string table.  A n_strx value of 0 indicates 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.

 .PP
 If a symbol's type is undefined external,
 and the value field is non-zero,
 .PP
 If a symbol's type is undefined external,
 and the value field is non-zero,


@@ -95,65 +204,49 @@ the name of a common region
 whose size is indicated by the value of the
 symbol.
 .PP
 whose size is indicated by the value of the
 symbol.
 .PP

-The value of a word in the text or data portions which is not
-a reference to an undefined external symbol
-is exactly that value which will appear in core
+The value of a byte in the text or data which is not
+a portion of a reference to an undefined external symbol
+is exactly that value which will appear in memory

 when the file is executed.
 when the file is executed.

-If a word in the text or data portion
+If a byte in the text or data

 involves a reference to an undefined external symbol,
 involves a reference to an undefined external symbol,

-as indicated by the relocation information
-for that word,
-then the value of the word as stored in the file
+as indicated 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
 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 into the word in the file.
+be added to the bytes in the file.

 .PP
 If relocation
 .PP
 If relocation

-information is present, it amounts to one word per
-word of program text or initialized data.
-There is no relocation information if the `relocation info stripped'
-flag in the header is on.
-.PP
-Bits 3-1 of a relocation word indicate the segment referred
-to by the text or data word associated with the relocation
-word:
-.TP
-000
-absolute number
-.br
-.ns
-.TP
-002
-reference to text segment
-.br
-.ns
-.TP
-004
-reference to initialized data
-.br
-.ns
-.TP
-006
-reference to uninitialized data (bss)
-.br
-.ns
-.TP
-010
-reference to undefined external symbol
+information is present, it amounts to eight bytes per
+relocatable datum as in the following structure:

 .PP
 .PP

-Bit 0 of the relocation word indicates, if 1,
-that the
-reference is relative to the pc (e.g. `clr x');
-if 0,
-that
-the reference is to the actual symbol (e.g.,
-`clr *$x').
+.nf
+.ta \w'#define  'u +\w'unsigned  'u +\w'r_symbolnum:24,  'u +4n
+/*
+.ti +\w'/'u
+* Format of a relocation datum.
+.ti +\w'/'u
+*/
+struct relocation_info {
+       int     r_address;      /* address which is relocated */
+       unsigned        r_symbolnum:24, /* local symbol ordinal */
+               r_pcrel:1,      /* was relocated pc relative already */
+               r_length:2,     /* 0=byte, 1=word, 2=long */
+               r_extern:1,     /* does not include value of sym referenced */
+               :4;     /* nothing, yet */
+};
+.fi
+.DT

 .PP
 .PP

-The remainder of the relocation word (bits 15-4)
-contains a symbol number in the case of external
-references, and is unused otherwise.
-The first symbol is numbered 0, the second 1, etc.
+There is no relocation information if a_trsize+a_drsize==0.
+If r_extern is 0, then r_symbolnum is actually a n_type for the relocation
+(i.e. N_TEXT meaning relative to segment text origin.)
+.fi

 .SH "SEE ALSO"
 .SH "SEE ALSO"

-as(1), ld(1), nm(1)
+adb(1), as(1), ld(1), nm(1), dbx(1), stab(5), strip(1)
+.SH BUGS
+Not having the size of the string table in the header is a loss, but
+expanding the header size would have meant stripped executable file
+incompatibility, and we couldn't hack this just now.