BSD 4_4 release

[unix-history] / usr / src / contrib / sun.sharedlib / man / man5 / a.out.5

.\" This source code is a product of Sun Microsystems, Inc. and is provided
.\" for unrestricted use provided that this legend is included on all tape
.\" media and as a part of the software program in whole or part.  Users
.\" may copy or modify this source code without charge, but are not authorized
.\" to license or distribute it to anyone else except as part of a product or
.\" program developed by the user.
.\"
.\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC.
.\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY
.\" OF SUCH SOURCE CODE FOR ANY PURPOSE.  IT IS PROVIDED "AS IS" WITHOUT
.\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND.  SUN MICROSYSTEMS, INC. DISCLAIMS
.\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN
.\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT,
.\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY.
.\" 
.\" This source code is provided with no support and without any obligation on
.\" the part of Sun Microsystems, Inc. to assist in its use, correction, 
.\" modification or enhancement.
.\"
.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
.\" SOURCE CODE OR ANY PART THEREOF.
.\"
.\" Sun Microsystems, Inc.
.\" 2550 Garcia Avenue
.\" Mountain View, California 94043
.\"
.\" Copyright (c) 1991 Sun Microsystems, Inc.
.\"
.\" @(#)a.out.5 1.32 90/01/30 SMI; from UCB 4.2
.TH A.OUT 5 "18 February 1988"
.SH NAME
a.out \- assembler and link editor output format
.SH SYNOPSIS
.nf
.ft B
#include <a.out.h>
#include <stab.h>
#include <nlist.h>
.ft R
.fi
.SH AVAILABILITY
.LP
Sun-2, Sun-3, and Sun-4 systems only.
For Sun386i systems refer to
.BR coff (5).
.SH DESCRIPTION
.IX  "a.out file"  ""  "\fLa.out\fP \(em assembler and link editor output"
.IX  "assembler output"  ""  "assembler output \(em \fLa.out\fP"
.IX  "link editor output"  ""  "link editor output \(em \fLa.out\fP"
.LP
.B a.out
is the output format of the assembler
.BR as (1)
and the link editor
.BR ld (1).
The link editor makes
.B a.out
executable files.
.LP
A file in
.B a.out
format consists of: a header, the program text, program data, text
and data relocation information, a symbol table,
and a string table (in that order).
In the header, the sizes of each section are given in bytes.  The
last three sections may be absent if the program was loaded with
the
.B \-s
option of
.B ld
or if the symbols and relocation have been removed by
.BR strip (1).
.LP
The machine type in the header indicates the type of hardware on
which the object code can be executed.   Sun-2 code runs on
Sun-3 systems, but not vice versa.  Program files predating release
3.0 are recognized by a machine type of
.RB ` 0 '.
Sun-4 code may not be run on Sun-2 or Sun-3, nor vice versa.
.SS Header
.LP
The header consists of a
.B exec
structure.  The
.B exec
structure has the form:
.LP
.RS
.nf
.ta 1i 2.0i 3.0i
.ft B
struct exec {
	unsigned char	a_dynamic:1;	/* has a __DYNAMIC */
	unsigned char	a_toolversion:7;	/* version of toolset used to create this file */
	unsigned char	a_machtype;	/* machine type */
	unsigned short	a_magic;	/* magic number */
	unsigned long	a_text;		/* size of text segment */
	unsigned long	a_data;		/* size of initialized data */
	unsigned long	a_bss;		/* size of uninitialized data */
	unsigned long	a_syms;		/* size of symbol table */
	unsigned long	a_entry;	/* entry point */
	unsigned long	a_trsize;	/* size of text relocation */
	unsigned long	a_drsize;	/* size of data relocation */
};
.ft R
.fi
.DT
.RE
.LP
The members of the structure are:
.TP 15
.B a_dynamic
.B 1
if the
.B a.out
file is dynamically linked or is a shared object,
.B 0
otherwise.
.TP
.B a_toolversion
The version number of the toolset
.RB ( as ,
.BR ld ,
etc.) used to create the file.
.TP
.B a_machtype
One of the following:
.RS
.TP 12
.B 0
pre-3.0 executable image
.TP
.SB M_68010
executable image using only \s-1MC\s068010 instructions that can run
on Sun-2 or Sun-3
systems.
.TP
.SB M_68020
executable image using \s-1MC\s068020 instructions that can run only
on Sun-3
systems.
.TP
.SB M_SPARC
executable image using \s-1SPARC\s0 instructions that can run only
on Sun-4
systems.
.RE
.TP 15
.B a_magic
One of the following:
.RS
.TP 12
.SB OMAGIC
An text executable image which is not to be
write-protected, so the data segment is immediately contiguous with the
text segment.
.TP
.SB NMAGIC
A write-protected text executable image.
The data segment begins at the first segment boundary following
the text segment, and the text segment is not writable by the program.
When the image is started with
.BR execve (2V),
the entire text and data segments will be read into memory.
.TP
.SB ZMAGIC
A page-aligned text executable image.
the data segment begins at the first segment boundary following
the text segment, and the text segment is not writable by the program.
The text and data sizes are both multiples of the page size,
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 the default format produced by
.BR ld (1).
.RE
.IP
The macro
.SB N_BADMAG
takes an
.B exec
structure as an argument; it evaluates to 1 if the
.B a_magic
field of that structure is invalid, and evaluates to 0 if it is valid.
.TP 15
.B a_text
The size of the text segment, in bytes.
.TP
.B a_data
The size of the initialized portion of the data segment, in bytes.
.TP
.B a_bss
The size of the \*(lquninitialized\*(rq portion of the data segment, in bytes.
This portion is actually initialized to zero.  The zeroes are not stored in the
.B a.out
file; the data in this portion of the data segment is zeroed out when it is
loaded.
.TP
.B a_syms
The size of the symbol table, in bytes.
.TP
.B a_entry
The virtual address of the entry point of the program; when the image is
started with
.BR execve ,
the first instruction executed in the image is at this address.
.TP
.B a_trsize
The size of the relocation information for the text segment.
.TP
.B a_drsize
The size of the relocation information for the data segment.
.LP
The macros
.SM
.BR N_TXTADDR ,
.SM
.BR N_DATADDR ,
and
.SB N_BSSADDR
give the memory addresses at which the text, data, and bss segments,
respectively, will be loaded.
.LP
In the
.SB ZMAGIC
format, the size of the header is included in the size of the text
section; in other formats, it is not.
.LP
When an
.B 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 data), and a stack.  For the
.SB ZMAGIC
format, the header is loaded with the text segment; for other
formats it is not.
.LP
Program execution begins at the address given by the value of
the
.B a_entry
field. 
.LP
The stack starts at the highest possible location in the memory image,
and grows downwards.  The stack is automatically extended as required.
The data segment is extended as requested by
.BR brk (2)
or
.BR sbrk .
.SS "Text and Data Segments"
.LP
The text segment begins at the start
of the file for
.SB ZMAGIC
format, or just after the header for the other formats.  The
.SB N_TXTOFF
macro returns this absolute file position when given an
.B 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
.SB N_DATOFF
macro returns the absolute file position of the beginning of the data segment
when given an
.B exec
structure as argument.
.SS Relocation
.LP
The relocation information appears after the text and data segments.
The
.SB N_TRELOFF
macro returns the absolute file position of the relocation information
for the text segment, when given an
.B exec
structure as argument.
The
.SB N_DRELOFF
macro returns the absolute file position of the relocation information
for the data segment, when given an
.B exec
structure as argument.
There is no relocation information if
.BR a_trsize + a_drsize ==0.
.SS "Relocation (Sun-2 and Sun-3 Systems)"
If a byte 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 is added to the bytes in the file.
If a byte involves a reference to a relative location, or
relocatable segment, then the value stored in the file is an
offset from the associated segment.
.br
.ne 12
.LP
If relocation information is present, it amounts to eight bytes per
relocatable datum as in the following structure:
.LP
.RS
.nf
.ft B
.ta +4n; +8n; +8n; +10n
struct reloc_info_68k {
	long 	r_address;	/* address which is relocated */
unsigned int	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 */
	r_baserel:1,	/* linkage table relative */
	r_jmptable:1,	/* pc-relative to jump table */
	r_relative:1,	/* relative relocation */
	:1;
};

.fi
.RE
.LP
If
.B r_extern
is 0, then
.B r_symbolnum
is actually an
.B n_type
for the relocation (for instance,
.SB N_TEXT
meaning relative to segment text origin.)
.SS "Relocation (Sun-4 System)"
.LP
If a byte 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 ignored. Unlike the Sun-2 and Sun-3 system, the offset from the
associated symbol is kept with the relocation record.  When the file
is processed by the link editor and the external symbol becomes
defined, the value of the symbol is added to this offset, and the
sum is inserted into the bytes in the text or data segment.
.LP
If relocation information is present, it amounts to twelve bytes per
relocatable datum as in the following structure:
.LP
.nf
.ft B
.ta 4n; +22n; +22n; +22n; +8n; +8n
enum reloc_type
{
	\s-1RELOC_8\s0,	\s-1RELOC_16\s0,	\s-1RELOC_32\s0,	/* simplest relocs */
	\s-1RELOC_DISP8\s0,	\s-1RELOC_DISP16\s0,	\s-1RELOC_DISP32\s0,	/* Disp's (pc-rel) */
	\s-1RELOC_WDISP30\s0,	\s-1RELOC_WDISP22\s0,	/* \s-1SR\s0 word disp's */
	\s-1RELOC_HI22\s0,	\s-1RELOC_22\s0,	/* \s-1SR\s0 22-bit relocs */
	\s-1RELOC_13\s0,	\s-1RELOC_LO10\s0,	/* \s-1SR\s0 13&10-bit relocs */
	\s-1RELOC_SFA_BASE\s0,	\s-1RELOC_SFA_OFF13\s0,	/* \s-1SR S.F.A.\s0 relocs */
	\s-1RELOC_BASE10\s0,	\s-1RELOC_BASE13\s0,	\s-1RELOC_BASE22\s0,	/* base_relative pic */
	\s-1RELOC_PC10\s0,	\s-1RELOC_PC22\s0,	/* special pc-rel pic*/
	\s-1RELOC_JMP_TBL\s0,	/* jmp_tbl_rel in pic */
	\s-1RELOC_SEGOFF16\s0,	/* ShLib offset-in-seg */
	\s-1RELOC_GLOB_DAT\s0,	\s-1RELOC_JMP_SLOT\s0,	\s-1RELOC_RELATIVE\s0,	/* rtld relocs */
};
.sp .5
.ne 9
.ta 4n; +18n; +10n; +10n
struct reloc_info_sparc	/* used when header.a_machtype == M_SPARC */
{
	unsigned long int	r_address;		/* relocation addr (offset in segment) */
	unsigned int	r_index	:24;	/* segment index or symbol index */
	unsigned int	r_extern	:\01;	/* if F, r_index==SEG#; if T, SYM idx */
	int	:\02;		/* <unused> */
	enum reloc_type	r_type	:\05;	/* type of relocation to perform */
	long int	r_addend;		/* addend for relocation value */
};
.fi
.ft
.LP
If
.B r_extern
is 0, then
.B r_index
is actually a
.B n_type
for the relocation (for instance,
.SB N_TEXT
meaning relative to segment text origin.)
.SS Symbol Table
.LP
The
.SB N_SYMOFF
macro returns the absolute file position of the symbol table when given an
.B exec
structure as argument.
Within this symbol table, distinct symbols point to disjoint
areas in the string table (even when two symbols have the same name).
The string table immediately follows the symbol table; the
.SB N_STROFF
macro returns the absolute file position of the string table when given an
.B exec
structure as argument.
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
.I includes
the 4 bytes; thus, the minimum string table size is 4.
Layout information as given in the include file for the Sun system is
shown below.
.LP
The layout of a symbol table entry and the principal flag values
that distinguish symbol types are given in the include file as follows:
.LP
.nf
.ft B
.ta 6; +6; +4; +10
struct nlist {
	union {
		char	*n_name;	/* for use when in-memory */
		long	n_strx;	/* index into file string table */
	} n_un;
	unsigned char	n_type;		/* type flag, that is, \s-1N_TEXT\s0 etc; see below */
	char	n_other;
	short	n_desc;		/* see <stab.h> */
	unsigned	n_value;		/* value of this symbol (or adb offset) */
};
#define	n_hash	n_desc		/* used internally by ld */
/*
* Simple values for n_type.
*/
#define	\s-1N_UNDF\s0	0x0		/* undefined */
#define	\s-1N_ABS\s0	0x2		/* absolute */
#define	\s-1N_TEXT\s0	0x4		/* text */
#define	\s-1N_DATA\s0	0x6		/* data */
#define	\s-1N_BSS\s0	0x8		/* bss */
#define	\s-1N_COMM\s0	0x12		/* common (internal to ld) */
#define	\s-1N_FN\s0	0x1f		/* file name symbol */
#define	\s-1N_EXT\s0	01		/* external bit, or'ed in */
#define	\s-1N_TYPE\s0	0x1e		/* mask for all the type bits */
.sp .5v
/*
* Other permanent symbol table entries have some of the \s-1N_STAB\s0 bits set.
* These are given in <stab.h>
*/
#define	\s-1N_STAB\s0	0xe0		/* if any of these bits set, don't discard */
.ft
.fi
.LP
In the
.B a.out
file a symbol's
.B n_un.n_strx
field gives an index into the string
table.  A
.B n_strx
value of 0 indicates that no name is associated with a
particular symbol table entry.  The field
.B n_un.n_name
can be used to
refer to the symbol name only if the program sets this up using
.B n_strx
and appropriate data from the string table.  Because of the union in
the
.B nlist
declaration, it is impossible in C to statically initialize
such a structure.  If this must be done (as when using
.BR nlist (3V))
include the file
.BR <nlist.h> ,
rather than
.BR <a.out.h> .
This contains the declaration without the union.
.LP
If a symbol's type is undefined external, and the value field is
non-zero, the symbol is interpreted by the loader
.B ld
as the name of a common region whose size
is indicated by the value of the symbol.
.SH "SEE ALSO"
.BR adb (1),
.BR as (1),
.BR cc (1V),
.BR dbx (1),
.BR ld (1),
.BR nm (1),
.BR strip (1),
.BR brk (2),
.BR nlist (3V),
.BR coff (5)