A.OUT(5) COMMAND REFERENCE 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 the a.out file executable if there were no errors and no unresolved external references. Layout information as given in the include file /usr/include/a.out.h is: /* * Header for OMAGIC (0407) a.out files */ struct exec { long a_magic; /* magic number (0407) */ 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 */ }; /* * Header for ZMAGIC (0413) a.out files */ struct zexec { long a_magic; /* magic number (0413) */ 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 */ unsigned a_archclass; /* target architecture class */ unsigned a_flags; /* characteristics of a.out file */ unsigned a_textoff; /* offset from start of file to text */ unsigned a_dataoff; /* offset from start of file to data */ unsigned a_textaddr; /* process (virtual) address of text */ unsigned a_dataaddr; /* process (virtual) address of data */ unsigned a_bssaddr; /* process (virtual) address of bss */ }; /* * Supported values for a_magic */ Printed 3/13/89 1
A.OUT(5) COMMAND REFERENCE A.OUT(5) #define OMAGIC 0407 /* old impure format */ #define ZMAGIC 0413 /* demand load format */ The file has five sections: a header, the program text and data, 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 ld or if the symbols and relocation have been removed by strip(1). The header provides the sizes of the five sections, either directly or indirectly, in bytes. The size of the header is not included in any of the other sizes but may be determined using the N_TXTOFF macro (below). When an a.out file is executed, three logical segments are set up: text, data and stack. Text always starts off at location zero in process space. A data segment consists of initialized data followed by uninitialized data. Initialized data is filled with starting values from the file. Uninitialized data is filled with zeros. The header is never loaded into process space. The remaining rules for handling of the three segments depend on the type of file being handled, as determined by the magic number. For OMAGIC (0407) files the text and data are loaded contiguously in a single region of memory that is writeable and not shared. Text in the file starts immediately following the header. Data in the file starts immediately following text. Text and data have the relationship to one another in the file that they are to have in process space. This is the oldest kind of executable program and is used primarily for unbound object modules intended as input to ld(1) . For ZMAGIC (0413) files text is paged from the a.out file and shared by multiple users. Text starts in byte location 1024 of the file to allow direct paging. Text is not writeable. The bytes after the header and before the text are reserved and must be zero. Text pages will be brought into the running image as needed, and not preloaded as with the other formats. This is especially suitable for very large programs and is the default format produced by ld(1). Data begins at the first 8192-byte boundary (in process space) following text. Uninitialized data immediately follows initialized data. The text and data of a ZMAGIC file may appear in the file in the same relation they will occupy in process space. The small amount of virtual space wasted by the 8192-byte spacing requirement is needed so that the file will be executable on machines with a page size that large. The associated unused space in the file is avoided by using the Printed 3/13/89 2
A.OUT(5) COMMAND REFERENCE A.OUT(5) additional fields in the new header. The additional members in the zexec structure may all be zero if the appropriate values of the first ones are provided. Nonzero values of the new members provide performance or functionality extensions. A_archclass allows execve(2) to determine whether a given file is likely to run successfully on this machine. A nonzero value indicates an architecture class which must be appropriate for the program to run. The allowable architectures are enumerated in /usr/include/a.out.h. A_flags provide special options related to the a.out file format and are enumerated in /usr/include/a.out.h. A_textoff is the number of bytes from the start of the file to the start of text. This should always be 1024 for ZMAGIC files. A_dataoff is the number of bytes from the start of the file to the start of data. A nonzero value means that it should be used for finding the start of data in the file rather than inferring the start from the header and text sizes. A_textaddr is the virtual address for which text was relocated. This will be zero for all UTek files, but may not be for files targeted at non- UTek execution environments. A_dataaddr is the virtual address for which data was relocated. A nonzero value means that data should be loaded at that address rather than one inferred from the text size. A_bssaddr is the virtual address of the start of uninitialized data. A nonzero value means that uninitialized data starts there rather than immediately following initialized data. It is only used for files which run in a non-UTek environment. The stack will occupy the highest possible locations in the core image: the actual address depends on the machine and version of UTek being used. The stack is automatically extended as required. The data segment is only extended as requested by brk(2) or mmap(2). /* * Macros which take exec structures as arguments and tell whether * the file has a reasonable magic number or offsets to * text|symbols|strings. */ #define N_BADMAG(x) \ (((x).a_magic)!=OMAGIC && ((x).a_magic)!=ZMAGIC) #define N_TXTOFF(x) \ ((x).a_magic==ZMAGIC ? 1024 : sizeof (struct exec)) #define N_SYMOFF(x) \ /* see ``/usr/include/a.out.h'' */ #define N_STROFF(x) \ /* see ``/usr/include/a.out.h'' */ Printed 3/13/89 3
A.OUT(5) COMMAND REFERENCE A.OUT(5) After the header in the file follow the text, data, text and data relocation, symbol table and string table in that order. The N_TXTOFF macro returns the absolute file position of the start of text when given the name of an exec or newexec 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. The layout of a symbol table entry and the principal flag values that distinguish symbol types are given in the include file as follows: /* * Format of a symbol table entry. */ 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; 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 */ /* * Simple values for n_type. */ #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 */ /* * Other permanent symbol table entries have some of the N_STAB bits set. * These are given in <stab.h> */ Printed 3/13/89 4
A.OUT(5) COMMAND REFERENCE A.OUT(5) #define N_STAB 0xe0 /* if any of these bits set, */ /* don't discard */ /* * Format for namelist values. */ #define N_FORMAT "%08x" In the 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. 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 byte in the text or data which is not a portion of a reference to an undefined external symbol is exactly that value which will appear in memory when the file is executed. 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 will be added to the bytes in the file. If relocation information is present, it amounts to eight bytes per relocatable datum as in the following structure: /* * Format of a relocation datum. */ struct relocation_info { int r_address; /* address which is relocated */ unsigned r_symbolnum:24, /* local symbol ordinal, */ /* or type if !extern */ r_pcrel:1, /* was relocated pc relative already */ r_length:2, /* 0=byte, 1=word, 2=long, or */ /* one of LEN_XXX */ r_extern:1, /* does not include value of */ /* sym referenced */ r_byteorder:2, /* byte order on relocated item */ :2; /* nothing, yet */ }; /* * r_byteorder values Printed 3/13/89 5
A.OUT(5) COMMAND REFERENCE A.OUT(5) */ #define R_LSB 0 /* LSB first */ #define R_MSB 2 /* MSB first */ #define R_DISP 3 /* MSB first, 16032 displacement operand */ #define R_M78K 1 /* r_length contains a LEN_XXX symbol */ /* * Special r_length values when r_byteorder==R_M78K: * These all describe fields in the M78k architecture. */ /* * These values are meaningful when r_byteorder==R_M78K and r_pcrel==0: */ #define LEN_LOW16 0 /* 16-bit unsigned short; store value&0xFFFF */ #define LEN_HIGH16 1 /* 16-bit unsigned short; store value>>16 */ #define LEN_LIT16 2 /* 16-bit unsigned short; flag overflow */ #define LEN_2LIT16 3 /* two 16-bit shorts in adjacent longwords */ /* * For LEN_HIGH16 when r_extern==0, the low 16 bits of the operand to the * hi16(x) function are stored in the high 16 bits of r_symbolnum. * LEN_LIT16 is similar to (r_byteorder==R_MSB && r_length==1) but may be * extended in future to accommodate load-time instruction synthesis. */ /* * These values are meaningful when r_byteorder==R_M78K and r_pcrel==1: */ #define LEN_OFF16 0 /* 16-bit offset */ #define LEN_OFF26 1 /* 26-bit offset */ There is no relocation information if a_trsize + a_drsize==0. If r_extern is 0, then the low eight bits of r_symbolnum actually contain a n_type for the relocation (i.e. N_TEXT meaning relative to segment text origin). The high 16 bits of r_symbolnum contain zero, except when r_byteorder==R_M78K and r_pcrel==0 and r_length==LEN_HIGH16, when the high 16 bits of r_symbolnum contain the low 16 bits of the (unrelocated) argument to hi16. (The high 16 bits of the argument are stored in the LIT16 field of the instruction to be relocated.) When r_byteorder equals 1, the r_length value supports the Motorola M78000 architecture. The interpretation of r_length depends on the value of r_pcrel. LEN_OFF16 is only meaningful if r_length==R_M78K and r_pcrel==1. It means that the reference is to the low 16 bits of the 32-bit word (stored MSB) at this location. The value to be stored here must be shifted right two bits, and the loader should check that those discarded two bits are zeros. Printed 3/13/89 6
A.OUT(5) COMMAND REFERENCE A.OUT(5) LEN_OFF26 is only meaningful if r_length==R_M78K and r_pcrel==1. It means that the reference is to the low 26 bits of the 32-bit word (stored MSB) at this location. The value to be stored here must be shifted right two bits, and the loader should check that those discarded two bits are zeros. LEN_LOW16 is only meaningful if r_length==R_M78K and r_pcrel==0. It means that the reference is to the unsigned short stored in the low 16 bits of the 32-bit word (stored MSB) at this location, and that this is a M78k "lit16" field. The loader should add the relocation factor and store the low 16 bits of the result, discarding the high 16 bits and not flagging any overflow. LEN_HIGH16 is only meaningful if r_length==R_M78K and r_pcrel==0. It means that the reference is to the unsigned short stored in the low 16 bits of the 32-bit word (stored MSB) at this location, and that this is a M78k "lit16" field. If r_extern==0, then the low 16 bits of the 32-bit argument to the assembler hi16 function are stored in the high 16 bits of r_symbolnum. The loader should add the relocation factor and store the high 16 bits of the result, discarding the low 16 bits. LEN_LIT16 is only meaningful if r_length==R_M78K and r_pcrel==0. It means that the reference is to the unsigned short stored in the low 16 bits of the 32-bit word (stored MSB) at this location, and that this is a M78k "lit16" field. The loader should check that, after adding the relocation factor, the result fits in 16 bits (i.e., it should flag overflow). This is equivalent to r_byteorder==R_MSB && r_length==1 (a 16-bit word) but may be extended to permit the loader to perform code synthesis, i.e., to insert instructions to calculate at runtime a value greater than 16 bits when the lit16 field would overflow. LEN_2LIT16 is only meaningful if r_length==R_M78K and r_pcrel==0. It means that the reference is to two 16-bit fields in the low halves of two 32-bit words at this location and at this location +4, and that these are M78k "lit16" fields, to be interpreted as the high order and low order, respectively, 16-bit halves of a 32 bit word. That word is to be relocated. CAVEATS A previous file format, NMAGIC (0410), is no longer supported since it has no advantage over ZMAGIC format and has several disadvantages. Old NMAGIC files work in the current release of UTek, but may not be supported by a future release. Printed 3/13/89 7
A.OUT(5) COMMAND REFERENCE A.OUT(5) SEE ALSO adb(1), as(1), ld(1), nm(1), strip(1), stab(5). Printed 3/13/89 8
%%index%% na:264,92; sy:356,284; de:640,2346;3322,2907;6565,2791;9692,2294;12322,2490;15148,2549;18033,2441; ca:20474,343; se:21153,230; %%index%%000000000160