A.OUT(5)	    UNIX Programmer's Manual		 A.OUT(5)


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.  Lay-
     out information as given in the include file for the PDP11
     is:

     /*
      * Header prepended to each a.out file.
      */
     struct   exec {
	      int	    a_magic;	  /* magic number */
	      unsigned int  a_text;	  /* size of text segment */
	      unsigned int  a_data;	  /* size of initialized data */
	      unsigned int  a_bss;	  /* size of uninitialized data */
	      unsigned int  a_syms;	  /* size of symbol table */
	      unsigned int  a_entry;	  /* entry point */
	      unsigned int  a_unused;	  /* not used */
	      unsigned int  a_flag;	  /* relocation info stripped */
     };

     #define  NOVL	    15		  /* number of overlays */
     struct   ovlhdr {
	      int	    max_ovl;	  /* maximum overlay size */
	      unsigned int  ov_siz[NOVL]; /* size of i'th overlay */
     };

     struct   xexec {
	      struct exec e;
	      struct ovlhdr o;
     };

     #define  A_MAGIC1	    0407	  /* normal */
     #define  A_MAGIC2	    0410	  /* read-only text */
     #define  A_MAGIC3	    0411	  /* separated I&D */
     #define  A_MAGIC4	    0405	  /* overlay */
     #define  A_MAGIC5	    0430	  /* auto-overlay (nonseparate) */
     #define  A_MAGIC6	    0431	  /* auto-overlay (separate) */

     /*
      * Macros which take exec structures as arguments and tell whether
      * the file has a reasonable magic number or offset to text.
      */
     #define  N_BADMAG(x) \
	      (((x).a_magic)!=A_MAGIC1 && ((x).a_magic)!=A_MAGIC2 && \
	      ((x).a_magic)!=A_MAGIC3 && ((x).a_magic)!=A_MAGIC4 && \


Printed 11/26/99	 January 9, 1994			1


A.OUT(5)	    UNIX Programmer's Manual		 A.OUT(5)


	      ((x).a_magic)!=A_MAGIC5 && ((x).a_magic)!=A_MAGIC6)

     #define  N_TXTOFF(x) \
	      ((x).a_magic==A_MAGIC5 || (x).a_magic==A_MAGIC6 ? \
	      sizeof(struct ovlhdr) + sizeof(struct exec) : sizeof(struct exec))

     /*
      * The following were added as part of the new object file format.  They
      * call functions because calculating the sums of overlay sizes was too
      * messy (and verbose) to do 'inline'.
      *
      * NOTE: if the magic number is that of an overlaid object the program
      * must pass an extended header ('xexec') as the argument.
     */

     off_t    n_stroff(), n_symoff(), n_datoff(), n_dreloc(), n_treloc();

     #define  N_STROFF(e) (n_stroff(&e))
     #define  N_SYMOFF(e) (n_symoff(&e))
     #define  N_DATOFF(e) (n_datoff(&e))
     #define  N_DRELOC(e) (n_dreloc(&e))
     #define  N_TRELOC(e) (n_treloc(&e))

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

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

     When an a.out file is executed, three or four logical seg-
     ments are set up: the text segment, a possible text overlay
     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.

     Non-overlaid objects: If the magic number in the header is
     A_MAGIC1 (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.  This is the
     oldest kind of executable program and is the default; it
     should not be used for production binaries.  If the magic
     number is A_MAGIC2 (0410), the data segment begins at the
     first 0 mod 8K 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.  If the magic number is A_MAGIC3 (0411), the
     text segment is again pure, write-protected, and shared, and


Printed 11/26/99	 January 9, 1994			2


A.OUT(5)	    UNIX Programmer's Manual		 A.OUT(5)


     moreover instruction and data space are separated; the text
     and data segment both begin at location 0.  This format is
     only runnable on processors which support separate instruc-
     tion and data space but can provide significantly more data
     space than an A_MAGIC2 format of the same object.

     Text replacement objects : If the magic number is A_MAGIC4
     (0405), the text segment is overlaid on an existing non-
     overlaid pure (A_MAGIC2 or A_MAGIC3) or text replacement
     (A_MAGIC4) text segment and the existing data segment is
     preserved.  The text segment of the previous memory image
     must be the same size as that of the text replacement object
     being loaded.  There is, unfortunately, no loader support to
     help achieve this requirement.  The text replacement format
     is useful for objects which need a large amount of data
     space on non-separate I&D processors.

     Overlaid objects : If the magic number is A_MAGIC5 (0430), a
     base text segment is write-protected and shared and is fol-
     lowed by a text overlay segment.  There are a maximum of
     NOVL overlays, all pure and shared.  The base segment runs
     from 0 to txtsiz.	The overlay region begins at the next 0
     mod 8k byte boundary, which is as large as the largest over-
     lay.  When running, any one of the overlays can be mapped
     into this region.	The data segment begins at the following
     0 mod 8k byte boundary.  If the magic number is A_MAGIC6
     (0431), the situation is the same as for type A_MAGIC5
     except that instruction and data spaces are separated and
     both begin at location 0.	As with the A_MAGIC3 format, an
     a.out in A_MAGIC6 format can only be run on a processor
     which supports separate I&D, but again can provide signifi-
     cantly more data space than A_MAGIC5 format.  Both A_MAGIC5
     and A_MAGIC6 executable files have a second header between
     the normal a.out header and the start of the text image; it
     contains the maximum overlay size and the sizes of each of
     the overlays.  The text images of the overlays follow the
     text in the object file.

     The stack segment will occupy the highest possible locations
     in the core image: growing downwards from 0177776(8).  The
     stack segment is automatically extended as required.  The
     data segment is only extended as requested by brk(2).

     The include file a.out.h defines _AOUT_INCLUDE_, the include
     file nlist.h does not.  This permits compile time initiali-
     zation of the n_name field for programs that are not looking
     at the executable header.

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


Printed 11/26/99	 January 9, 1994			3


A.OUT(5)	    UNIX Programmer's Manual		 A.OUT(5)


     struct   nlist {
     #ifdef   _AOUT_INCLUDE_
	      union {
			    char *n_name;/* In memory address of symbol name */
			    off_t n_strx;/* String table offset (file) */
	      } n_un;
     #else
	      char	    *n_name;   /* symbol name (in memory) */
     #endif
	      u_char	    n_type;    /* Type of symbol - see below */
	      char	    n_ovly;    /* Overlay number */
	      u_int	    n_value;   /* Symbol value */
     };

     /*
      * Simple values for n_type.
      */
     #define  N_UNDF	    0x0        /* undefined */
     #define  N_ABS	    0x1        /* absolute */
     #define  N_TEXT	    0x2        /* text symbol */
     #define  N_DATA	    0x3        /* data symbol */
     #define  N_BSS	    0x4        /* bss symbol */
     #define  N_REG	    0x14       /* register name */
     #define  N_FN	    0x1f       /* file name symbol */

     #define  N_EXT	    0x20       /* external bit, or'ed in */
     #define  N_TYPE	    0x1f       /* mask for all the type bits */

     /*
      * Format for namelist values.
      */
     #define  N_FORMAT	    "%06o"

     If a symbol's type is undefined external, and the value
     field is non-zero, the symbol is interpreted by the loader
     ld as the name of a common region whose size is indicated by
     the value of the symbol.

     The value of a word in the text or data which is not a por-
     tion of a reference to an undefined external symbol is
     exactly that value which will appear in memory when the file
     is executed.  If a word in the text or data involves a
     reference to an undefined external symbol, 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 be
     added into the word in the file.

     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'


Printed 11/26/99	 January 9, 1994			4


A.OUT(5)	    UNIX Programmer's Manual		 A.OUT(5)


     flag in the header is on.	Automatic-overlay (A_MAGIC5 and
     A_MAGIC6) files do not contain relocation information.

     Bits 1-3 of a relocation word indicate the segment referred
     to by the text or data word associated with the relocation
     word:

     000  absolute number
     002  reference to text segment
     004  reference to initialized data
     006  reference to uninitialized data (bss)
     010  reference to undefined external symbol

     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').

     The remainder of the relocation word (bits 15-4) contains a
     symbol number in the case of external references, and is
     unused otherwise.

     The string table begins with a longword containing the
     length of the string table (including the longword itself).
     All strings are null terminated.

     The first symbol is numbered 0, the second 1, etc.

SEE ALSO
     as(1), ld(1), nm(1), strip(1), nlist(3)

BUGS
     The current implementation places a maximum length of 32
     characters for symbol names in a.out files.  This is (rela-
     tively) easily raised with the caveat that the linker and
     other programs which look at symbol tables will slow down
     even more than they already have.

     The 4BSD a.out format has been implemented. This involved
     modifying the first phase of the C compiler (/lib/c0), the
     assembler (/bin/as), the debugger adb(1), the linker ld(1),
     and then simply porting the 4.3BSD/Net-2 ar(1), nm(1), ran-
     lib(1), strip(1) and nlist(3).

     As part of this effort the include file short_names.h has
     gone away.


Printed 11/26/99	 January 9, 1994			5


 
Generated: 2009-03-18
Generated by man2html V0.24
page hit count: 782
Valid CSS Valid XHTML 1.0 Strict