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 2941750..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 "UNIX/32V"
+.\" 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


@@ -14,18 +21,52 @@ Both programs make
 executable if there were no
 errors and no unresolved external references.
 Layout information as given in the include file for the VAX-11 is:
 executable if there were no
 errors and no unresolved external references.
 Layout information as given in the include file for the VAX-11 is:

-.PP

 .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:
+The file has five sections:

 a header, the program text and data,
 a header, the program text and data,

-relocation information, and a symbol table
-(in that order).
-The last two may be empty
+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


@@ -39,38 +80,120 @@ The size of the header is not included in any of the other sizes.
 .PP
 When an
 .I a.out
 .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 512 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.

+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: growing downwards from 80000000(16).
+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
 The stack is automatically extended as required.
 The data segment is only extended as requested by

-.IR break (2).
+.IR brk (2).

 .PP
 .PP

-The start of the text segment in the file is 32(10);
-the start of the data segment is 32+a_text;
-the start of the text relocation is 32+a_text+a_data;
-the start of the data relocation is 32+a_text+a_data+a_trsize;
-the start of the symbol table is 32+a_text+a_data+a_trsize+a_drsize.
+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.
+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,


@@ -96,27 +219,34 @@ defined, the value of the symbol will
 be added to the bytes in the file.
 .PP
 If relocation
 be added to the bytes in the file.
 .PP
 If relocation

-information is present, it amounts to six bytes per
-relocatable dataum.
-There is no relocation information if a_trsize+a_drsize==0.
-The relocation information is structured as
-.nf
-.ta 4n,+17n
+information is present, it amounts to eight bytes per
+relocatable datum as in the following structure:

 .PP
 .PP

+.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 {
 struct relocation_info {

-       long address;   /* relative to current segment */
-       short pcrel:1,  /* if so, segment offset has already */
-               /* been subtracted */
-         length:2,     /* 0=byte, 1=word, 2=long */
-         extern:1,     /* does not include value */
-               /* of symbol referenced */
-         offset:1,     /* already includes origin */
-               /* of this segment (?) */
-         symbolnum:11;
-               /* if extern then symbol table */
-               /* ordinal (0, 1, 2, ...) else */
-               /* segment number (same as symbol types) */
+       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
 };
 .fi

+.DT
+.PP
+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.