Return to a.out.5 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man5

Annotation of cci/usr/src/man/man5/a.out.5, revision 1.1

1.1     ! root        1: .TH A.OUT 5 "25 February 1983"
        !             2: .UC 4
        !             3: .SH NAME
        !             4: a.out \- assembler and link editor output
        !             5: .SH SYNOPSIS
        !             6: .B #include <a.out.h>
        !             7: .SH DESCRIPTION
        !             8: .I A.out
        !             9: is the output file of the assembler
        !            10: .IR as (1)
        !            11: and the link editor
        !            12: .IR ld (1).
        !            13: Both programs make
        !            14: .I a.out
        !            15: executable if there were no
        !            16: errors and no unresolved external references.
        !            17: Layout information as given in the include file for the Tahoe is:
        !            18: .nf
        !            19: .ta \w'#define  'u +\w'unsigned  'u +\w'a_dirsize  'u +4n
        !            20: .PP
        !            21: /*
        !            22: .ti +\w'/'u
        !            23: * Header prepended to each a.out file.
        !            24: .ti +\w'/'u
        !            25: */
        !            26: struct exec {
        !            27:        long    a_magic;        /* magic number */
        !            28:        unsigned        a_text; /* size of text segment */
        !            29:        unsigned        a_data; /* size of initialized data */
        !            30:        unsigned        a_bss;  /* size of uninitialized data */
        !            31:        unsigned        a_syms; /* size of symbol table */
        !            32:        unsigned        a_entry;        /* entry point */
        !            33:        unsigned        a_trsize;       /* size of text relocation */
        !            34:        unsigned        a_drsize;       /* size of data relocation */
        !            35: };
        !            36: 
        !            37: #define        OMAGIC  0407    /* old impure format */
        !            38: #define        NMAGIC  0410    /* read-only text */
        !            39: #define        ZMAGIC  0413    /* demand load format */
        !            40: 
        !            41: /*
        !            42: .ti +\w'/'u
        !            43: * Macros which take exec structures as arguments and tell whether
        !            44: .ti +\w'/'u
        !            45: * the file has a reasonable magic number or offsets to text\||\|symbols\||\|strings.
        !            46: .ti +\w'/'u
        !            47: */
        !            48: #define        N_BADMAG(x) \e
        !            49:     (((x).a_magic)!=OMAGIC && ((x).a_magic)!=NMAGIC && ((x).a_magic)!=ZMAGIC)
        !            50: 
        !            51: #define        N_TXTOFF(x) \e
        !            52:        ((x).a_magic==ZMAGIC ? 1024 : sizeof (struct exec))
        !            53: #define N_SYMOFF(x) \e
        !            54:        (N_TXTOFF(x) + (x).a_text+(x).a_data + (x).a_trsize+(x).a_drsize)
        !            55: #define        N_STROFF(x) \e
        !            56:        (N_SYMOFF(x) + (x).a_syms)
        !            57: .DT
        !            58: .fi
        !            59: .PP
        !            60: The file has five sections:
        !            61: a header, the program text and data,
        !            62: relocation information, a symbol table and a string table (in that order).
        !            63: The last three may be omitted
        !            64: if the program was loaded
        !            65: with the `\-s' option
        !            66: of
        !            67: .I ld
        !            68: or if the symbols and relocation have been
        !            69: removed by
        !            70: .IR strip (1).
        !            71: .PP
        !            72: In the header the sizes of each section are given in bytes.
        !            73: The size of the header is not included in any of the other sizes.
        !            74: .PP
        !            75: When an
        !            76: .I a.out
        !            77: file is executed, three logical segments are
        !            78: set up: the text segment, the data segment
        !            79: (with uninitialized data, which starts off as all 0, following
        !            80: initialized),
        !            81: and a stack.
        !            82: The text segment begins at 0
        !            83: in the core image; the header is not loaded.
        !            84: If the magic number in the header is OMAGIC (0407),
        !            85: it indicates that the text
        !            86: segment is not to be write-protected and shared,
        !            87: so the data segment is immediately contiguous
        !            88: with the text segment.
        !            89: This is the oldest kind of executable program and is rarely used.
        !            90: If the magic number is NMAGIC (0410) or ZMAGIC (0413),
        !            91: the data segment begins at the first 0 mod 1024 byte
        !            92: boundary following the text segment,
        !            93: and the text segment is not writable by the program;
        !            94: if other processes are executing the same file,
        !            95: they will share the text segment.
        !            96: For ZMAGIC format, the text segment begins at a 0 mod 1024 byte boundary
        !            97: in the
        !            98: .I a.out
        !            99: file, the remaining bytes after the header in the first block are
        !           100: reserved and should be zero.
        !           101: In this case the text and data sizes must both be multiples of 1024 bytes,
        !           102: and the pages of the file will be brought into the running image as needed,
        !           103: and not pre-loaded as with the other formats.  This is especially suitable
        !           104: for very large programs and is the default format produced by
        !           105: .IR ld (1).
        !           106: .PP
        !           107: The stack will occupy the highest possible locations
        !           108: in the core image: growing downwards from
        !           109: .lg 0
        !           110: 0xbffff000.
        !           111: .lg 1
        !           112: The stack is automatically extended as required.
        !           113: The data segment is only extended as requested by
        !           114: .IR brk (2).
        !           115: .PP
        !           116: After the header in the file follow the text, data, text relocation
        !           117: data relocation, symbol table and string table in that order.
        !           118: The text begins at the byte 1024 in the file for ZMAGIC format or just
        !           119: after the header for the other formats.  The N_TXTOFF macro returns
        !           120: this absolute file position when given the name of an exec structure
        !           121: as argument.  The data segment is contiguous with the text and immediately
        !           122: followed by the text relocation and then the data relocation information.
        !           123: The symbol table follows all this; its position is computed by the
        !           124: N_SYMOFF macro.  Finally, the string table immediately follows the
        !           125: symbol table at a position which can be gotten easily using N_STROFF.
        !           126: The first 4 bytes of the string table are not used for string storage,
        !           127: but rather contain the size of the string table; this size INCLUDES
        !           128: the 4 bytes, the minimum string table size is thus 4.
        !           129: .PP
        !           130: The layout of a symbol table entry and the principal flag values
        !           131: that distinguish symbol types are given in the include file as follows:
        !           132: .PP
        !           133: .nf
        !           134: .ta \w'#define  'u +\w'char'u-1u +\w'unsigned  'u+1u +\w'*n_name  'u
        !           135: /*
        !           136: .ti +\w'/'u
        !           137: * Format of a symbol table entry.
        !           138: .ti +\w'/'u
        !           139: */
        !           140: struct nlist {
        !           141:        union {
        !           142:                char    *n_name;        /* for use when in-core */
        !           143:                long    n_strx; /* index into file string table */
        !           144:        } n_un;
        !           145:        unsigned char   n_type; /* type flag, i.e. N_TEXT etc; see below */
        !           146:        char    n_other;
        !           147:        short   n_desc; /* see <stab.h> */
        !           148:        unsigned        n_value;        /* value of this symbol (or offset) */
        !           149: };
        !           150: #define        n_hash  n_desc  /* used internally by ld */
        !           151: 
        !           152: /*
        !           153: .ti +\w'/'u
        !           154: * Simple values for n_type.
        !           155: .ti +\w'/'u
        !           156: */
        !           157: #define        N_UNDF  0x0     /* undefined */
        !           158: #define        N_ABS   0x2     /* absolute */
        !           159: #define        N_TEXT  0x4     /* text */
        !           160: #define        N_DATA  0x6     /* data */
        !           161: #define        N_BSS   0x8     /* bss */
        !           162: #define        N_COMM  0x12    /* common (internal to ld) */
        !           163: #define        N_FN    0x1f    /* file name symbol */
        !           164: 
        !           165: #define        N_EXT   01      /* external bit, or'ed in */
        !           166: #define        N_TYPE  0x1e    /* mask for all the type bits */
        !           167: 
        !           168: /*
        !           169: .ti +\w'/'u
        !           170: * Other permanent symbol table entries have some of the N_STAB bits set.
        !           171: .ti +\w'/'u
        !           172: * These are given in <stab.h>
        !           173: .ti +\w'/'u
        !           174: */
        !           175: #define        N_STAB  0xe0    /* if any of these bits set, don't discard */
        !           176: 
        !           177: /*
        !           178: .ti +\w'/'u
        !           179: * Format for namelist values.
        !           180: .ti +\w'/'u
        !           181: */
        !           182: #define        N_FORMAT        "%08x"
        !           183: .fi
        !           184: .DT
        !           185: .PP
        !           186: In the
        !           187: .I a.out
        !           188: file a symbol's n_un.n_strx field gives an index into the
        !           189: string table.  A n_strx value of 0 indicates that no name is associated
        !           190: with a particular symbol table entry.  The field n_un.n_name can be used
        !           191: to refer to the symbol name only if the program sets this up using
        !           192: n_strx and appropriate data from the string table.
        !           193: .PP
        !           194: If a symbol's type is undefined external,
        !           195: and the value field is non-zero,
        !           196: the symbol is interpreted by the loader
        !           197: .I ld
        !           198: as
        !           199: the name of a common region
        !           200: whose size is indicated by the value of the
        !           201: symbol.
        !           202: .PP
        !           203: The value of a byte in the text or data which is not
        !           204: a portion of a reference to an undefined external symbol
        !           205: is exactly that value which will appear in memory
        !           206: when the file is executed.
        !           207: If a byte in the text or data
        !           208: involves a reference to an undefined external symbol,
        !           209: as indicated by the relocation information,
        !           210: then the value stored in the file
        !           211: is an offset from the associated external symbol.
        !           212: When the file is processed by the
        !           213: link editor and the external symbol becomes
        !           214: defined, the value of the symbol will
        !           215: be added to the bytes in the file.
        !           216: .PP
        !           217: If relocation
        !           218: information is present, it amounts to eight bytes per
        !           219: relocatable datum as in the following structure:
        !           220: .PP
        !           221: .nf
        !           222: .ta \w'#define  'u +\w'unsigned  'u +\w'r_symbolnum:24,  'u +4n
        !           223: /*
        !           224: .ti +\w'/'u
        !           225: * Format of a relocation datum.
        !           226: .ti +\w'/'u
        !           227: */
        !           228: struct relocation_info {
        !           229:        int     r_address;      /* address which is relocated */
        !           230:        unsigned        r_symbolnum:24, /* local symbol ordinal */
        !           231:                r_pcrel:1,      /* was relocated pc relative already */
        !           232:                r_length:2,     /* 0=byte, 1=word, 2=long */
        !           233:                r_extern:1,     /* does not include value of sym referenced */
        !           234:                :4;     /* nothing, yet */
        !           235: };
        !           236: .fi
        !           237: .DT
        !           238: .PP
        !           239: There is no relocation information if a_trsize+a_drsize==0.
        !           240: If r_extern is 0, then r_symbolnum is actually a n_type for the relocation
        !           241: (i.e. N_TEXT meaning relative to segment text origin.)
        !           242: .fi
        !           243: .SH "SEE ALSO"
        !           244: adb(1), as(1), ld(1), nm(1), dbx(1), stab(5), strip(1)
        !           245: .SH BUGS
        !           246: Not having the size of the string table in the header is a loss, but
        !           247: expanding the header size would have meant stripped executable file
        !           248: incompatibility, and we couldn't hack this just now.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.