A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
-------------------------------------------------------------------------------
a.out
PURPOSE
Provides common assembler and link editor output.
SYNOPSIS
#include <a.out.h>
DESCRIPTION
The as (assembler), compilers (C, VS Pascal, and VS FORTRAN), and ld (link
editor) programs produce an output file (the a.out file by default). The a.out
file is executable if the assembler, compilers, and the link editor do not find
any unresolved external references or errors in the source file.
This file can consist of the following sections: a file header, an auxiliary
header, section headers for each of the file's raw data sections, the raw data
sections, relocation data for each raw data section, line number information
for each raw data section, a symbol table section, and, if long symbols are
used, a strings table. A diagram of this structure follows.
Every a.out does not contain all the sections enumerated. In particular, the
line number, symbol table, and strings table sections are not present if the
program is linked with the -s flag of the ld command or if they were removed by
the strip command.
Comment sections are only present as a result of certain as directives.
Library sections (.lib) are only found in shared library archive members or
programs linked with shared libraries. Initialization sections (.init) are
only found in shared library archive members or programs linked with shared
libraries that are not yet executable. Finally, there are no relocation
sections if the file is executable.
Loading an a.out file into memory for execution causes the creation of three
logical segments: the text segment, the data segment (initialized data followed
by data that is not initialized, the latter effectively being initialized to
all zeros), and a stack.
The text segment occupies a low memory address in the process image, and its
size is static. The data segment follows the text segment. The size of this
segment can be extended using the brk system call. The stack segment begins
near the highest locations and grows toward the data segment as required.
Common Object File Format
Processed November 7, 1990 A.OUT(5,F) 1
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
File Organization:
INCLUDE FILE
+--------------------------------------+
| HEADER DATA |
|--------------------------------------|
| File Header | "filehdr.h"
|--------------------------------------|
| Auxiliary Header Information | "aouthdr.h"
|--------------------------------------|
| ".init" section header | "scnhdr.h"
|--------------------------------------|
| ".text" section header | "
|--------------------------------------|
| ".data" section header | "
|--------------------------------------|
| ".bss" section header | "
|--------------------------------------|
| ".comment" section header | "
|--------------------------------------|
| ".debug" section header | "
|--------------------------------------|
| ".lib" section header | "
|--------------------------------------|
| RAW DATA |
|--------------------------------------|
| ".init" section data (rounded to 4 |
| bytes) |
|--------------------------------------|
| ".text" section data (rounded to 4 |
| bytes) |
|--------------------------------------|
| ".data" section data (rounded to 4 |
| bytes) |
|--------------------------------------|
| ".comment" section data (rounded to |
| 4 bytes) |
|--------------------------------------|
| ".lib" section data (rounded to 4 |
| bytes) |
|--------------------------------------|
| RELOCATION DATA |
|--------------------------------------|
| ".init" section relocation data | "reloc.h"
|--------------------------------------|
| ".text" section relocation data | "
|--------------------------------------|
| ".data" section relocation data | "
+--------------------------------------+
Processed November 7, 1990 A.OUT(5,F) 2
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
+--------------------------------------+
| LINE NUMBER DATA |
|--------------------------------------|
| ".text" section line numbers | "linenum.h"
|--------------------------------------|
| ".data" section line numbers | "
|--------------------------------------|
| SYMBOL TABLE |
|--------------------------------------|
| ".init", ".text", ".data" and ".bss" | "syms.h"
| section symbols | "storclass.h"
|--------------------------------------|
| STRINGS TABLE |
|--------------------------------------|
| ".init", ".text", ".data" and ".bss" |
| section symbols larger than 8 chars |
+--------------------------------------+
OBJECT FILE COMPONENTS:
Header Files:
/usr/include/filehdr.h
/usr/include/aouthdr.h
/usr/include/scnhdr.h
/usr/include/reloc.h
/usr/include/linenum.h
/usr/include/syms.h
/usr/include/storclass.h
Standard File (includes the header files above):
/usr/include/a.out.h
Object file
File Header
The format of the file header is as follows:
struct filehdr {
unsigned short f_magic; /* magic number */
unsigned short f_nscns; /* number of sections */
long f_timdat; /* time & date stamp */
long f_symptr; /* file pointer to symtab */
long f_nsyms; /* number of symtab entries */
unsigned short f_opthdr; /* sizeof(optional hdr) */
unsigned short f_flags; /* flags */
};
The fields in the file header are defined as follows:
f_magic A 2-byte machine type identification number.
Processed November 7, 1990 A.OUT(5,F) 3
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
f_nscns The number of sections in this file.
f_timdat A 4-byte number encoding the time and date that the file was created.
f_symptr A file pointer or offset into the file to the start of the symbol
table section.
f_nsyms The number of symbol table entries.
f_opthdr The size of the auxiliary or optional header. This field is 0 if
there is no header.
f_flags The bits in the f_flags field are defined as follows:
F_RELFLG Relocation information stripped from file
F_EXEC File is executable (that is, no unresolved external
references)
F_LNNO Line numbers stripped from file
F_LSYMS Local symbols stripped from file
F_MINIMAL This is a minimal object file (*.m) output of fextract.
F_SWABD This file has had its bytes swabbed (in names).
F_UPDATE This is a fully bound update file output of ogen.
F_AR16WR This file created on AR16WR machine (for instance, Intel
80286)
F_AR32WR This file created on AR32WR machine (for instance, IBM
PS/2)
F_AR32W This file created on AR32W machine (for instance, IBM
System/370)
F_PATCH File contains "patch" list in optional header
F_NODF (Minimal file only) no decision functions for replaced
functions.
The numerical value of the flags is as follows:
#define F_RELFLG 0000001
#define F_EXEC 0000002
#define F_LNNO 0000004
#define F_LSYMS 0000010
#define F_MINMAL 0000020
#define F_UPDATE 0000040
#define F_SWABD 0000100
Processed November 7, 1990 A.OUT(5,F) 4
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
#define F_AR16WR 0000200
#define F_AR32WR 0000400
#define F_AR32W 0001000
#define F_PATCH 0002000
#define F_NODF 0002000
Auxiliary Header
The format of the auxiliary header is as follows:
typedef struct aouthdr {
short magic; /* magic number - see /etc/magic */
short vstamp; /* version stamp */
long tsize; /* text size in bytes, padded to FW boundary */
long dsize; /* initialized data " " */
long bsize; /* uninitialized data " " */
long entry; /* entry pt. */
long text_start; /* base of text used for this file */
long data_start; /* base of data used for this file */
} AOUTHDR;
The fields in the auxiliary header are defined as follows:
magic File type identification number.
vstamp Number used to identify the file version. The linker fills in this
field upon request.
tsize The size of the .text segment, rounded to the nearest 4-byte
boundary.
dsize The size of the .data segment, rounded to the next 4-byte boundary.
bsize The size of the .bss segment, rounded to the next 4-byte boundary.
entry The starting address of the program at execution time.
text_start The base address of the .text segment at execution time
data_start The base address of the .data segment at execution time
Section Headers
Each raw data section of the COFF file has a corresponding section header with
the following format:
Processed November 7, 1990 A.OUT(5,F) 5
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
struct scnhdr {
char s_name[8]; /* section name */
long s_paddr; /* physical address */
long s_vaddr; /* virtual address */
long s_size; /* section size - in bytes */
long s_scnptr; /* file ptr to raw data for section */
long s_relptr; /* file ptr to relocation entries */
long s_lnnoptr; /* file ptr to line numbers entries */
unsigned short s_nreloc; /* number of relocation entries */
unsigned short s_nlnno; /* number of line number entries */
long s_flags; /* flags */
};
/*
* The low two bytes of s_flags is used as a section "type"
*/
#define STYP_REG 0x00 /* "regular" section: */
/* allocated, relocated, loaded */
#define STYP_DSECT 0x01 /* "dummy" section: */
/* not allocated, relocated,
not loaded */
#define STYP_NOLOAD 0x02 /* "noload" section: */
/* allocated, relocated,
not loaded */
#define STYP_GROUP 0x04 /* "grouped" section: */
/* formed of input sections */
#define STYP_PAD 0x08 /* "padding" section: */
/* not allocated, not relocated,
loaded */
#define STYP_COPY 0x10 /* "copy" section: */
/*for decision function used by
field update;
/* not allocated, not relocated,
loaded; reloc & lineno
entries processed normally */
#define STYP_TEXT 0x20 /* section contains text only */
#define STYP_DATA 0x40 /* section contains data only */
#define STYP_BSS 0x80 /* section contains bss only */
#define S_NEWFUN 0X100 /* new function in an update file*/
#define STYP_INFO 0x200 /* comment section : not allocated
not relocated, not loaded */
#define STYP_OVER 0x400 /* overlay section : relocated
not allocated or loaded */
#define STYP_LIB 0x800 /* for .lib section : same as INFO */
Note: The physical address of a section is its offset from address zero of the
address space. It is NOT necessarily the run-time address.
Relocation Data
Processed November 7, 1990 A.OUT(5,F) 6
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
A word in the text or data segment of memory contains either an actual value or
the value of an offset. If a word in the text or data segment references an
undefined external symbol, its value is an offset from the associated external
symbol. During processing, the link editor defines the external symbol and
adds the value of the symbol to the word in the file.
When relocation information is present, each item that can be relocated is 10
bytes long. The format of the relocation information is as follows:
struct reloc {
long r_vaddr; /* (virtual) address of reference */
long r_symndx; /* index into symbol table */
unsigned short r_type; /* relocation type */
};
The r_vaddr field gives the location of the relocatable reference relative to
the beginning of the segment in which it is defined.
The r_symndex field contains an index, counted from zero, of the symbol table
entry that is referenced.
The r_type field indicates to the link editor the type of relocation that is to
be performed on the relocation entry during the linking process.
The currently defined relocation types are as follows:
#define R_ABS 0
#define R_OFF8 07
#define R_OFF16 010
#define R_SEG12 011
#define R_AUX 013
#define R_DIR16 01
#define R_REL16 02
#define R_IND16 03
#define R_DIR24 04
#define R_REL24 05
#define R_OPT16 014
#define R_IND24 015
#define R_IND32 016
#define R_DIR10 025
#define R_REL10 026
#define R_REL32 027
#define R_DIR32 06
#define R_DIR32S 012
#define R_RELBYTE 017
#define R_RELWORD 020
#define R_RELLONG 021
#define R_PCRBYTE 022
#define R_PCRWORD 023
#define R_PCRLONG 024
Processed November 7, 1990 A.OUT(5,F) 7
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
Line Number Data
When present, there is one line number entry for every "breakpointable" source
line in a section. Line numbers are grouped on a per function basis; the first
entry in a function grouping will have "l_lnno = 0" and, in place of the
physical address, there will be the symbol table index of the function name.
The format of a line number entry is as follows:
struct lineno
{
union
{
long l_symndx ; /* sym. table index of function name
if l_lnno == 0 */
long l_paddr ; /* (physical) address of line number */
} l_addr ;
unsigned short l_lnno ; /* line number */
} ;
Line number entries are used by a symbolic debugger to debug code at the source
level.
Symbol Table Data
The symbol table consists of the following entries:
Processed November 7, 1990 A.OUT(5,F) 8
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
struct syment
{
union
{
char _n_name[SYMNMLEN]; /* old COFF version */
struct
{
long _n_zeros; /* new == 0 */
long _n_offset; /* offset into string table */
} _n_n;
char *_n_nptr[2]; /* allows for overlaying */
} _n;
unsigned long n_value; /* value of symbol */
short n_scnum; /* section number */
unsigned short n_type; /* type and derived type */
char n_sclass; /* storage class */
char n_numaux; /* number of aux. entries */
};
#define SYMNMLEN 8 /* Number of characters in a symbol name */
#define SYMENT struct syment
#define SYMESZ 18 /* sizeof(SYMENT) - on disk */
/* WARNING: size may differ in memory */
/* because of alignment restrictions */
#define n_name _n._n_name
#define n_nptr _n._n_nptr[1]
#define n_zeros _n._n_n._n_zeros
#define n_offset _n._n_n._n_offset
The fields in the symbol table are defined as follows:
_n_name:
The symbol name, which consists of a null-terminated ASCII string, is
contained within the _n_name field,if the length of the name is less
than equal to SYMNMLEN. Otherwise, the first 4 bytes of the field are
zero and the next 4 bytes contain a file pointer into the strings table
section, which contains the name.
Symbol Value
n_value:
The value assigned to a symbol is dependent upon its storage class.
(See "Storage Classes.") In the usual case of interest, relocatable
symbols have a value that is equal to the virtual address of the
symbol. Of course, when a program module is linked with other modules
this value changes.
The full meaning of n_value is summarized in the following table:
Storage Class n_value
C_AUTO stack offset in bytes
Processed November 7, 1990 A.OUT(5,F) 9
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
Storage Class n_value
C_EXT relocatable address
C_STAT relocatable address
C_REG register number
C_LABEL relocatable address
C_MOS offset in bytes
C_ARG stack offset in bytes
C_STRTAG 0
C_MOU 0
C_UNTAG 0
C_TPDEF 0
C_ENTAG 0
C_MOE enumeration value
C_REGPARM register number
C_FIELD bit displacement
C_BLOCK relocatable address
C_FCN relocatable address
C_EOS size
C_FILE pointer to next
C_FILE entry
C_ALIAS tag index
C_HIDDEN relocatable address
Note: The C_FILE entries form a singly linked list in the symbol
table. For the last entry in the symbol table, the value of the
symbol is the index of the first global symbol.
n_scnum:
Relocatable symbols have a section number, n_scnum, of the section in
which they are defined. Otherwise, section numbers have the following
meanings:
#define N_UNDEF 0 /* undefined symbol */
#define N_ABS -1 /* value of symbol is absolute */
#define N_DEBUG -2 /* special debugging symbol
value of symbol is meaningless */
#define N_TV
(unsigned short) -3 /* symbol needs transfer vector
(preload) */
#define P_TV
(unsigned short) -4 /* symbol needs
transfer vector (postload) */
n_type:
The n_type field is primarily for use by a symbolic debugger. The
fundamental type of a symbol packed into the low 4 bits of the n_type
field as follows :
Processed November 7, 1990 A.OUT(5,F) 10
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
#define T_NULL 0
#define T_ARG 1 /* function argument
(only used by compiler) */
#define T_CHAR 2 /* character */
#define T_SHORT 3 /* short integer */
#define T_INT 4 /* integer */
#define T_LONG 5 /* long integer */
#define T_FLOAT 6 /* floating point */
#define T_DOUBLE 7 /* double word */
#define T_STRUCT 8 /* structure */
#define T_UNION 9 /* union */
#define T_ENUM 10 /* enumeration */
#define T_MOE 11 /* member of enumeration */
#define T_UCHAR 12 /* unsigned character */
#define T_USHORT 13 /* unsigned short */
#define T_UINT 14 /* unsigned integer */
#define T_ULONG 15 /* unsigned long */
The high-order bits form the derived type. The derived types are
defined as follows:
#define DT_NON 0 /* no derived type */
#define DT_PTR 1 /* pointer */
#define DT_FCN 2 /* function */
#define DT_ARY 3 /* array */
Type packing constants are defined as follows:
#define N_BTMASK 017
#define N_TMASK 060
#define N_TMASK1 0300
#define N_TMASK2 0360
#define N_BTSHFT 4
#define N_TSHIFT 2
Storage Classes
n_sclass:
The field n_sclass has one of the following values:
#define C_EFCN -1 /* physical end of function */
#define C_NULL 0
#define C_AUTO 1 /* automatic variable */
#define C_EXT 2 /* external symbol */
#define C_STAT 3 /* static */
#define C_REG 4 /* register variable */
#define C_EXTDEF 5 /* external definition */
#define C_LABEL 6 /* label */
#define C_ULABEL 7 /* undefined label */
#define C_MOS 8 /* member of structure */
#define C_ARG 9 /* function argument */
#define C_STRTAG 10 /* structure tag */
Processed November 7, 1990 A.OUT(5,F) 11
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
#define C_MOU 11 /* member of union */
#define C_UNTAG 12 /* union tag */
#define C_TPDEF 13 /* type definition */
#define C_USTATIC 14 /* undefined static */
#define C_ENTAG 15 /* enumeration tag */
#define C_MOE 16 /* member of enumeration */
#define C_REGPARM 17 /* register parameter */
#define C_FIELD 18 /* bit field */
#define C_WKEXT 20 /* Fortran weak extern */
#define C_BLOCK 100 /* ".bb" or ".eb" */
#define C_FCN 101 /* ".bf" or ".ef" */
#define C_EOS 102 /* end of structure */
#define C_FILE 103 /* file name */
#define C_ALIAS 105 /* duplicate tag */
#define C_HIDDEN 106 /* special storage class for external
symbols in dmert public libraries */
#define C_ENDINIT 107 /* special storage class for
.bei and .fei sdb information */
#define C_LFNE 104 /* dummy for line number entries
reformatted as symbol table entries */
Auxiliary Entry Format
n_numaux:
The n_numaux field contains the number of auxiliary entries associated
with this symbol table entry. Currently, a symbol table entry can have
at most one auxiliary entry.
The auxiliary entry provides additional information, and has this
format:
union auxent
{
struct
{
long x_tagndx; /* str, union, or enum tag indx */
union
{
struct
{
unsigned short x_lnno; /* declaration line number */
unsigned short x_size; /* str, union, array size */
} x_lnsz;
long x_fsize; /* size of function */
} x_misc;
union
{
struct /* if ISFCN, tag, or .bb */
{
long x_lnnoptr; /* ptr to fcn line # */
Processed November 7, 1990 A.OUT(5,F) 12
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
long x_endndx; /* entry ndx past block end */
} x_fcn;
struct /* if ISARY, up to 4 dimen. */
{
unsigned short x_dimen[DIMNUM];
} x_ary;
} x_fcnary;
unsigned short x_tvndx; /* tv index */
} x_sym;
struct
{
char x_fname[FILNMLEN];
} x_file;
struct
{
long x_scnlen; /* section length */
unsigned short x_nreloc; /* number of relocation entries */
unsigned short x_nlinno; /* number of line numbers */
} x_scn;
struct
{
long x_tvfill; /* tv fill value */
unsigned short x_tvlen; /* length of .tv */
unsigned short x_tvran[2]; /* tv range */
} x_tv; /* info about .tv section (in auxent of symbol .tv)) */
};
#define AUXENT union auxent
#define AUXESZ 18 /* sizeof(AUXENT) */
#define FILNMLEN 14 /* Number of characters in a file name */
#define DIMNUM 4 /* Number of array dimensions in aux entry */
/* Defines for "special" symbols */
#define _ETEXT "etext"
#define _EDATA "edata"
#define _END "end"
The information in an auxiliary entry cannot be correctly interpreted
without the symbol table entry to which it belongs. The order of
entries within the symbol table is significant.
Strings Table
The strings table contains the names of symbols that are longer than 8
characters. If present, the first 4 bytes contain the length, in bytes, of the
strings table, including the length bytes. Thus, offsets into the strings
table are greater than or equal to 4. The remainder of the table is a sequence
Processed November 7, 1990 A.OUT(5,F) 13
A.OUT(5,F) AIX Technical Reference A.OUT(5,F)
of null-terminated ASCII strings. If the n_zeros field in a symbol table entry
is 0, the n_offset field gives the offset into the strings table of the name
for the symbol.
Access Routines
To ease program access to the COFF file sections, you should use the access
routines in the library libld. Within the library libld, there exist routines
to open, close, and access sections of a COFF file.
RELATED INFORMATION
In Volume 1 of this book see: "ldahread," "ldclose, ldaclose," "ldfcn,"
"ldfhread," "ldgetname," "ldlread, ldlinit, ldlitem," "ldlseek, ldnlseek,"
"ldohseek," "ldopen, ldaopen," "ldrseek, ldnrseek," "ldshread, ldnshread,"
"ldsseek, ldnsseek," "ldtbindex," "ldtbread," and "ldtbseek."
The config program and the as, cc, dump, ld, nm, dbx, size, strip, and what
commands in the AIX Operating System Commands Reference.
Processed November 7, 1990 A.OUT(5,F) 14