diff options
Diffstat (limited to 'share/man/man5/a.out.5')
| -rw-r--r-- | share/man/man5/a.out.5 | 456 |
1 files changed, 456 insertions, 0 deletions
diff --git a/share/man/man5/a.out.5 b/share/man/man5/a.out.5 new file mode 100644 index 0000000..aa4c7da --- /dev/null +++ b/share/man/man5/a.out.5 @@ -0,0 +1,456 @@ +.\" Copyright (c) 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This manual page is derived from documentation contributed to Berkeley by +.\" Donn Seeley at UUNET Technologies, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)a.out.5 8.1 (Berkeley) 6/5/93 +.\" $FreeBSD$ +.\" +.Dd June 10, 2010 +.Dt A.OUT 5 +.Os +.Sh NAME +.Nm a.out +.Nd format of executable binary files +.Sh SYNOPSIS +.In a.out.h +.Sh DESCRIPTION +The include file +.In a.out.h +declares three structures and several macros. +The structures describe the format of +executable machine code files +.Pq Sq binaries +on the system. +.Pp +A binary file consists of up to 7 sections. +In order, these sections are: +.Bl -tag -width "text relocations" +.It exec header +Contains parameters used by the kernel +to load a binary file into memory and execute it, +and by the link editor +.Xr ld 1 +to combine a binary file with other binary files. +This section is the only mandatory one. +.It text segment +Contains machine code and related data +that are loaded into memory when a program executes. +May be loaded read-only. +.It data segment +Contains initialized data; always loaded into writable memory. +.It text relocations +Contains records used by the link editor +to update pointers in the text segment when combining binary files. +.It data relocations +Like the text relocation section, but for data segment pointers. +.It symbol table +Contains records used by the link editor +to cross reference the addresses of named variables and functions +.Pq Sq symbols +between binary files. +.It string table +Contains the character strings corresponding to the symbol names. +.El +.Pp +Every binary file begins with an +.Fa exec +structure: +.Bd -literal -offset indent +struct exec { + unsigned long a_midmag; + unsigned long a_text; + unsigned long a_data; + unsigned long a_bss; + unsigned long a_syms; + unsigned long a_entry; + unsigned long a_trsize; + unsigned long a_drsize; +}; +.Ed +.Pp +The fields have the following functions: +.Bl -tag -width a_trsize +.It Fa a_midmag +This field is stored in host byte-order. +It has a number of sub-components accessed by the macros +.Fn N_GETFLAG , +.Fn N_GETMID , +and +.Fn N_GETMAGIC , +and set by the macro +.Fn N_SETMAGIC . +.Pp +The macro +.Fn N_GETFLAG +returns a few flags: +.Bl -tag -width EX_DYNAMIC +.It Dv EX_DYNAMIC +indicates that the executable requires the services of the run-time link editor. +.It Dv EX_PIC +indicates that the object contains position independent code. +This flag is +set by +.Xr as 1 +when given the +.Sq -k +flag and is preserved by +.Xr ld 1 +if necessary. +.El +.Pp +If both EX_DYNAMIC and EX_PIC are set, the object file is a position independent +executable image (e.g.\& a shared library), which is to be loaded into the +process address space by the run-time link editor. +.Pp +The macro +.Fn N_GETMID +returns the machine-id. +This indicates which machine(s) the binary is intended to run on. +.Pp +.Fn N_GETMAGIC +specifies the magic number, which uniquely identifies binary files +and distinguishes different loading conventions. +The field must contain one of the following values: +.Bl -tag -width ZMAGIC +.It Dv OMAGIC +The text and data segments immediately follow the header +and are contiguous. +The kernel loads both text and data segments into writable memory. +.It Dv NMAGIC +As with +.Dv OMAGIC , +text and data segments immediately follow the header and are contiguous. +However, the kernel loads the text into read-only memory +and loads the data into writable memory at the next +page boundary after the text. +.It Dv ZMAGIC +The kernel loads individual pages on demand from the binary. +The header, text segment and data segment are all +padded by the link editor to a multiple of the page size. +Pages that the kernel loads from the text segment are read-only, +while pages from the data segment are writable. +.El +.It Fa a_text +Contains the size of the text segment in bytes. +.It Fa a_data +Contains the size of the data segment in bytes. +.It Fa a_bss +Contains the number of bytes in the +.Sq bss segment +and is used by the kernel to set the initial break +.Pq Xr brk 2 +after the data segment. +The kernel loads the program so that this amount of writable memory +appears to follow the data segment and initially reads as zeroes. +.Em ( bss += block started by symbol) +.It Fa a_syms +Contains the size in bytes of the symbol table section. +.It Fa a_entry +Contains the address in memory of the entry point +of the program after the kernel has loaded it; +the kernel starts the execution of the program +from the machine instruction at this address. +.It Fa a_trsize +Contains the size in bytes of the text relocation table. +.It Fa a_drsize +Contains the size in bytes of the data relocation table. +.El +.Pp +The +.In a.out.h +include file defines several macros which use an +.Fa exec +structure to test consistency or to locate section offsets in the binary file. +.Bl -tag -width N_BADMAG(exec) +.It Fn N_BADMAG exec +Nonzero if the +.Fa a_magic +field does not contain a recognized value. +.It Fn N_TXTOFF exec +The byte offset in the binary file of the beginning of the text segment. +.It Fn N_SYMOFF exec +The byte offset of the beginning of the symbol table. +.It Fn N_STROFF exec +The byte offset of the beginning of the string table. +.El +.Pp +Relocation records have a standard format which +is described by the +.Fa relocation_info +structure: +.Bd -literal -offset indent +struct relocation_info { + int r_address; + unsigned int r_symbolnum : 24, + r_pcrel : 1, + r_length : 2, + r_extern : 1, + r_baserel : 1, + r_jmptable : 1, + r_relative : 1, + r_copy : 1; +}; +.Ed +.Pp +The +.Fa relocation_info +fields are used as follows: +.Bl -tag -width r_symbolnum +.It Fa r_address +Contains the byte offset of a pointer that needs to be link-edited. +Text relocation offsets are reckoned from the start of the text segment, +and data relocation offsets from the start of the data segment. +The link editor adds the value that is already stored at this offset +into the new value that it computes using this relocation record. +.It Fa r_symbolnum +Contains the ordinal number of a symbol structure +in the symbol table (it is +.Em not +a byte offset). +After the link editor resolves the absolute address for this symbol, +it adds that address to the pointer that is undergoing relocation. +(If the +.Fa r_extern +bit is clear, the situation is different; see below.) +.It Fa r_pcrel +If this is set, +the link editor assumes that it is updating a pointer +that is part of a machine code instruction using pc-relative addressing. +The address of the relocated pointer is implicitly added +to its value when the running program uses it. +.It Fa r_length +Contains the log base 2 of the length of the pointer in bytes; +0 for 1-byte displacements, 1 for 2-byte displacements, +2 for 4-byte displacements. +.It Fa r_extern +Set if this relocation requires an external reference; +the link editor must use a symbol address to update the pointer. +When the +.Fa r_extern +bit is clear, the relocation is +.Sq local ; +the link editor updates the pointer to reflect +changes in the load addresses of the various segments, +rather than changes in the value of a symbol (except when +.Fa r_baserel +is also set (see below). +In this case, the content of the +.Fa r_symbolnum +field is an +.Fa n_type +value (see below); +this type field tells the link editor +what segment the relocated pointer points into. +.It Fa r_baserel +If set, the symbol, as identified by the +.Fa r_symbolnum +field, is to be relocated to an offset into the Global Offset Table. +At run-time, the entry in the Global Offset Table at this offset is set to +be the address of the symbol. +.It Fa r_jmptable +If set, the symbol, as identified by the +.Fa r_symbolnum +field, is to be relocated to an offset into the Procedure Linkage Table. +.It Fa r_relative +If set, this relocation is relative to the (run-time) load address of the +image this object file is going to be a part of. +This type of relocation +only occurs in shared objects. +.It Fa r_copy +If set, this relocation record identifies a symbol whose contents should +be copied to the location given in +.Fa r_address . +The copying is done by the run-time link-editor from a suitable data +item in a shared object. +.El +.Pp +Symbols map names to addresses (or more generally, strings to values). +Since the link-editor adjusts addresses, +a symbol's name must be used to stand for its address +until an absolute value has been assigned. +Symbols consist of a fixed-length record in the symbol table +and a variable-length name in the string table. +The symbol table is an array of +.Fa nlist +structures: +.Bd -literal -offset indent +struct nlist { + union { + const char *n_name; + long n_strx; + } n_un; + unsigned char n_type; + char n_other; + short n_desc; + unsigned long n_value; +}; +.Ed +.Pp +The fields are used as follows: +.Bl -tag -width n_un.n_strx +.It Fa n_un.n_strx +Contains a byte offset into the string table +for the name of this symbol. +When a program accesses a symbol table with the +.Xr nlist 3 +function, +this field is replaced with the +.Fa n_un.n_name +field, which is a pointer to the string in memory. +.It Fa n_type +Used by the link editor to determine +how to update the symbol's value. +The +.Fa n_type +field is broken down into three sub-fields using bitmasks. +The link editor treats symbols with the +.Dv N_EXT +type bit set as +.Sq external +symbols and permits references to them from other binary files. +The +.Dv N_TYPE +mask selects bits of interest to the link editor: +.Bl -tag -width N_TEXT +.It Dv N_UNDF +An undefined symbol. +The link editor must locate an external symbol with the same name +in another binary file to determine the absolute value of this symbol. +As a special case, if the +.Fa n_value +field is nonzero and no binary file in the link-edit defines this symbol, +the link-editor will resolve this symbol to an address +in the bss segment, +reserving an amount of bytes equal to +.Fa n_value . +If this symbol is undefined in more than one binary file +and the binary files do not agree on the size, +the link editor chooses the greatest size found across all binaries. +.It Dv N_ABS +An absolute symbol. +The link editor does not update an absolute symbol. +.It Dv N_TEXT +A text symbol. +This symbol's value is a text address and +the link editor will update it when it merges binary files. +.It Dv N_DATA +A data symbol; similar to +.Dv N_TEXT +but for data addresses. +The values for text and data symbols are not file offsets but +addresses; to recover the file offsets, it is necessary +to identify the loaded address of the beginning of the corresponding +section and subtract it, then add the offset of the section. +.It Dv N_BSS +A bss symbol; like text or data symbols but +has no corresponding offset in the binary file. +.It Dv N_FN +A filename symbol. +The link editor inserts this symbol before +the other symbols from a binary file when +merging binary files. +The name of the symbol is the filename given to the link editor, +and its value is the first text address from that binary file. +Filename symbols are not needed for link-editing or loading, +but are useful for debuggers. +.El +.Pp +The +.Dv N_STAB +mask selects bits of interest to symbolic debuggers +such as +.Xr gdb 1 ; +the values are described in +.Xr stab 5 . +.It Fa n_other +This field provides information on the nature of the symbol independent of +the symbol's location in terms of segments as determined by the +.Fa n_type +field. +Currently, the lower 4 bits of the +.Fa n_other +field hold one of two values: +.Dv AUX_FUNC +and +.Dv AUX_OBJECT +(see +.In link.h +for their definitions). +.Dv AUX_FUNC +associates the symbol with a callable function, while +.Dv AUX_OBJECT +associates the symbol with data, irrespective of their locations in +either the text or the data segment. +This field is intended to be used by +.Xr ld 1 +for the construction of dynamic executables. +.It Fa n_desc +Reserved for use by debuggers; passed untouched by the link editor. +Different debuggers use this field for different purposes. +.It Fa n_value +Contains the value of the symbol. +For text, data and bss symbols, this is an address; +for other symbols (such as debugger symbols), +the value may be arbitrary. +.El +.Pp +The string table consists of an +.Em unsigned long +length followed by null-terminated symbol strings. +The length represents the size of the entire table in bytes, +so its minimum value (or the offset of the first string) +is always 4 on 32-bit machines. +.Sh SEE ALSO +.Xr as 1 , +.Xr gdb 1 , +.Xr ld 1 , +.Xr brk 2 , +.Xr execve 2 , +.Xr nlist 3 , +.Xr core 5 , +.Xr elf 5 , +.Xr link 5 , +.Xr stab 5 +.Sh HISTORY +The +.In a.out.h +include file appeared in +.At v7 . +.Sh BUGS +Since not all of the supported architectures use the +.Fa a_midmag +field, +it can be difficult to determine what +architecture a binary will execute on +without examining its actual machine code. +Even with a machine identifier, +the byte order of the +.Fa exec +header is machine-dependent. |
